Autark

Appearance

@urban-toolkit/autk-db

@urban-toolkit/autk-db / AutkDb

Class: AutkDb ​

Defined in: db.ts:65

DuckDB-backed spatial database for loading, querying, and managing urban datasets.

Supports multiple isolated workspaces, each with its own schema, registered tables, and cached spatial metadata.

Throws ​

Never throws. Initialization happens later via init().

Example ​

ts
const db = new AutkDb();
await db.init();
await db.loadOsm({
  queryArea: { geocodeArea: 'New York', areas: ['Manhattan Island'] },
  autoLoadLayers: { layers: ['buildings', 'roads', 'parks', 'water'] },
});

Constructors ​

Constructor ​

new AutkDb(): AutkDb

Returns ​

AutkDb

Methods ​

buildHeatmap() ​

buildHeatmap(params): Promise<Table>

Defined in: db.ts:981

Builds a heatmap table by creating a grid internally and aggregating source values into its cells.

Uses the cached workspace bounding box as the grid extent, runs a NEAR spatial aggregation into the generated grid, then rewrites the result as raster-band properties.

Parameters ​

params ​

BuildHeatmapParams

Source table, NEAR settings, grid configuration, and aggregation method.

Returns ​

Promise<Table>

The resulting heatmap table metadata.

Throws ​

If the database is not initialized, if the workspace has no bounding box, or if the source table is missing.

Example ​

ts
const heatmap = await db.buildHeatmap({
  tableJoinName: 'incidents',
  near: { distance: 500 },
  outputTableName: 'heatmap_result',
  grid: { rows: 50, columns: 50 },
  groupBy: [{ column: '*', aggregateFn: 'count' }],
});

getBoundingBoxFromLayer() ​

getBoundingBoxFromLayer(layerName): Promise<BoundingBox>

Defined in: db.ts:769

Computes the bounding box of a layer from its geometry column.

Parameters ​

layerName ​

string

Name of the layer table.

Returns ​

Promise<BoundingBox>

The layer bounding box.

Throws ​

If the database is not initialized, the table is missing, or it has no geometry column.

Example ​

ts
const bbox = await db.getBoundingBoxFromLayer('osm_buildings');
console.log(bbox.minLon, bbox.maxLon);

getCurrentWorkspace() ​

getCurrentWorkspace(): string

Defined in: db.ts:274

Returns the name of the workspace currently selected for operations.

This value changes when setWorkspace() succeeds.

Returns ​

string

Current workspace name.

Throws ​

Never throws.

Example ​

ts
console.log(db.getCurrentWorkspace()); // 'autk'

getLayer() ​

getLayer(layerTableName, options?): Promise<FeatureCollection<Geometry, GeoJsonProperties>>

Defined in: db.ts:722

Exports a loaded layer as a GeoJSON FeatureCollection with an automatically computed bounding box.

The bbox is resolved from the immutable workspace bounds, then the layer's own bounds.

Parameters ​

layerTableName ​

string

Name of the layer table to export.

options? ​

GetLayerOptions = {}

Optional per-OSM-element export with preserved source tags and typed IDs.

Returns ​

Promise<FeatureCollection<Geometry, GeoJsonProperties>>

A FeatureCollection with bbox when workspace or nonempty layer bounds are available.

Throws ​

If the database is not initialized, the table is missing, or it is not a layer table.

Example ​

ts
const buildings = await db.getLayer('osm_buildings');
map.loadCollection('buildings', { collection: buildings, type: 'buildings' });

getLayersMetadata() ​

getLayersMetadata(): (Table & object)[]

Defined in: db.ts:804

Returns metadata for all vector layers in the current workspace.

Returns ​

(Table & object)[]

Filtered array of vector layer metadata.

Throws ​

If the active workspace is missing from the internal registry.

Example ​

ts
const layers = db.getLayersMetadata();
for (const l of layers) await map.loadCollection(l.name, { collection: await db.getLayer(l.name), type: l.type });

getRaster() ​

getRaster(tableName): Promise<FeatureCollection<null, GeoJsonProperties>>

Defined in: db.ts:698

Exports a compact raster table as a packed raster FeatureCollection for rendering.

This applies to GeoTIFF rasters and compact heatmap rasters. The returned feature contains flat band arrays (band_1, band_2, ...) and raster resolution metadata. Pass one of the band ids as the raster property selector in AutkMap.loadCollection().

Parameters ​

tableName ​

string

Name of the compact raster table.

Returns ​

Promise<FeatureCollection<null, GeoJsonProperties>>

A FeatureCollection with a single feature containing flat band arrays and resolution metadata.

Throws ​

If the database is not initialized, the table is missing, or it is not a compact raster table.

Example ​

ts
const fc = await db.getRaster('temperature');
map.loadCollection('temperature', {
  collection: fc,
  type: 'raster',
  property: 'band_1',
});

getRastersMetadata() ​

