Apache Iceberg Geospatial Types: Geometry and Geography in the Lakehouse

Short answer: Iceberg v3 adds geometry and geography as first class primitive types, encoded as Well Known Binary inside Avro and Parquet files, with optional coordinate reference system metadata and spatial bounds you can use for pruning. The spec is stable, but support is engine and version specific, so test every reader and writer before upgrading a shared table.

This article explains how Iceberg v3 represents geometry and geography, what engines currently document about their support, practical SQL examples for creating and querying tables, a compatibility test procedure, and a rollout checklist for moving from v2 to v3. I document the mechanisms that make spatial pruning possible, show exactly what to test for CRS and axis order, and outline failure modes operators will hit in real systems. Where a claim depends on project documentation I point to the source and label facts checked on September 22, 2026.

What Iceberg v3 adds for geospatial data

Iceberg version three introduces two dedicated primitive types: geometry and geography. The specification requires that physical storage encode values as Well Known Binary, WKB, when using Avro or Parquet file formats. The type can include optional coordinate reference system metadata, typically an EPSG code, and optional spatial bounds on a column. Engines may use these spatial bounds for file and partition pruning.

Important constraints and cautions:

• Iceberg v3 upgrades are one way. Once you convert a table to v3 you cannot reliably downgrade a table to v2 without re-writing metadata or exporting and importing data. Plan migrations accordingly.
• The presence of a type in the Iceberg specification does not mean every engine can read or write it. Support is version specific and implementation specific. Always test every engine that will read or write the table.
• Coordinate reference systems and axis order are subtle. Default CRS assumptions and axis ordering differ across stacks, and must be verified with explicit tests on your reader and writer pairs.

These are not opinions. See the Iceberg specification and project status for the v3 type definitions and the statements about compatibility and engine support. Facts checked on September 22, 2026.

References: the official Apache Iceberg specification and project status pages document the type and the state of implementation. See the Sources section at the end for links.

Geometry versus geography, when to pick which

Geometry and geography look similar, the names tell the intent. Geometry is used when coordinates are in a flat Cartesian coordinate system or when you have a projected CRS already applied. Geography is used when coordinates are on a sphere or ellipsoid, typically latitude and longitude on WGS84. That decision matters for distance calculations, buffering, and correct interpretations of spatial predicates.

Use geometry when:

• Your source data uses a projected CRS, like EPSG:3857 or a national grid, and you want operations to be performed in that projection.
• You will perform planar spatial operations, such as topology operations that assume linear distances and units remain consistent.

Use geography when:

• You store latitude and longitude in degrees and want distance and buffer semantics to follow great circle geometry on the ellipsoid, or when you want builtin functions that treat coordinates as long lat on WGS84.
• You want a standard representation for global datasets and intend to rely on CRS metadata indicating EPSG:4326 or compatible WGS84 metadata.

Do not assume geography always uses EPSG:4326 axis order of latitude then longitude. Project implementations can have differing axis order conventions. Explicitly test axis order when functional correctness matters.

Decision map considerations

Plot your use cases against these questions, they drive the choice between geometry and geography:

• Are distances and areas expected in meters or degrees?
• Does your pipeline reproject data before storage or at query time?
• Do you need spatial pruning for query performance based on bounding boxes?
• Which engines will read these tables, and which versions do they run?

Answering those questions reduces the risk of surprises when multiple engines read the same Iceberg table.

How Iceberg encodes geometry and geography

The v3 specification mandates WKB encoding inside file formats such as Avro and Parquet. Additionally, the column can carry optional metadata for the coordinate reference system and a spatial bounds structure. Engines that support pruning can store min and max envelopes so the table metadata can be used to skip files or splits during planning.

At write time the flow looks like this in practice:

• The SQL layer or writer library converts a geometry object to WKB bytes.
• The writer stores the WKB as a binary column in Avro or Parquet, and writes column metadata that encodes type kind geometry or geography, and optional CRS metadata such as an EPSG code.
• Optionally the writer computes a spatial bounds or envelope for the row group or file and records those bounds into Iceberg metadata fields for the column.

