GeoPackage

A GeoPackage object represents an open connection to a single GeoPackage (.gpkg) SQLite database. You never construct one directly — obtain an instance from GeoPackageManager.open() or GeoPackageManager.create().

Always call geoPackage.close() when you have finished working with the database. Failing to do so leaks the underlying SQLite file handle.

Table management

getFeatureTables()

Returns the names of all feature (vector) tables registered in the GeoPackage.

getFeatureTables(): string[]

const tables = geoPackage.getFeatureTables();
// ['countries', 'cities']

getTileTables()

Returns the names of all tile (raster) tables registered in the GeoPackage.

getTileTables(): string[]

getAttributesTables()

Returns the names of all attributes tables registered in the GeoPackage.

getAttributesTables(): string[]

getTables()

Returns the names of all content tables, optionally filtered by data type.

getTables(type?: ContentsDataType): string[]

type

ContentsDataType

Optional data type filter. Omit to return all tables regardless of type.

hasFeatureTable()

Returns true if a feature table with the given name exists.

hasFeatureTable(featureTableName: string): boolean

featureTableName

string

required

The name of the feature table to check.

hasTileTable()

Returns true if a tile table with the given name exists.

hasTileTable(tileTableName: string): boolean

tileTableName

string

required

The name of the tile table to check.

getInfoForTable()

Returns a plain object with summary information about a feature or tile table — row count, geometry column details (features), zoom range (tiles), contents metadata, SRS info, and a column map.

getInfoForTable(tableDao: TileDao | FeatureDao): object

tableDao

TileDao | FeatureDao

required

A DAO instance obtained from getTileDao() or getFeatureDao().

const dao = geoPackage.getFeatureDao('countries');
const info = geoPackage.getInfoForTable(dao);
console.log(info.count);               // row count
console.log(info.geometryColumns);     // geometry column metadata
console.log(info.columns);            // array of column descriptors

Feature access

getFeatureDao()

Returns a FeatureDao for the named feature table. Use the DAO to iterate rows, query by geometry, add or update features, and more.

getFeatureDao(tableName: string): FeatureDao

tableName

string

required

Name of the feature table.

FeatureDao

Data-access object for the feature table.

Errors thrown

GeoPackageException — no feature table with that name exists, or GeometryColumns could not be retrieved.

const featureDao = geoPackage.getFeatureDao('countries');
const resultSet = featureDao.queryForAll();
try {
  while (resultSet.moveToNext()) {
    const row = resultSet.getRow();
    console.log(row.getValue('name'));
  }
} finally {
  resultSet.close();
}

queryForGeoJSONFeatures()

Queries a feature table and returns results as GeoJSON features. Optionally filters by bounding box. Geometry types that cannot be converted to GeoJSON are silently omitted.

queryForGeoJSONFeatures(
  tableName: string,
  boundingBox?: BoundingBox
): GeoJSONResultSet

tableName

string

required

Name of the feature table to query.

boundingBox

BoundingBox

Optional spatial filter. Must be in the same projection as the feature table. Omit to return all features.

GeoJSONResultSet

An iterable result set whose items are GeoJSON Feature objects.

import { BoundingBox } from '@ngageoint/geopackage';

// Query all features in a bounding box around Washington D.C.
const bbox = new BoundingBox(-77.12, 38.79, -76.91, 38.99);
const results = geoPackage.queryForGeoJSONFeatures('places', bbox);
const features = [];
for (const feature of results) {
  features.push(feature); // each item is a GeoJSON Feature
}
results.close();

Tile access

getTileDao()

Returns a TileDao for the named tile table.

getTileDao(tableName: string): TileDao

tableName

string

required

Name of the tile table.

TileDao

Data-access object for the tile table.

Errors thrown

GeoPackageException — no tile table with that name exists, or TileMatrixSet could not be retrieved.

xyzTile()

Retrieves a single tile rendered at the requested pixel dimensions using the standard XYZ (slippy-map) tile coordinate scheme.

