> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wherobots.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Iceberg Tables Overview

> How WherobotsDB stores spatial data in Apache Iceberg tables: the spatial column types, format versions, spatial file skipping on each format version, and supported format-version 3 features.

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](https://docs.wherobots.com/data-engineering/iceberg-tables/geometry-tables.md)**
>
> Create, write, and query tables with `GEOMETRY(<srid>)` and `GEOGRAPHY(<srid>)` columns.

> **[Upgrade Existing Geometry Tables](https://docs.wherobots.com/data-engineering/iceberg-tables/upgrade-geometry-tables.md)**
>
> Check whether a table's geometry columns have a declared CRS, and copy a table without one.

> **[Raster Tables](https://docs.wherobots.com/data-engineering/iceberg-tables/raster-tables.md)**
>
> Create, write, and query tables with in-db and out-db raster columns.

> **[Spatial Filter Push-down and Clustering](https://docs.wherobots.com/data-engineering/iceberg-tables/spatial-index.md)**
>
> How WherobotsDB skips data files for spatial filters, and how to cluster or partition a table so it skips more.

## Spatial column types

| Column type | Values | Format version |
| :- | :- | :- |
| `geometry(<srid>)` | Geometries in the declared Coordinate Reference System (CRS). A value in another CRS is rejected. | 3 |
| `geography(<srid>)` | Geographies in the declared CRS, interpreted on a sphere. | 3 |
| `geometry`, with no declared CRS | Geometries that each carry their own Spatial Reference Identifier (SRID), which isn't checked against the column. Iceberg engines outside Wherobots read the column as binary. | 1, 2, or 3 |
| `raster` | In-db or out-db rasters. | 1, 2, or 3 |

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](https://docs.wherobots.com/data-engineering/iceberg-tables/upgrade-geometry-tables.md).

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](https://docs.wherobots.com/reference/havasu-table/spec.md).

## 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](https://docs.wherobots.com/get-started/initial-storage/aws/connect-to-glue-catalog.md#known-limitations).

To check a table's format version:

```sql theme={"system"}
SHOW TBLPROPERTIES org_catalog.test_db.test_table ('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:

| Column | Format-version 1 or 2 | Format-version 3 |
| :- | :- | :- |
| `geometry(<srid>)` | Not available: the column type requires format-version 3 | Skips data files |
| `geometry`, with no declared CRS | Skips data files | Reads every data file |
| `raster` | Skips data files | Reads every data file |

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](https://docs.wherobots.com/data-engineering/iceberg-tables/spatial-index.md).

## 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](https://iceberg.apache.org/docs/latest/getting-started/).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.