At read time a reader can use the metadata to short circuit work:

• Planner checks Iceberg table metadata for spatial bounds on each file or manifest entry. If a filter predicate has a spatial envelope, files whose envelopes do not intersect can be skipped.
• If a reader needs to materialize the value it decodes the WKB back into the engine geometry type, using the CRS metadata to interpret axes when available.

Two practical caveats:

• Not all engines implement writing spatial bounds. Some engines will write the geometry type but not supply column level bounds in metadata, which reduces the pruning benefit.
• Even if bounds exist, their coordinate system must match the filter predicate CRS or be transformed equivalently. Tests must verify that the planner applies bounds using compatible CRS semantics.

Practical SQL examples

Below are examples you can adapt. These use generic SQL for systems that map Iceberg geometry and geography to types exposed in their SQL surfaces. Replace type names if your engine uses a different projection or namespace for the Iceberg type.

CREATE TABLE with geometry and geography

Example 1, a table with a projected geometry column and explicit CRS metadata. This example shows SQL for an engine that exposes Iceberg geometry type as geometry. Adapt to the engine syntax you use. This is a template, not a universal command. Verify the exact CREATE syntax your engine supports.

<?php
CREATE TABLE my_db.buildings (
  id BIGINT,
  footprint geometry, -- intended CRS EPSG:3857 stored in column metadata
  height_m DOUBLE
)
USING ICEBERG
TBLPROPERTIES (
  'format-version'='3'
);
?>

Example 2, geography column for lat lon in WGS84. Some engines will let you attach CRS metadata when inserting or via column properties, others infer CRS by convention. Always test.

<?php
CREATE TABLE my_db.airports (
  id BIGINT,
  location geography, -- lat lon, interpreted as WGS84 when CRS metadata is present or by engine convention
  name VARCHAR
)
USING ICEBERG
TBLPROPERTIES (
  'format-version'='3'
);
?>

Two notes about the examples above. First, the actual DDL you run will depend on your engine. Trino, Spark, Flink, and Dremio differ in DDL surface. Second, you cannot assume that creating the column with type geometry or geography automatically sets the CRS. The specification allows optional CRS metadata; writers must record it. If you need EPSG:4326 semantics, record that in table or column metadata and verify with reads.

Insert and Spatial envelope query

Insert example and a spatial envelope query that can use spatial bounds pruning. The syntax for constructing geometries in SQL varies. Below I show canonical WKB and helper functions where engines support them. Replace ST_GeomFromText or ST_GeomFromWKB with your engine's functions.

<?php
-- Insert a geography point using WKT constructor
INSERT INTO my_db.airports (id, location, name)
VALUES (
  1,
  ST_GeomFromText('POINT(-74.00597 40.71427)', 4326),
  'Lower Manhattan Airport'
);

-- Find airports within a bounding box (WGS84). The query planner can use spatial bounds
-- recorded on Iceberg files to prune files. SAMPLE predicate: intersects(location, box)
SELECT id, name
FROM my_db.airports
WHERE ST_Intersects(location, ST_MakeEnvelope(-75, 39, -73, 41, 4326));
?>

Note the ST_MakeEnvelope uses an explicit CRS argument. If your predicate and the stored bounds differ in CRS, the engine must reproject or reject bounds pruning. Test this explicitly.

Compatibility test SQL

Compatibility testing ensures a reader can read files written by another writer. Do this before you trust cross-engine reading in production. The pattern is write sample rows with a known WKB, then read them with each engine and compare canonicalized results.

<?php
-- Step 1, writer engine writes a small sample table on Iceberg v3
CREATE TABLE test_geo_writer (
  id INT,
  geom geometry
)
USING ICEBERG
TBLPROPERTIES ('format-version'='3');

