Skip to main content
WherobotsDB stores tables in Apache Iceberg. A table can have geometry, geography, and raster columns, and WherobotsDB uses the spatial bounds of each data file to skip the files a spatial filter can’t match. This page covers what applies to every table: the spatial column types, the Iceberg format versions, and spatial file skipping on each.

Geometry and Geography Tables

Create, write, and query tables with GEOMETRY(<srid>) and GEOGRAPHY(<srid>) columns.

Upgrade Existing Geometry Tables

Check whether a table’s geometry columns have a declared CRS, and copy a table without one.

Raster Tables

Create, write, and query tables with in-db and out-db raster columns.

Spatial Filter Push-down and Clustering

How WherobotsDB skips data files for spatial filters, and how to cluster or partition a table so it skips more.

​
Spatial column types

The geometry and geography types are part of the Apache Iceberg table spec from format-version 3. Wherobots adds the raster type and the CREATE SPATIAL INDEX statement. Tables created before September 15, 2026 have geometry columns with no declared CRS, and so does a table created from the result of an ST_ function. To check a table and upgrade it, see Upgrade Existing Geometry Tables. How raster columns and geometry columns with no declared CRS are stored in data files and manifests is specified in Spatial Extensions for Apache Iceberg Tables.

​
Format versions

New tables in Wherobots-managed catalogs, such as org_catalog, are format-version 3 (V3). Tables created before September 15, 2026 were created at format-version 2 (V2), and Wherobots doesn’t raise them to V3. In an AWS Glue catalog, a new table is V2 unless it has a GEOMETRY(<srid>) or GEOGRAPHY(<srid>) column; see the Glue known limitations. To check a table’s format version:
To create a V2 table, set the format version when you create it: add TBLPROPERTIES ('format-version'='2') to CREATE TABLE or CREATE TABLE ... AS SELECT, or call .tableProperty("format-version", "2") on the writer that writeTo returns, before .create(). Later writes with INSERT INTO or writeTo(...).append() keep the table at V2. A V2 table can’t have a GEOMETRY(<srid>) or GEOGRAPHY(<srid>) column. ALTER TABLE ... SET TBLPROPERTIES ('format-version'='3') raises a table to V3 in place, and a V3 table can’t go back to V2. Raising the format version doesn’t give an existing geometry column a declared CRS.

​
Spatial file skipping

Whether WherobotsDB skips data files for a spatial filter depends on the column type and the table’s format version: Queries return the same rows either way; only the amount of data read differs. Because a geometry(<srid>) column requires format-version 3, a table can’t have both a declared-CRS geometry column and raster file skipping. Keep rasters that you filter spatially in a separate format-version 2 table. WherobotsDB skips the most files when rows that are near each other are stored in the same files. See Spatial Filter Push-down and Clustering.

​
Format-version 3 features

On V3 tables:
  • Merge-on-read DELETE, UPDATE, and MERGE write deletion vectors.
  • The row lineage columns _row_id and _last_updated_sequence_number can be queried.
  • variant columns can be written and read.
Limitations:
  • Column default values can’t be set.
  • A table with a timestamp_ns column can’t be read.
For Apache Iceberg itself, see the Apache Iceberg documentation for Spark.