Skip to content

Apache Iceberg 1.12.0 Release

The Apache Iceberg community is pleased to announce the release of Apache Iceberg 1.12.0. This release is the result of 777 commits from 142 contributors since 1.11.0. See the release notes for the complete list of changes.

Release Highlights🔗

Data Types: Variant and Geospatial🔗

This release improves Variant read performance, extends shredded Variant writes beyond Spark, and adds read and write support for the geospatial types.

Variant. Reading unshredded Variant data is now faster in Spark. On both Spark 4.0 and 4.1, unshredded Variant columns are read through the vectorized Parquet path instead of row-at-a-time decoding.

Variant shredding also uses a stricter layout rule. Shredding now requires type uniformity: a field is shredded into a typed column only when all of its values fall into a single type family (after numeric widening); fields that mix types stay in the untyped residual. Unlike the previous majority-based rule, which could shred a field while covering only a fraction of its rows, every typed column now fully covers its field. Single-type fields are unaffected.

Shredded Variant writes are no longer Spark-only. Flink can now write shredded Variant, and the Kafka Connect sink and the generic record writer can produce shredded Variant as well, so semi-structured data ingested through those paths benefits from the same read-time pushdown. Flink also gains Variant support in Avro readers and writers.

Several correctness and hardening fixes also landed for Variant:

Geospatial. The geometry and geography types gain read and write support. Both are stored as Well-Known Binary (WKB) and can now be read and written in Avro and in Parquet, where they map to the Parquet geometry and geography logical types so files are self-describing; single-value binary serialization is also in place for defaults and metadata.

Spark 4.1 is the first engine with an end-to-end geospatial path: it reads and writes both types in Parquet and supports row-level DELETE, UPDATE, and MERGE on tables with geospatial columns, including the merge-on-read, deletion-vector path on format version 3. Current limitations:

  • Support is limited to Spark 4.1 (not Spark 3.5 or 4.0, Flink, or ORC)
  • Reads use the row-based reader; there is no Arrow geospatial vector yet
  • There are no spatial predicates yet, so filters are expressed against non-geospatial columns

Deletion Vectors🔗

Deletion vectors gain co-located access through DataFile.deletionVector(), and get fixes for references when they share a Puffin file and preserved encryption metadata on merge.

Streaming Deletes🔗

Streaming pipelines that upsert into Iceberg write equality deletes: markers that say "remove every row whose key matches these values." They are cheap to write but expensive to read, because every query has to re-open data files and compare values to work out which rows still exist. 1.12.0 adds a Flink-native maintenance task that resolves those deletes once, instead of on every scan.

ConvertEqualityDeletes. This new maintenance task resolves the equality deletes produced during streaming ingest into row-position deletion vectors and commits them alongside the data files. After conversion, readers apply deletes by position rather than re-scanning and comparing values, so queries no longer pay this cost.

It pairs with IcebergSink, which stages new data files and equality deletes on a source branch; the converter resolves those into deletion vectors and commits to the target branch, or converts in place. Because deletion vectors are a v3 feature, the task requires table format version 3 or later and runs on Flink 1.20, 2.1, 2.2, and 2.3. It landed across several changes, including the core data model and integration with IcebergSink; a follow-up ensures deleted rows do not reappear after a failed conversion cycle.

Data Layout🔗

Hilbert clustering. rewrite_data_files gains Hilbert-curve clustering, a new multi-dimensional sort strategy alongside Z-order. Both map several columns onto a single space-filling curve so rows with similar values in those columns are stored together, improving file skipping for multi-column filters. Hilbert keeps neighboring points on the curve adjacent in the data, without the large "jumps" across the space that Z-order makes. You select it through the sort strategy:

CALL system.rewrite_data_files(
  table => 'db.tbl',
  strategy => 'sort',
  sort_order => 'hilbert(c1, c2)'
);

Hilbert clustering ships for Spark 4.1.

Other maintenance. The RepairTable action interface is defined (a standard way to repair manifest-entry statistics that disagree with the files they describe), and Spark's rewrite_data_files now accepts the max-file-group-input-files option to cap the input files in a single group.

REST Catalog🔗

The REST catalog protocol picks up several additions, grouped here by layer. (Finer-grained read restrictions on loadTable, a spec-level change, are covered under Spec Evolution below.)

OpenAPI protocol. VariantType is now representable in the spec so Variant columns can travel in schemas over the protocol. Read-only list and load function endpoints and an unregister-table endpoint (which detaches a table from a catalog without deleting its data or metadata) are added, along with formalized remote signing configuration and a labels field for catalog metadata enrichment.

Library and client. CatalogObjectIdentifier adds a shared way to name catalog objects, the remote signing configuration gains a client implementation, and catalog labels are read on load responses and exposed on the loaded table via SupportsLabels.

Spec Evolution🔗

The specification evolved alongside the code during this release. These changes define behavior for current and future table versions; they are not necessarily engine features shipped in 1.12.0.

The expressions specification is adopted, giving Iceberg a formal, engine-independent definition of predicate expressions; the REST OpenAPI spec is aligned to it in the same release, so read-restriction row filters are portable across clients.

Finer-grained read restrictions on loadTable are added: a catalog can return a ReadRestrictions object in the load response describing required column projections (column-masking actions such as showing only the last four characters, replacing a value with null, truncating a timestamp, hashing, or alphanumeric masking) together with a required row filter modeled as an Iceberg expression. The contract is client-enforced and fail-closed: a reader that supports read restrictions must apply every returned action and filter in full, and if it cannot apply one it must fail the query rather than return raw, partial, or empty rows. This is a spec and OpenAPI contract only; no Iceberg reader applies read restrictions in 1.12.0, so a catalog that returns a ReadRestrictions object today is silently ignored by every consumer.

