Analyzing data

Once data is loaded into DuckDB, autk-db provides methods for spatial analysis and custom SQL queries. Analysis methods update existing tables or create new ones. To inspect the results, use one of the retrieving data methods.

Spatial queries

spatialQuery performs a spatial join between two tables. The root table is always modified in place, and the joined values are written into properties.sjoin.

1. tableRootName and tableJoinName — The two tables involved in the join. The root table receives the result; the join table provides the matching features.

2. near — Optional NEAR predicate configuration. When provided, spatialQuery matches features that lie within the specified distance of the root geometries. If omitted, the query uses INTERSECT and only matches features whose geometries overlap.

Units depend on projection

near.distance is interpreted in the native units of the loaded geometries. For example, when the data uses EPSG:3395, distances are measured in meters.

3. groupBy — Optional aggregation rules applied to the join-side data.

Regarding the output format, each matched feature is written directly under properties.sjoin, which can produce multiple rows for the same root feature. For example, if the matched features in the noise table contain properties such as key and date, those same properties are copied into properties.sjoin.

{
  "properties": {
    "sjoin": { "key": 1, "date": "03/31/2025 11:17:00 PM" }
  }
}

The groupBy output

Grouping summarizes the matched features instead of returning one join result per match. Aggregated values are written into properties.sjoin.<aggregateFn>.<key>.

When groupBy is used, the matched features are aggregated before being written under properties.sjoin.<aggregateFn>.<key>. As a result, the spatial query returns a single summarized row for each root feature.

{
  "properties": {
    "sjoin": {
      "count": { "noise": 42 }
    }
  }
}

Normalization

When normalize: true is set, the aggregated value is normalized between 0 and 1.

List of spatialQuery parameters

Option	Type	Description
tableRootName	string	Root table name.
tableJoinName	string	Join table name.
near distance	number	NEAR distance.
groupBy columnaggregateFnnormalize	stringAggregateFunctionboolean	Aggregation column.Aggregation function.Normalize to 0–1.

Build heatmap

buildHeatmap creates a grid over the current workspace bounds and aggregates values from a source table into each grid cell.

Workspace bounds

buildHeatmap is built based on workspace bounding box. In practice, this usually comes from previously loaded OSM or GeoJSON layers (see Loading data).

List of buildHeatmap parameters

Option	Type	Description
tableJoinName	string	Source table name.
outputTableName	string	Output table name.
near distance	number	NEAR distance.
grid rowscolumns	numbernumber	Grid rows.Grid columns.
groupBy columnaggregateFn	stringHeatmapAggregateFunction	Aggregation column.Band aggregation.

Raw SQL

While spatialQuery and buildHeatmap cover common spatial analysis patterns, Autark also provides rawQuery, which gives direct access to DuckDB SQL to run custom queries against the current workspace.

The output parameter controls how the query result is returned. Use type: 'RETURN_OBJECT' when you want the selected rows back as plain JavaScript objects. Use type: 'CREATE_TABLE' when you want to register the query result as a new table inside the current workspace. In that case, you can also provide tableName and optional metadata such as source and tableType.

List of rawQuery parameters

Option	Type	Description
query	string	SQL query.
output typetableNamesourcetableType	"CREATE_TABLE" | "RETURN_OBJECT"stringTableSourceLayerType	Output mode.New table name.Result table source metadata.Result table type.

Raw query limitations

• Queries run against the current workspace only.
• rawQuery supports SELECT and WITH queries. Statements such as INSERT, UPDATE, DELETE, CREATE, ALTER, DROP, TRUNCATE, and REPLACE are rejected.