getRastersMetadata(): (Table & object)[]

Defined in: db.ts:816

Returns metadata for all raster tables in the current workspace.

Returns ​

(Table & object)[]

Filtered array of raster table metadata.

Throws ​

If the active workspace is missing from the internal registry.

getTable() ​

getTable(tableName): Promise<GetTableOutput>

Defined in: db.ts:832

Reads all rows from a table as plain JavaScript objects.

Parameters ​

tableName ​

string

Table name.

Returns ​

Promise<GetTableOutput>

Array of plain objects where each object represents one row.

Throws ​

If the database is not initialized or the table is not found.

Example ​

ts
const rows = await db.getTable('stations');
console.log(rows[0]);

getTablesMetadata() ​

getTablesMetadata(): Table[]

Defined in: db.ts:146

Returns metadata for all tables in the current workspace.

Exposes the live table registry for the active workspace without querying DuckDB again.

Returns ​

Table[]

Array of table metadata objects for the current workspace.

Throws ​

If the active workspace is missing from the internal registry.

Example ​

ts
const tables = db.getTablesMetadata();
console.log(tables.map((table) => table.name));

getWorkspaceConfiguration() ​

getWorkspaceConfiguration(): WorkspaceConfiguration

Defined in: db.ts:283

Returns the CRS and precision grid used for stored vectors and spatial results in the active workspace.

Returns ​

WorkspaceConfiguration

A copy of the active workspace configuration.

getWorkspaces() ​

getWorkspaces(): string[]

Defined in: db.ts:260

Returns the names of all workspaces known to this instance.

Uses the in-memory workspace registry rather than discovering schemas from DuckDB.

Returns ​

string[]

Array of registered workspace names.

Throws ​

Never throws.

Example ​

ts
const names = db.getWorkspaces();
console.log(names); // ['autk', 'analysis-a']

init() ​

init(): Promise<void>

Defined in: db.ts:161

Initializes DuckDB and the spatial extension for use by the database wrapper.

Must be called before any other database operation so workspaces, use cases, and the shared connection are ready.

Returns ​

Promise<void>

Resolves when DuckDB, the spatial extension, and the default workspace have been initialized.

Throws ​

If DuckDB WebAssembly fails to load, the connection cannot be opened, or the spatial extension cannot be installed.

Example ​

ts
const db = new AutkDb();
await db.init();

loadCsv() ​

loadCsv(params): Promise<CsvTable>

Defined in: db.ts:547

Loads a CSV file into the database, optionally creating geometry from coordinate or WKT columns.

Supports the default Latitude / Longitude shorthand, custom lat/lng column names, or a single WKT geometry column.

Parameters ​

params ​

LoadCsvParams

File URL or array, table name, and optional geometry column mapping.

Returns ​

Promise<CsvTable>

The created CSV table metadata.

Throws ​

If the database is not initialized, both csvFileUrl and csvObject are provided, geometry creation fails, or WKT geometry families are mixed.

Example ​

ts
const table = await db.loadCsv({
  csvFileUrl: '/data/stations.csv',
  outputTableName: 'stations',
  geometryColumns: true,
});

loadGeojson() ​

loadGeojson(params): Promise<GeojsonTable>

Defined in: db.ts:631

Loads a GeoJSON FeatureCollection as a spatial layer, optionally auto-clipping to the workspace bbox when OSM data is present.

Building features keep their own identity and original parts; independent GeoJSON features are never clustered merely because their geometries overlap.

Parameters ​

params ​

LoadGeojsonParams

File URL or object, table name, and layer type.

Returns ​

Promise<GeojsonTable>

The created custom layer table metadata.

Throws ​

If the database is not initialized, or the GeoJSON is not a FeatureCollection.

Example ​

ts
const neighborhoods = await db.loadGeojson({
  geojsonFileUrl: '/data/neighborhoods.geojson',
  outputTableName: 'neighborhoods',
  layerType: 'parks',
});

loadGeoTiff() ​

loadGeoTiff(params): Promise<GeotiffTable>

Defined in: db.ts:661

Loads a GeoTIFF raster as a compact raster table with metadata and flat in-memory band arrays.

Large rasters are downsampled when needed so browser memory use stays bounded.

Parameters ​

params ​

LoadGeoTiffParams

File URL or ArrayBuffer, table name, and optional CRS override.

Returns ​

Promise<GeotiffTable>

The created GeoTIFF table metadata.

Throws ​

If the database is not initialized or if the input sources are invalid.

Example ​

ts
const raster = await db.loadGeoTiff({
  geotiffFileUrl: '/data/lst.tif',
  outputTableName: 'temperature',
});

loadJson() ​

loadJson(params): Promise<JsonTable>

Defined in: db.ts:573

Loads a JSON array into the database, optionally creating geometry from coordinate or WKT fields.

Supports the default Latitude / Longitude shorthand, custom lat/lng field names, or a single WKT geometry field.

