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 must be a vector table and receives the result; the join table provides matching vector features or compact raster cells.

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 workspace CRS units. For example, when the data uses EPSG:3395, distances are measured in meters.

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

Raster joins

In v4.1.1, a compact raster can be tableJoinName. Each decoded cell contributes its center transformed to the workspace CRS; joins do not compute pixel-area intersections. Numeric aggregates ignore NoData values. Reload the raster before joining if its in-memory payload is unavailable.

Aggregate keys can contain dots, such as shadows.jun. Property paths such as properties.sjoin.avg.shadows.jun resolve these literal dotted keys, while fully traversable nested paths take precedence.

Centroid distance versus geometry distance

near.useCentroid defaults to true: the distance test compares the centroids of the root and join geometries. Set it to false to measure the minimum distance between the geometries themselves.

For example, a long park can touch a district while their centroids are more than 250 meters apart. Geometry distance includes that park; centroid distance may exclude it. Both modes use the workspace CRS units, so choose the mode according to whether you care about centers or proximity to the actual shapes.

Without groupBy, each root feature remains a single row. Matches are written to properties.sjoin.matches as an array of { id?, properties } entries, so the root geometry is never duplicated. For example, matches from the noise table look like:

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

No match produces an empty matches array. When you need a scalar value for thematic rendering or charting, use groupBy to aggregate the matches.

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.