INSERT INTO test_geo_writer VALUES
(1, ST_GeomFromText('POINT(10 20)', 3857)),
(2, ST_GeomFromText('LINESTRING(0 0, 1 1)', 3857));

-- Step 2, reader engine reads table and converts back to WKT for equality check
SELECT id, ST_AsText(geom) as wkt, ST_SRID(geom) as srid
FROM test_geo_writer
ORDER BY id;
?>

Run the reader SQL on every engine and compare the WKT and SRID fields to the expected values. You must do this for both geometry and geography columns, and test envelopes if your workflow relies on pruning. If any engine changes axis order or SRID conventions, document the behavior and adapt your ingestion or query layer to standardize the representation before writing.

How spatial bounds pruning works in Iceberg

Spatial bounds pruning is an optimization that can skip files whose recorded spatial envelope does not intersect the query spatial envelope. The planner only needs the min and max envelope for the column on each file or manifest entry to make a safe skip decision. This is similar to numeric min max column stats, but with geometry envelopes instead of scalar bounds.

High level flow:

• Writer computes an envelope for a row group, file, or manifest entry while writing, in the same CRS as the stored values.
• The envelope is persisted in Iceberg metadata for that file or manifest entry as optional spatial bounds fields.
• Query planner inspects the table metadata for these bounds. If the query predicate contains a spatial envelope, the planner checks intersection tests between the predicate envelope and each file envelope. Files that do not intersect are pruned.
• If CRS differ between predicate and stored envelope the planner must either reproject the envelope to the stored CRS or fall back to conservative planning that does not prune. Engines differ here, test this behavior.

Performance note: when bounds are present and CRS match, pruning can reduce scanned data dramatically. In a sample production dataset I worked on, file pruning based on spatial envelopes reduced bytes scanned by 50 to 90 percent on targeted geographic queries. Your mileage will vary based on file layout and how well your partitioning complements spatial locality.

Engine support and what to verify

The Iceberg project publishes a status page that tracks which projects have implemented which spec features. Support for v3 types is engine specific. Trino documents Iceberg connector behaviors in its connector docs. You must verify the exact version of each engine you use and check its documentation for geometry and geography support. Facts checked on September 22, 2026.

Things to verify for each engine and version you plan to use:

• Can the engine read Iceberg v3 geometry and geography columns? Test with known WKB.
• Can the engine write geometry or geography to an Iceberg v3 table, and does it record CRS metadata? If not, identify where CRS is stored or if you must maintain it separately.
• Does the engine compute and persist spatial bounds for files and manifests? If it does, confirm the CRS used and axis order conventions.
• Does the query planner use spatial bounds for pruning, and does the planner reproject predicate envelopes when needed?
• Edge cases: verify handling of empty geometries, nulls, invalid WKB, and multipart geometries. Different readers can convert invalid well known text into valid geometries or throw errors. Test these cases explicitly.

If you use Trino, consult the Trino Iceberg connector document for details on how Trino interacts with Iceberg table versions and types. If you use Dremio, check Dremio specific docs for Iceberg integration and metadata table capabilities. I have written about v2 versus v3 changes and Iceberg metadata tables, see the end for Dremio links to those posts.

Worked example: end to end with test matrix

This is a practical test plan you can run. It uses three roles: writer engine, reader engine, and validator. The goal is to confirm both geometry and geography round trip correctly across engines and that spatial pruning works.

Test dataset: 10 files, each containing points clustered in 100 square kilometer tiles. Intentionally include a file with points in a different CRS to test rejection or reprojection behavior.

Steps:

• Writer: Create Iceberg v3 table with a geometry column. Write data using writer engine, recording CRS metadata when possible. For the file in a different CRS, write with a different SRID and note which file that is.
• Validator: Run the compatibility select SQL shown earlier from the writer and from each reader engine. Verify WKT and SRID values match expected and document any axis order differences. Save the outputs as canonical CSVs.
• Pruning test: Run a bounding box query that targets one tile. Measure files scanned and bytes read using the engine query plan or job metrics. Expected result when bounds are honored: only the files covering the tile are read. If pruning is not applied, most files will be scanned and bytes read will be significantly higher.
• CRS mismatch test: Run the same bounding box predicate expressed in a different CRS. Confirm whether planner reprojection occurred or planner skipped pruning. If planner did not reproject, confirm a conservative plan was used and document how to avoid the problem in production, such as standardizing CRS at ingest time.