Parameters ​

params ​

LoadJsonParams

File URL or array, table name, and optional geometry field mapping.

Returns ​

Promise<JsonTable>

The created JSON table metadata, including a renderable type when geometry is materialized.

Throws ​

If the database is not initialized, both jsonFileUrl and jsonObject are provided, or geometry creation fails.

Example ​

ts
const table = await db.loadJson({
  jsonFileUrl: '/data/events.json',
  outputTableName: 'events',
  geometryColumns: { wktColumnName: 'wkt' },
});

loadOsm() ​

loadOsm(params): Promise<OsmLoadTimings>

Defined in: db.ts:311

Loads OpenStreetMap data from the Overpass API or a PBF file and extracts thematic layers.

autoLoadLayers is required. The raw OSM import tables are treated as temporary staging tables and are always dropped after the requested layers are extracted. Surface is always built, excluding sea when coastline reconstruction succeeds. Named coastlines use the geocode bbox, not only the selected areas. Requested water also includes bbox(areas) minus classified land, marked generated=coastline. Missing/invalid coastal data never generates presumed sea. Surface stays hidden unless requested; other layers/tag sets use it as a crop. Building parts remain uncut; parts not fully covered by the surface are discarded and survivors reindexed.

Parameters ​

params ​

LoadOsmParams

Area query, optional output table name, and required layer extraction settings.

Returns ​

Promise<OsmLoadTimings>

Timing breakdown for OSM download and layer extraction.

Throws ​

If the database is not initialized.

Example ​

ts
const timings = await db.loadOsm({
  queryArea: { geocodeArea: 'New York', areas: ['Manhattan Island'] },
  autoLoadLayers: {
    layers: ['buildings', 'roads', 'surface'],
  },
});

rawQuery() ​

rawQuery<T>(params): Promise<Table | T>

Defined in: db.ts:925

Executes arbitrary SQL against the current workspace.

Type Parameters ​

T ​

T = RawQueryOutput

Parameters ​

params ​

RawQueryParams

SQL query string and optional output configuration to create a table from the result.

Returns ​

Promise<Table | T>

The raw query result, or a Table if output.type is 'CREATE_TABLE'.

Throws ​

If the database is not initialized.

Example ​

ts
const result = await db.rawQuery({
  query: 'SELECT COUNT(*) as cnt FROM manhattan_buildings',
});

removeLayer() ​

removeLayer(tableName): Promise<void>

Defined in: db.ts:946

Drops a table from DuckDB and unregisters it from the active workspace.

Keeps the in-memory workspace registry aligned with the physical schema after a table is removed.

Parameters ​

tableName ​

string

Name of the table to remove.

Returns ​

Promise<void>

Resolves when the table has been dropped and unregistered.

Throws ​

If the database is not initialized.

Example ​

ts
await db.removeLayer('osm_raw');

setWorkspace() ​

setWorkspace(name, configuration?): Promise<void>

Defined in: db.ts:217

Switches to a workspace, creating its schema and cache entry if needed.

Updates both the active DuckDB schema and the in-memory workspace registry used by this instance.

Parameters ​

name ​

string

The name of the workspace to activate.

configuration? ​

WorkspaceConfiguration

Optional CRS and precision grid. Both values are required together.

Returns ​

Promise<void>

Resolves when the workspace has been created if necessary and set as active.

Throws ​

If the database has not been initialized, configuration is invalid, or existing tables would change CRS.

Example ​

ts
await db.setWorkspace('my-analysis', { coordinateFormat: 'EPSG:3395', precisionGrid: 0.01 });
await db.loadCsv({ csvFileUrl: '/data.csv', outputTableName: 'points' });

spatialQuery() ​

spatialQuery(params): Promise<Table>

Defined in: db.ts:903

Performs a spatial join between two tables using predicates like INTERSECT or NEAR.

The join always modifies the root table in place using a LEFT join.

Parameters ​

params ​

SpatialQueryParams

Root and join table names, spatial predicate, optional near distance, and optional grouping.

Returns ​

Promise<Table>

The updated root table.

Throws ​

If the database is not initialized.

Example ​

ts
await db.spatialQuery({
  tableRootName: 'roads',
  tableJoinName: 'lst',
  near: { distance: 1000 },
});

updateTable() ​

updateTable(params): Promise<Table>

Defined in: db.ts:855

Updates an existing table with new data using a replace or record-level update strategy.

Parameters ​

params ​

Omit<UpdateTableParams, "workspace">

Table name, data, strategy ('replace' or 'update'), and optional idColumn for update strategy.

Returns ​

Promise<Table>

The updated table with refreshed column metadata.

Throws ​

If the database is not initialized, the table is missing, or idColumn is required but omitted.

Example ​

ts
await db.updateTable({
  tableName: 'stations',
  data: updatedRows,
  strategy: 'replace',
});

Released under the MIT License.

2026 Autark

Developed at