autk-db / SpatialDb
Class: SpatialDb
Defined in: SpatialDb.ts:44
SpatialDb class provides methods to interact with a DuckDB database for spatial data operations.
It allows loading OSM data, CSV, JSON, custom layers, and grid layers, as well as performing spatial joins and raw queries. It also provides methods to retrieve layer data and bounding boxes.
Supports multiple isolated workspaces, each with its own schema and data.
Constructors
Constructor
new SpatialDb():
SpatialDb
Returns
SpatialDb
Accessors
tables
Get Signature
get tables():
Table[]
Defined in: SpatialDb.ts:50
Returns
Table[]
Methods
buildHeatmap()
buildHeatmap(
params):Promise<Table>
Defined in: SpatialDb.ts:565
Builds a heatmap from spatial data by creating a grid and aggregating values. The heatmap is generated by creating a grid over the bounding box and aggregating values from the source table into each grid cell.
Parameters
params
BuildHeatmapParams
Parameters for building the heatmap, including source table, grid configuration, and aggregation method.
Returns
Promise<Table>
A promise that resolves to the resulting GridLayerTable containing the heatmap data.
Throws
Error if the database or connection is not initialized.
getBoundingBoxFromLayer()
getBoundingBoxFromLayer(
layerName):Promise<BoundingBox>
Defined in: SpatialDb.ts:408
Retrieves the bounding box of a layer by its table name.
Parameters
layerName
string
The name of the layer table to retrieve the bounding box from.
Returns
Promise<BoundingBox>
A promise that resolves to the bounding box of the layer.
Throws
Error if the database or connection is not initialized.
Throws
Error if the layer table is not found.
Throws
Error if the layer table does not have a geometry column.
getCurrentWorkspace()
getCurrentWorkspace():
string
Defined in: SpatialDb.ts:155
Gets the name of the current active workspace.
Returns
string
The current workspace name.
getLayer()
getLayer(
layerTableName):Promise<FeatureCollection<Geometry,GeoJsonProperties>>
Defined in: SpatialDb.ts:358
Retrieves the GeoJSON representation of a layer by its table name. The returned FeatureCollection will include a bbox property with the layer's bounding box.
Parameters
layerTableName
string
The name of the layer table to retrieve.
Returns
Promise<FeatureCollection<Geometry, GeoJsonProperties>>
A promise that resolves to the GeoJSON FeatureCollection of the layer with bbox.
Throws
Error if the database or connection is not initialized.
Throws
Error if the layer table is not found or is not a Layer table.
getLayerTables()
getLayerTables(): (
LayerTable|CustomLayerTable)[]
Defined in: SpatialDb.ts:433
Retrieves all layer tables (LayerTable and CustomLayerTable) from the loaded tables.
Returns
(LayerTable | CustomLayerTable)[]
An array of LayerTable and CustomLayerTable objects.
getOsmBoundingBox()
getOsmBoundingBox(): [
number,number,number,number] |null
Defined in: SpatialDb.ts:388
Retrieves the bounding box of the OSM data loaded from the Overpass API for the current workspace.
Returns
[number, number, number, number] | null
The bounding box as a tuple [minLon, minLat, maxLon, maxLat], or null if no OSM data has been loaded.
getTableData()
getTableData(
params):Promise<GetTableDataOutput>
Defined in: SpatialDb.ts:451
Retrieves the data from any table as an array of plain JavaScript objects. This method works with all table types (CSV, JSON, Layer, Grid, etc.).
Parameters
params
Parameters including table name and optional pagination (limit, offset).
Returns
Promise<GetTableDataOutput>
A promise that resolves to an array of objects representing the table rows.
Throws
Error if the database or connection is not initialized.
Throws
Error if the table is not found.
getWorkspaces()
getWorkspaces():
string[]
Defined in: SpatialDb.ts:147
Gets the list of all available workspaces.
Returns
string[]
An array of workspace names.
init()
init():
Promise<void>
Defined in: SpatialDb.ts:89
Initializes the SpatialDb instance by loading the DuckDB database and setting up use cases.
Returns
Promise<void>
A promise that resolves when initialization is complete.
loadCsv()
loadCsv(
params):Promise<CsvTable>
Defined in: SpatialDb.ts:256
Loads a CSV file into the database and returns the created CsvTable.
Parameters
params
Params
Parameters for loading the CSV file, including file path and table name.
Returns
Promise<CsvTable>
A promise that resolves to the created CsvTable.
Throws
Error if the database or connection is not initialized.
loadCustomLayer()
loadCustomLayer(
params):Promise<CustomLayerTable>
Defined in: SpatialDb.ts:311
Loads a custom layer from a GeoJSON file and returns the created CustomLayerTable. If OSM bounding box is available, it will be automatically applied to crop the layer.
Parameters
params
Params
Parameters for loading the custom layer, including file path, table name, and layer type.
Returns
Promise<CustomLayerTable>
A promise that resolves to the created CustomLayerTable.
Throws
Error if the database or connection is not initialized.
loadGridLayer()
loadGridLayer(
params):Promise<GridLayerTable>
Defined in: SpatialDb.ts:333
Loads a grid layer and returns the created GridLayerTable. If no bounding box is provided in params, the OSM bounding box will be used if available.
Parameters
params
LoadGridLayerParams
Parameters for loading the grid layer, including grid size, cell size, and optional bounding box.
Returns
Promise<GridLayerTable>
A promise that resolves to the created GridLayerTable.
Throws
Error if the database or connection is not initialized.
loadJson()
loadJson(
params):Promise<JsonTable>
Defined in: SpatialDb.ts:272
Loads a JSON file into the database and returns the created JsonTable.
Parameters
params
Params
Parameters for loading the JSON file, including file path and table name.
Returns
Promise<JsonTable>
A promise that resolves to the created JsonTable.
Throws
Error if the database or connection is not initialized.
loadLayer()
loadLayer(
params):Promise<LayerTable>
Defined in: SpatialDb.ts:289
Loads a layer from an OSM input table and returns the created LayerTable.
Parameters
params
Params
Parameters for loading the layer.
Returns
Promise<LayerTable>
A promise that resolves to the created LayerTable.
Throws
Error if the database or connection is not initialized.
Throws
Error if the OSM input table is not found or is not of the correct type.
loadOsmFromOverpassApi()
loadOsmFromOverpassApi(
params):Promise<void>
Defined in: SpatialDb.ts:187
Loads OSM data from the Overpass API and optionally loads layers based on the provided parameters. When autoLoadLayers is enabled, this method will automatically extract and process specific layers (e.g., buildings, roads, surface) from the OSM data, and optionally polygonize the surface layer.
Parameters
params
Params
Parameters for loading OSM data and layers.
Returns
Promise<void>
A promise that resolves when the OSM data and layers are fully loaded.
Throws
Error if the database or connection is not initialized.
rawQuery()
rawQuery<
T>(params):Promise<Table|T>
Defined in: SpatialDb.ts:528
Executes a raw SQL query and returns the result.
Type Parameters
T
T = RawQueryOutput
Parameters
params
RawQueryParams
Parameters for the raw query, including the SQL query string and output type.
Returns
Promise<Table | T>
A promise that resolves to a Table if output type is 'CREATE_TABLE', otherwise returns the query result of type T.
Throws
Error if the database or connection is not initialized.
removeLayer()
removeLayer(
tableName):Promise<void>
Defined in: SpatialDb.ts:548
Drops a table from the database and removes it from the current workspace.
Parameters
tableName
string
The name of the table to remove.
Returns
Promise<void>
A promise that resolves when the table has been dropped.
Throws
Error if the database or connection is not initialized.
setWorkspace()
setWorkspace(
name):Promise<void>
Defined in: SpatialDb.ts:127
Sets the current workspace. If the workspace doesn't exist, it will be created.
Parameters
name
string
The name of the workspace to switch to.
Returns
Promise<void>
A promise that resolves when the workspace is set.
spatialJoin()
spatialJoin(
params):Promise<Table>
Defined in: SpatialDb.ts:510
Performs a spatial join between two tables and returns the resulting table. The method can either create a new table or update an existing one based on the parameters.
Parameters
params
SpatialJoinParams
Parameters for the spatial join operation, including source and target tables, join type, and output table name.
Returns
Promise<Table>
A promise that resolves to the resulting table after the spatial join.
Throws
Error if the database or connection is not initialized.
updateTable()
updateTable(
params):Promise<Table>
Defined in: SpatialDb.ts:479
Updates an existing table with new data.
For layer tables (OSM, GeoJSON), the input data should be a GeoJSON FeatureCollection. For non-layer tables (CSV, JSON), the input data should be an array of objects.
Parameters
params
Omit<UpdateTableParams, "workspace">
Parameters for updating the table:
- tableName: The name of the table to update
- data: The new data (FeatureCollection for layers,
Record<string, unknown>[]for CSV/JSON) - strategy: 'replace' (drop and recreate) or 'update' (update existing records by ID)
- idColumn: Required for 'update' strategy. Supports 'id' or 'properties.attribute_name' format
Returns
Promise<Table>
A promise that resolves to the updated Table with refreshed column metadata.
Throws
Error if the database or connection is not initialized.
Throws
Error if the table is not found.
Throws
Error if idColumn is not provided when using 'update' strategy.