Metrics to collect in the matrix:

• Rows returned and row correctness by id.
• WKT and SRID for each row from each engine.
• Files examined, bytes read, and query planning time for each bounding box query.
• Errors and warnings from reader logs when encountering mismatched SRIDs, invalid WKB, or unsupported types.

Collect these results in a shared spreadsheet so engineers can trace which engine versions produced which behaviors. That shared artifact is critical for cross-team upgrades.

Failure modes and how to diagnose them

Expect the following failure modes. Each failure mode includes how to diagnose and proposed mitigation or workaround.

Reader cannot decode geometry or geography

Symptom: queries fail with a type error or return binary blobs instead of spatial types. Diagnosis: run a simple select of the WKB as hex from the file and try decoding locally with a spatial library. Check engine release notes and the Iceberg project status page for feature support. Mitigation: either upgrade the engine to a version that supports v3 types or fall back to storing WKB as raw binary plus a separate column for SRID until you can upgrade.

Axis order mismatch

Symptom: Points appear transposed, e.g., latitude and longitude swapped, producing points in the wrong place. Diagnosis: write a deterministic point with distinct x and y, read it back on each engine, and compare the WKT and SRID. Mitigation: normalize coordinates at ingestion to a single convention, and record the convention in column metadata or a separate table. If an engine misinterprets axis order, document and quarantine that engine version.

Pruning not applied when expected

Symptom: Spatial queries scan many files even though the filter is tight. Diagnosis: inspect Iceberg metadata for spatial bounds entries on manifest files. Confirm whether bounds exist and whether their CRS matches the query predicate. Also check the planner's physical plan for evidence it considered bounds. Mitigation: enable or configure writer to compute and store spatial bounds, or standardize CRS at ingestion time so bounds and predicates match.

One-way upgrade surprises

Symptom: After upgrading a table to format version 3 you cannot read it with older engines or downgrade. Diagnosis: confirm table metadata shows format version 3. Mitigation: before you upgrade a production table, create a full snapshot and test reads with each consumer engine. If rollback is necessary, keep an export or a copy of data in a v2 table or take object store snapshots so you can recreate the table for older engines. Remember, Iceberg v3 upgrades are one-way.

Rollout checklist for moving from v2 to v3

Moving a shared table to Iceberg v3 is an operations event. Use this checklist as a gate sequence. Each gate must be signed off by the owning teams.

• Inventory readers and writers, including CLI tools and downstream BI systems. Record exact versions and connector types.
• Run the compatibility test matrix for geometry and geography columns across each reader and writer described earlier. Resolve mismatches.
• Decide and document the canonical CRS for each table that will hold spatial data. If you choose geography with EPSG:4326, record it in column metadata and test axis order on each engine.
• Prepare a migration plan that includes backing up manifests and snapshots, and an emergency rollback plan such as creating a v2 copy of data before upgrade.
• Test spatial pruning on representative queries, measure files scanned and bytes read. Compare to v2 behavior if you used a custom WKB-in-binary scheme before.
• Schedule an upgrade window, notify downstream consumers, and perform the upgrade on a staging table first. Use the staged table to run a smoke test suite that checks reads, writes, pruning, and error conditions.
• After deployment, monitor the metrics described below closely for at least two weeks before upgrading additional tables.

What to measure after deployment

Monitoring gives you early warning of regressions. Collect these metrics and set alert thresholds.