async xyzTile(
  table: string,
  x: number,
  y: number,
  z: number,
  width?: number,
  height?: number
): Promise<GeoPackageTile>

table

string

required

Name of the tile table.

number

required

Tile column index.

number

required

Tile row index.

number

required

Zoom level.

width

number

Output tile width in pixels. Defaults to 256.

height

number

Output tile height in pixels. Defaults to 256.

Promise<GeoPackageTile>

Resolves with a GeoPackageTile containing the rendered image data, or null if no tile exists at those coordinates.

const tile = await geoPackage.xyzTile('imagery', 1234, 2345, 12);
if (tile) {
  // tile.getData() returns Uint8Array of PNG/JPEG bytes
}

Attributes access

getAttributesDao()

Returns an AttributesDao for the named attributes table.

getAttributesDao(tableName: string): AttributesDao

tableName

string

required

Name of the attributes table.

AttributesDao

Data-access object for the attributes table.

Errors thrown

GeoPackageException — no contents entry exists for the given table name.

const attrDao = geoPackage.getAttributesDao('metadata');
const resultSet = attrDao.queryForAll();
try {
  while (resultSet.moveToNext()) {
    const row = resultSet.getRow();
    console.log(row.getValue('description'));
  }
} finally {
  resultSet.close();
}

Table creation

createFeatureTableWithMetadata()

Creates a new feature table together with all required GeoPackage metadata rows (contents, geometry columns, SRS).

createFeatureTableWithMetadata(metadata: FeatureTableMetadata): FeatureTable

metadata

FeatureTableMetadata

required

Describes the table name, geometry column, additional columns, SRS, and bounding box. Build one with FeatureTableMetadata.create(geometryColumns, columns, dataType, boundingBox).

FeatureTable

The created FeatureTable object.

import {
  GeometryColumns,
  FeatureTableMetadata,
  FeatureColumn,
  GeoPackageDataType,
  BoundingBox,
} from '@ngageoint/geopackage';
import { GeometryType } from '@ngageoint/simple-features-js';

const geomCols = new GeometryColumns();
geomCols.setTableName('cities');
geomCols.setColumnName('geometry');
geomCols.setGeometryType(GeometryType.POINT);
geomCols.setSrsId(4326);
geomCols.setZ(0);
geomCols.setM(0);

const columns = [
  FeatureColumn.createColumn('name', GeoPackageDataType.TEXT),
  FeatureColumn.createColumn('population', GeoPackageDataType.INTEGER),
];

const table = geoPackage.createFeatureTableWithMetadata(
  FeatureTableMetadata.create(geomCols, columns, undefined, BoundingBox.worldWGS84()),
);

Use createFeatureTable(table: FeatureTable) only if you want to create the SQLite table structure without the accompanying GeoPackage metadata rows. Prefer createFeatureTableWithMetadata() for most use cases.

createTileTableWithMetadata()

Creates a tile table from a TileTableMetadata descriptor. This is the recommended approach.

createTileTableWithMetadata(metadata: TileTableMetadata): TileTable

metadata

TileTableMetadata

required

Describes the table name, bounding boxes, and SRS IDs. Build with TileTableMetadata.create(tableName, contentsBB, contentsSrsId, tileMatrixSetBB, tileMatrixSetSrsId).

TileTable

The created TileTable object.

createTileTableWithTableName()

Creates a tile table and its associated metadata (contents row, tile matrix set row, tile matrix and tile matrix set tables) from explicit parameters.

createTileTableWithTableName(
  tableName: string,
  contentsBoundingBox: BoundingBox,
  contentsSrsId: number,
  tileMatrixSetBoundingBox: BoundingBox,
  tileMatrixSetSrsId: number
): TileMatrixSet

tableName

string

required

Name for the new tile table.

contentsBoundingBox

BoundingBox

required

Informational bounding box stored in the gpkg_contents row.

contentsSrsId

number

required

SRS ID for the contents bounding box (e.g. 4326). Must be defined in gpkg_spatial_ref_sys.