Content-file uniqueness is now spelled out: within a snapshot, each content file must be referenced by at most one live manifest entry across all manifests, and a snapshot that violates this has undefined behavior. Smaller clarifications round out the spec work: Variant type classification and decimal type serialization.

Format V4 Foundations🔗

Work toward Table Format V4 continues. V4 is under active development and has not been formally adopted: Iceberg 1.12.0 cannot read or write a V4 table, and everything here is groundwork the next ratified spec version will build on.

Manifests. The release adds a V4 manifest reader that reads V4 manifests written in both Parquet and Avro, the ability to write Parquet and Avro manifests in the V4 layout, and an adapter layer with a tracked-file metadata model that surfaces V4-tracked files through the existing ManifestFile and DataFile interfaces. These operate at the manifest level for testing and future use; tables still cannot be created or committed in V4.

Foundations. Several structural pieces land: relative paths in metadata (backed by relativization utilities and reader-side resolution), a step toward relocatable tables; a new content-statistics spec addition; and a read-only implementation of the Mumbling bitmap, a bounded-size compressed bitmap format for cases like deletion vectors, based on Roaring Bitmap.

Performance and Reliability🔗

Faster planning and scans. Manifest list files are now cached in the manifest content cache, and Parquet gains adaptive bloom filter sizing and per-column dictionary encoding.

Vectorized reader fixes. The vectorized Parquet reader gets several correctness fixes: int-to-long promotion that previously threw a ClassCastException, decimal columns with default values, decimals with precision greater than 18, dictionary-encoded VARCHAR/VARBINARY through direct byte buffers, all-null DELTA-encoded pages, an INT96 dictionary-decode offset, and a direct-memory leak in the row-lineage readers.

Sharper pruning. Predicate pushdown on nanosecond timestamps is fixed in Parquet and ORC, notStartsWith no longer skips row groups containing nulls, and null counting is correct for Parquet files written without null_count.

Core fixes. FileIO leaks are fixed and close() is standardized across catalog implementations, Z-order byte encoding of floating-point values is corrected, EncryptingFileIO is reworked as a DelegateFileIO so encrypted tables keep access to underlying I/O capabilities such as bulk operations, and a manifest-pruning and residual-evaluation bug is resolved.

Security🔗

This release fixes two HIGH-severity jackson-databind CVEs, CVE-2026-54512 and CVE-2026-54513, by aligning Jackson versions across the runtimes and bundles; a further Jackson bump fixes GHSA-r7wm-3cxj-wff9. Three Jackson findings remain in the Kafka Connect runtime because they come from the copy of Jackson shaded inside parquet-jackson, which cannot be upgraded independently of Apache Parquet.

The shaded-jar LICENSE and NOTICE files were cleaned up: duplicate license metadata was stripped from the cloud and engine bundles, and missing third-party notices were added.

Engine Updates🔗

Spark🔗

Spark support in 1.12.0 is Spark 3.5, 4.0, and 4.1; Spark 3.4 support is removed. Notable additions:

Spark 4.1 also gains geospatial support, described in the Data Types section above, and Hilbert-curve clustering for rewrite_data_files, described in the Data Layout section above.

Flink support in 1.12.0 is Flink 1.20, 2.1, 2.2, and 2.3; Flink 2.2 and 2.3 are added and Flink 2.0 is removed.

Beyond the equality-delete-to-deletion-vector conversion above, Flink gains Iceberg view support: it can read views in SQL and create, drop, and rename them through FlinkCatalog (both backported to 2.2, 2.1, and 1.20).

The Dynamic Sink gains fine-grained slot-sharing-group control and several fixes:

Kafka Connect🔗

The sink connector now surfaces commit failures instead of swallowing them, adds bounded retry for transient commit exceptions and a metric for partial commit failures, and improves offset handling by only committing offsets greater than the existing ones and tracking control-topic offsets as a high-water mark.

Breaking Changes🔗

Users upgrading from 1.11.0 should review these before upgrading.

Removals:

Deprecated APIs removed:

Behavior changes:

  • AWS HTTP client: the default AWS SDK HTTP client migrated to Apache HttpClient 5; users who manage their own AWS SDK classpath (that is, those using iceberg-aws directly rather than the iceberg-aws-bundle) must switch from software.amazon.awssdk:apache-client to software.amazon.awssdk:apache5-client
  • Geospatial toString(): GeometryType and GeographyType toString() now include the resolved CRS, and for geography the edge algorithm (for example geometry(OGC:CRS84) and geography(OGC:CRS84, spherical)), instead of the bare type name
  • REST idempotency retries: the REST client now retries POST requests carrying an Idempotency-Key on retriable errors (408, 500, 502, 503, 504)

Dependency Updates🔗

Notable dependency updates in 1.12.0:

  • AWS SDK (bom): 2.44.4 -> 2.54.17
  • Jackson (bom): 2.21.3 -> 2.22.2
  • Netty: 4.2.13.Final -> 4.2.18.Final
  • Nessie: 0.107.5 -> 0.108.8
  • RoaringBitmap: 1.6.14 -> 1.6.23
  • Avro: 1.12.1 -> 1.12.2
  • ORC: 1.9.8 -> 1.9.9
  • Guava: 33.6.0-jre -> 33.7.1-jre
  • Caffeine: 2.9.3 -> 3.2.4

Getting Involved🔗

Apache Iceberg is developed by a community of contributors. We use GitHub issues for tracking work and the Apache Iceberg Community Slack for discussions.

The easiest way to get started is to:

  1. Try Apache Iceberg 1.12.0 with your workloads and report any issues you encounter
  2. Review the contributor guide
  3. Look for good first issues

For more information, visit the Apache Iceberg repository or the documentation.