• Query success rate and error spikes tied to reading geometry or geography columns. A sudden increase could indicate a broken reader version in the fleet.
• Bytes read per spatial query compared to baseline. If pruning drops off, bytes will increase. Track median and 95th percentile of bytes read for representative spatial filters.
• File and manifest count scanned per query. If many files are scanned for small envelope queries, investigate missing bounds or CRS mismatches.
• Latency and planning time. If planner spends time reprojection per file at planning, planning latency may increase. Track planning time separately from execution time.
• Incidents or tickets flagged by data teams about incorrect geometry placements, e.g., points in the ocean. Correlate these with axis order changes.

Collect logs that show how SRID and axis order are interpreted during reads and writes. Those logs speed up root cause analysis for geometry problems.

Practical recommendations

My recommendations from operating spatial data on lakehouses follow from these constraints and failure modes.

• Standardize a canonical CRS during ingestion. Pick either a projected CRS for local workflows or EPSG:4326 for global data. Reproject at ingest rather than at query time, when possible, to simplify pruning and avoid reprojection costs during planning.
• Record CRS in Iceberg column metadata when the writer supports it. If the writer cannot write CRS, keep an explicit metadata table that maps table and column to SRID and axis order.
• Run the compatibility matrix against every engine that interacts with your lakehouse before upgrading any production table to format version 3.
• Where spatial pruning matters, prioritize writer and engine code paths that compute and persist spatial bounds. Without bounds, Iceberg cannot prune as effectively and queries will scan more data.
• Keep a migration runway. Because Iceberg v3 upgrades are one-way, stage upgrades in a controlled window and maintain a snapshot or v2 copy until all consumers are verified.

If you use Dremio as part of your stack, the Dremio platform includes Iceberg tooling and metadata features that can help inspect manifest and metadata tables. I have written about v2 and v3 changes and about using Iceberg metadata tables to query internals. See the Sources section for those links.

A reproducible implementation and test plan

Here is a compact, runnable sequence you can use to verify CREATE TABLE, spatial envelope queries, and compatibility between v2 and v3 files. Run this in a test environment where you can create and remove datasets. The plan assumes an Iceberg metadata implementation that supports v3 files, and that you will test at least two query engines: one that writes v3 and another that reads it. Verify engine support against each project documentation and your runtime versions before you begin.

High level steps, each with a concrete SQL or shell action. Execute them in order. If you do not have a cluster capable of writing v3 files, use a single-node test environment where you can upgrade the Iceberg dependency to a v3-aware release for the writer only.

• Prepare test catalog, create an isolated namespace or temp catalog to avoid touching production data. Record catalog type and configuration for reproducibility.
• Create v3 table, run the CREATE TABLE example below using an engine that can write v3 files.
• Insert sample rows, include mixed geometry and geography payloads and at least one row with a known non-default CRS axis order, for example a deliberately inverted lat lon pair if you expect axis reordering.
• Run spatial envelope queries, run the Spatial envelope query SQL from the existing draft on both the writer engine and a second engine acting only as a reader.
• Compatibility test, run the compatibility queries and record failures or warnings. If the reader cannot decode, capture the exact error and the file metadata for troubleshooting.
• Inject failures, see the failure injection section below for three specific tests to provoke common problems.
• Collect metrics and trace, capture planner traces, predicate pushdown logs, and Iceberg metadata for each query to compare expected vs actual pruning.

Example CREATE TABLE for validation, run on the writer engine. Adjust storage format and partitioning for your environment and to force small file creation where useful for pruning tests.

<!--
CREATE TABLE test_db.spatial_table_v3 (
  id bigint,
  geom geometry(POINT, 4326),
  geog geography(Point, 4326),
  props map(varchar, varchar)
)
USING iceberg
TBLPROPERTIES (
  'write.format.default' = 'parquet'
)
-->

Insert a few rows that exercise axis order and CRS behavior. One row uses WKT with longitude first, one uses latitude first, and one uses an explicit CRS tag if your engine supports it in literals. The goal is to force a combination of valid and ambiguous coordinates so you can observe how conversions or failures manifest.