tileMatrixSetBoundingBox

BoundingBox

required

Precise bounding box used to calculate tile row/column coordinates.

tileMatrixSetSrsId

number

required

SRS ID for the tile matrix set (e.g. 3857). Must be defined in gpkg_spatial_ref_sys.

TileMatrixSet

The created TileMatrixSet object.

Errors thrown

GeoPackageException — either SRS ID is not defined in gpkg_spatial_ref_sys.

createAttributesTableWithMetadata()

Creates an attributes table and its gpkg_contents metadata row.

createAttributesTableWithMetadata(metadata: AttributesTableMetadata): AttributesTable

metadata

AttributesTableMetadata

required

Describes the table name and columns. Build with AttributesTableMetadata.create(tableName, columns).

AttributesTable

The created AttributesTable object.

Geometry operations

getBoundingBox()

Returns the bounding box for the given table by combining the contents metadata with the actual indexed feature extents (when available).

getBoundingBox(
  table: string,
  projection?: Projection,
  manual?: boolean
): BoundingBox

table

string

required

Table name.

projection

Projection

Target projection for the returned bounding box. Defaults to the table’s own projection.

manual

boolean

When true, performs a full row scan to determine the bounds of un-indexed feature tables. Defaults to false.

Lifecycle

close()

Closes the underlying SQLite connection. Always call this when you are finished with the GeoPackage instance.

close(): void

const geoPackage = await GeoPackageManager.open('/data/world.gpkg');
try {
  // ... work with the GeoPackage
} finally {
  geoPackage.close();
}

export()

Exports the in-memory or on-disk database as a Uint8Array. Useful in the browser when you need to offer the file for download, or in Node.js when building a GeoPackage in memory before writing it.

async export(): Promise<Uint8Array>

Promise<Uint8Array>

Raw bytes of the .gpkg file.

getName()

Returns the name that was assigned to this GeoPackage when it was opened or created.

getName(): string

getPath()

Returns the file system path of the GeoPackage, or undefined for in-memory instances.

getPath(): string

Core API

Features & Tiles

Canvas & Images

Table management

getFeatureTables()

getTileTables()

getAttributesTables()

getTables()

hasFeatureTable()

hasTileTable()

getInfoForTable()

Feature access

getFeatureDao()

queryForGeoJSONFeatures()

Tile access

getTileDao()

xyzTile()

Attributes access

getAttributesDao()

Table creation

createFeatureTableWithMetadata()

createTileTableWithMetadata()

createTileTableWithTableName()

createAttributesTableWithMetadata()

Geometry operations

getBoundingBox()

Lifecycle

close()

export()

getName()

getPath()

Build docs developers (and LLMs) love

Core API

Features & Tiles

Canvas & Images

​Table management

​getFeatureTables()

​getTileTables()

​getAttributesTables()

​getTables()

​hasFeatureTable()

​hasTileTable()

​getInfoForTable()

​Feature access

​getFeatureDao()

​queryForGeoJSONFeatures()

​Tile access

​getTileDao()

​xyzTile()

​Attributes access

​getAttributesDao()

​Table creation

​createFeatureTableWithMetadata()

​createTileTableWithMetadata()

​createTileTableWithTableName()

​createAttributesTableWithMetadata()

​Geometry operations

​getBoundingBox()

​Lifecycle

​close()

​export()

​getName()

​getPath()

Build docs developers (and LLMs) love

Table management

getFeatureTables()

getTileTables()

getAttributesTables()

getTables()

hasFeatureTable()

hasTileTable()

getInfoForTable()

Feature access

getFeatureDao()

queryForGeoJSONFeatures()

Tile access

getTileDao()

xyzTile()

Attributes access

getAttributesDao()

Table creation

createFeatureTableWithMetadata()

createTileTableWithMetadata()

createTileTableWithTableName()

createAttributesTableWithMetadata()

Geometry operations

getBoundingBox()

Lifecycle

close()

export()

getName()

getPath()