What is Iceberg v3, and what does it add?

Summary

• Iceberg v3 is a version of the Apache Iceberg table specification, not a software release. The spec says versions 1, 2 and 3 are "complete and adopted by the community" and version 4 "is under active development and has not been formally adopted."
• v3 adds the variant, geometry, geography, unknown, timestamp_ns and timestamptz_ns types, column default values, multi-argument transforms, row lineage, binary deletion vectors and table encryption keys.
• Deletion vectors replace position delete files in v3, but position delete files from a v2 table stay valid after an upgrade.
• Iceberg's format-version table property defaults to 2. Check that every engine that reads or writes the table supports v3 before you upgrade.
• On Databricks, Iceberg v3 features are generally available for managed Iceberg tables and managed Delta tables with Iceberg reads (UniForm) on Databricks Runtime 18 LTS and above, with documented exceptions.

What is Iceberg v3, and what does it add?

Iceberg v3 is a version of the Apache Iceberg table specification. Version 3 "extends data types and existing metadata structures to add new capabilities." As of October 2026, versions 1, 2 and 3 are "complete and adopted by the community," while "Version 4 is under active development and has not been formally adopted."
The format version is incremented "when new features are added that will break forward-compatibility", meaning older readers would not read the newer table features correctly. Tables "may continue to be written with an older version of the spec to ensure compatibility by not using features that are not yet implemented by processing engines."

What does v3 add?

The spec's change list says "Types variant, geometry, geography, unknown, timestamp_ns, and timestamptz_ns are added in v3." Its overview of v3 lists these capabilities:

Addition	What the spec says
variant type	Semi-structured values; "The structure and data types in a variant are not necessarily consistent across rows in a table or data file"
geometry and geography types	Geospatial features from OGC Simple feature access. The default coordinate reference system is OGC:CRS84, and geography defaults to spherical edge interpolation
timestamp_ns, timestamptz_ns	Nanosecond-precision timestamps, without and with time zone
unknown type	"Default / null column type used when a more specific type is not known"; optional with null defaults, not stored in data files
Default values	initial-default fills records written before a field was added; write-default fills later records when the writer supplies no value
Multi-argument transforms	Partition and sort fields write source-ids
Row lineage	Fields _row_id and _last_updated_sequence_number; "In v3 and later, an Iceberg table must track row lineage fields for all newly created rows"
Deletion vectors	Bitmaps of deleted row positions, stored as Puffin deletion-vector-v1 blobs, at most one per data file in a snapshot
Encryption keys	Table metadata tracks encryption-keys

What changes when I upgrade a v2 table?

The spec says "Writers are not allowed to add new position delete files to v3 tables," while "Existing position delete files are valid in tables that have been upgraded from v2." For row lineage, "When a table is upgraded to v3, its next-row-id is initialized to 0 and existing snapshots are not modified."

How did v3 work show up in recent Iceberg releases?

Release	Date	Selected v3 items from the release notes
1.8.0	Feb 13, 2025	Deletion vectors in the spec, with reading and writing; Variant and unknown types; default values when reading Parquet and Avro
1.9.0	Apr 28, 2025	Geometry and geography types; nanosecond timestamps and unknown types; default values in UpdateSchema; row lineage enabled for all v3 tables
1.10.0	Sep 11, 2025	Encryption keys in the spec; Spark 4.0 row lineage support and variant reads
1.11.0	May 19, 2026	Writing deletion vectors in the Flink IcebergSink; row lineage readers for ORC and Flink
1.12.0	Sep 29, 2026	Geometry and geography in Parquet on Spark 4.1; variant for Avro on Flink; a Flink task that converts equality deletes to deletion vectors

How do I upgrade a table to v3?

format-version is a reserved table property: "Reserved table properties are only used to control behaviors when creating or updating a table." It defaults to 2. In Spark with Iceberg, ALTER TABLE ... SET TBLPROPERTIES sets table properties, so a v2 table moves to v3 with:

ALTER TABLE prod.db.sample SET TBLPROPERTIES ('format-version' = '3');

How does Databricks approach Iceberg v3?

Databricks documents Iceberg v3 "for managed tables using Iceberg or Delta Lake with Iceberg reads in Unity Catalog," on Databricks Runtime 18 LTS and above. Its May 21, 2026 release notes call "Apache Iceberg v3 features" "generally available," naming deletion vectors, the VARIANT data type and row lineage. To create a managed Iceberg v3 table, set 'format-version' = 3:

CREATE OR REPLACE TABLE main.schema.table (c1 INT)
USING iceberg
TBLPROPERTIES ('format-version' = 3);

A new Delta table with Iceberg reads uses 'delta.universalFormat.enabledFormats' = 'iceberg' and 'delta.enableIcebergCompatV3' = 'true'. To upgrade an existing table, enable any v3 feature, set 'format-version' = 3 for Iceberg, or set 'delta.enableIcebergCompatV3' = 'true' with 'delta.enableIcebergCompatV2' = 'false' for Delta Lake. Databricks "supports version 3 of the Iceberg specification, with the following exceptions": initial defaults, the unknown type, nanosecond precision timestamps and multi-argument transforms are not supported.

FAQs

Do I need to upgrade to v3?

No. The default format-version is 2, and the spec lets you keep writing older versions. Upgrade when a v3 feature such as deletion vectors, variant or row lineage solves a problem and every engine that touches the table supports v3.

Can an engine without v3 support read a v3 table?

No. The spec says "Implementations must throw an exception if a table's version is higher than the supported version."

Can I go back to v2?

On Databricks, yes: "Tables can be downgraded from v3 to v2 by restoring the table to a table version before the upgrade to v3 using RESTORE." Elsewhere, check your platform's documentation before upgrading.