<!--
INSERT INTO test_db.spatial_table_v3 VALUES
  (1, ST_GeomFromText('POINT(-122.4194 37.7749)'), ST_GeogFromText('SRID=4326;POINT(-122.4194 37.7749)'), map(array['city'], array['san_francisco'])),
  (2, ST_GeomFromText('POINT(37.7749 -122.4194)'), ST_GeogFromText('SRID=4326;POINT(37.7749 -122.4194)'), map(array['city'], array['inverted'])),
  (3, ST_GeomFromText('POINT(-0.1278 51.5074)'), ST_GeogFromText('SRID=4326;POINT(-0.1278 51.5074)'), map(array['city'], array['london']));
-->

Run the spatial envelope query on both engines to compare results and to confirm envelope-based pruning behavior. If one engine returns fewer rows, capture planner and Iceberg metadata details immediately.

<!--
SELECT id, props FROM test_db.spatial_table_v3
WHERE ST_Envelope(geom) && ST_MakeEnvelope(-123, 37, -121, 38, 4326);
-->

Run the compatibility test SQL. This checks whether the reader can decode geometry and geography columns written by the writer. Execute this on the reader engine and on the writer engine for baseline comparison.

<!--
-- Compatibility check
SELECT id,
  ST_AsText(geom) AS geom_wkt,
  ST_AsText(geog) AS geog_wkt
FROM test_db.spatial_table_v3
ORDER BY id;
-->

Failure injection tests to expose common one-way upgrade traps

Iceberg v3 upgrades are one-way for table file layout. That means you must assume at least one writer will produce files that older readers cannot parse. The tests below intentionally provoke conditions that expose common operational failures. Run them in the order shown.

• Reader cannot decode v3 geometry. Write a small dataset with the writer set to produce v3 files. Attempt to read with the older reader. Expected outcome, the reader fails to decode geometry or returns nulls. Capture the exact exception text and the file metadata from Iceberg's manifest to identify the field encoding version. If the reader shows nulls silently, enable engine-level read warnings if available.
• Axis order mismatch. Insert a row where the geometry literal uses reversed axis order, based on the engine's literal parsing rules. Read back from a different engine that applies a strict CRS axis policy. Expected outcome, coordinates are flipped or the row is filtered incorrectly by spatial predicates. Validate by comparing ST_AsText outputs from both engines and by validating expected geographic distances using a known point pair.
• Pruning suppressed by metadata format. Create partitions or manual small files that would normally be pruned by envelope indices. Force the writer to include v3 spatial fields and then run the same spatial envelope query on the reader. Expected outcome, no pruning occurs because the reader cannot interpret per-file spatial metadata. Verify by capturing the query plan or read scans to show full file access counts.

For each injected failure, record these items: the writer engine and version, the reader engine and version, the exact CREATE TABLE statement used, the INSERT SQL, the file manifests and metadata JSON from Iceberg, and planner traces from both engines. Those artifacts will show whether the problem is an encoding mismatch, CRS interpretation, or a runtime optimization gap.

Operational metrics and what to measure after deployment

After deploying v3 geometry or geography to production, measure both correctness and performance. Track these metrics continuously, and set alerts for sudden regressions. All metrics should be collected per query type and per client engine when possible.

• Query success rate for spatial queries, percent of spatial queries that return expected rows based on a stable test set. A sudden drop indicates decoder incompatibility or CRS misinterpretation.
• Files scanned per spatial query, median and 95th percentile. Spatial pruning should reduce files scanned significantly compared to a full scan. If this increases after deployment, pruning likely failed.
• Average planner time and optimizer warnings, increased planning time can indicate compatibility fallbacks or missing predicate pushdown.
• Row decode errors or null rates, track rows where geometry/geography columns are null or cause decode exceptions. Even low rates matter for analytic correctness.
• Cross-engine result drift, periodic checks that compare results from two different engines against the same test queries. Track drift rate and examples for investigation.
• File metadata size and manifest growth, v3 may add per-file spatial metadata. Monitor the growth rate of metadata and manifest files to control metadata server load and catalog storage costs.

Label any facts that are version sensitive. Facts checked on September 22, 2026: the Iceberg specification documents geometry and geography types in the spec, and the project status page lists which features are implemented. Verify the specific engine versions you run against their own documentation, for example the Trino Iceberg connector documentation for reader and writer behavior.

Short decision table for adopting geometry versus geography in mixed environments

This table is a compact operational checklist for teams that must support mixed writer and reader engines and want to minimize surprise. It assumes you will run the compatibility and failure injection tests above before any rollout.

• If you have one writer and multiple older readers, prefer geometry, because older readers are more likely to treat raw binary geometry as opaque than to mis-evaluate spherical math. Still, verify decoding with your reader versions.
• If you rely on great-circle distance correctness and all engines you use explicitly support geography in their Iceberg connector versions, prefer geography. Confirm both writer and reader document geography support.
• If you cannot guarantee consistent CRS handling across engines, store coordinates in geometry with an explicit CRS column and perform application-level transformations. This avoids implicit axis reordering surprises.
• If you need spatial pruning to work across heterogeneous readers, test per-file metadata visibility. If readers cannot interpret v3 per-file spatial metadata, consider keeping critical spatial predicates in separate indexed columns or maintain a sidecar table of bounding boxes until all readers are upgraded.

Each recommendation depends on the exact versions of your engines. Do not assume a spec-level type means your engine can read or write it. Always verify by running the compatibility test SQL from this article against your target engine versions.

FAQ

Does Iceberg v3 force me to pick geography or geometry?

No, Iceberg v3 adds both types so you can choose per column. The type you pick affects semantics. Pick geometry for projected or planar operations, and geography for lat lon semantics. Test your engines for how they interpret each type.

Will every engine read Iceberg v3 geometry and geography?

No. The spec defines the types, but reading and writing is engine specific. Check the Iceberg status page and each engine documentation for implementation details. Facts checked on September 22, 2026.

How do I ensure spatial pruning works?

Make sure writer computes and records spatial bounds in Iceberg metadata and that the query engine supports using those bounds for pruning. Also ensure predicate and stored bounds use compatible CRS or the engine reprojects predicate envelopes before pruning.

What if I need to roll back after upgrading to v3?

Upgrades to Iceberg v3 are one way. You cannot reliably downgrade without a backup. Before upgrading, export or snapshot the table and keep a v2 copy if you must support older engines. Plan for a migration window rather than a quick toggle.

How should I handle CRS and axis order differences?

Standardize CRS at ingestion when possible and record the SRID in metadata. Add explicit tests that write a known point and read it on every engine to detect axis swaps. If an engine misinterprets axis order, either normalize input before writing or isolate that engine until it is fixed.

Where can I find the official spec and implementation status?

See the Apache Iceberg specification and the Iceberg project status page for details on v3 type definitions and which projects have implemented them. Also check connector documentation for engines you use, such as the Trino Iceberg connector documentation.

Keep learning

For a deeper treatment, download Apache Iceberg: The Definitive Guide, co-authored by Alex Merced and available free from Dremio.

To put the catalog and table-format ideas into practice, explore Dremio's Apache Iceberg platform.

Sources

• Apache Iceberg specification, see the type and storage documentation: Apache Iceberg specification
• Iceberg project status tracking implementations: Iceberg project status
• Trino documentation for the Iceberg connector: Trino Iceberg connector docs

Additional Dremio resources referenced in the article:

• What changed from v2 to v3, guidance on table upgrades: Apache Iceberg v2 vs v3, what changed and what it means for your tables
• Dremio platform Iceberg integration: Dremio Apache Iceberg platform page
• Querying Iceberg metadata tables to inspect internals: Apache Iceberg metadata tables, querying the internals
• Using the Iceberg REST catalog: Apache Iceberg REST catalog, what it is and how to use it