Check Iceberg delete readers before accepting writer support
DuckDB’s Iceberg writes need compatible delete readers and clear snapshot freshness. Review the file contract before treating SQL support as interoperability.
By 
Paul. Architecture and infrastructure
A writer accepting an SQL update establishes one capability. A downstream engine returning the intended rows establishes another. Shared Iceberg tables need both, with a defined expectation about which committed state a reader sees. Treat interoperability as a contract between named implementations and versions. A successful statement in the writer cannot supply evidence for every consumer of the resulting table.
Looking back from November 2026, DuckDB’s November 2025 announcements make that boundary concrete. The useful adoption question is whether the actual readers understand the mutations the writer produces. This is separate from deciding how long to retain an archive or how to process late-arriving events. Here the concern is the meaning of rows after a mutation crosses an engine boundary.
Anchor the feature to its version
The 1.4.2 LTS announcement of 12 November 2025 already includes Iceberg inserts, updates and deletes. The 28 November explanation describes that version’s Iceberg v2 support, positional deletes and merge-on-read semantics. It excludes writes to partitioned or sorted tables and copy-on-write. The later article explains an existing release; it is not a second shipping date.
For file-level meaning, the Iceberg specification distinguishes data files from delete files. Positional deletes identify a data file and row position; equality deletes use field values. The dated DuckDB article’s request trace shows Parquet data and delete files, with Avro manifests. Do not collapse all of these into “some Parquet files” and assume that opening the data objects reconstructs the logical table.
These details describe the historical implementation under discussion. The specification is maintained, and newer table versions or extension releases can add other mechanisms. A current capability page cannot silently expand the November 2025 contract. No illustrative SQL or executed interoperability result is offered here; the evidence is the dated release material and the format’s documented distinctions.
A delete has to reach the reader’s result
With separate deletion information, physically present data can have ceased to belong in the logical result. A consumer that bypasses table metadata or ignores applicable delete files can therefore answer a different question from the writer. Reading a file successfully is not enough. The useful acceptance criterion is whether the consumer reconstructs the intended table state after the change.
An update deserves the same attention. It may involve old row versions being excluded and replacement values becoming visible. A consumer that handles the new data but misses the deletion information could retain an obsolete version alongside its replacement. This is a proposed failure mode to examine, not a claim that a named engine failed in a test performed for this article.
Compatibility records should identify the table format version and the deletion mechanism actually written. Then list the reader versions that are in scope. “Supports Iceberg” is too broad to resolve a disagreement about one mutation path. A small, explicit set of consumers gives the team a boundary it can evaluate and maintain when either side changes.
Freshness is a separate promise
The November explanation says the first table read in a transaction fixes its snapshot information for that transaction, while mutations become committed at transaction commit. That behaviour supports a consistent view. It also means a repeated read inside a long transaction is not a promise to discover every newer commit from elsewhere. Consistency and freshness answer different requirements.
For a recurring report, a stable snapshot may be exactly the desired behaviour. Its totals remain comparable throughout the calculation. An operational display asking for the newest state has another requirement. Define where a fresh transaction begins and how the application identifies the state used. Ending a transaction solely to see newer data also changes the consistency boundary of the calculation.
Caching should be discussed in those terms. A cache can be working as intended while a user expects fresher information. Before blaming storage or requesting more frequent polling, ask which snapshot the reader selected and which transaction remains open. A freshness promise that omits that boundary is difficult to diagnose because “latest” has no agreed reference point.
Define the evidence before adoption
A proposed compatibility check starts with a small table whose intended results are unambiguous. Record the writer and reader versions, table properties and catalog arrangement. Observe the results before mutation, after deletion and after update, using the snapshots the application intends to consume. This is a recommended evaluation plan, not a report of a test run here.
The record should distinguish an unsupported operation rejected by the writer from an accepted operation misunderstood by a reader. The remedies differ. Changing a table property might make a statement acceptable without making another engine understand its files. Conversely, a compatible reader cannot remove a restriction imposed by the writer version on sorted or partitioned tables.
Check behaviour after an upgrade as well as before the first deployment. A compatibility decision belongs to a combination of versions and settings, not permanently to a vendor name. Preserve the expected logical results so a future comparison has a stable reference. The goal is a focused piece of evidence about the actual consumer set, rather than an expensive claim to cover the entire ecosystem.
A controlled engine set is a reasonable boundary
The strongest counterargument is that exhaustive compatibility would make open formats impossible to adopt. That is correct: most applications need a few known engines. They can obtain real value without proving that every possible reader works. An intentionally restricted consumer set is a valid design choice when its limitations are understood and new consumers pass the same review.
The limit is organisational as much as technical. Someone needs to approve new writers, reader upgrades and changes to table properties. Otherwise a previously valid assumption can disappear without the report owner noticing. For software maintenance, include that compatibility record and the transaction-freshness expectation in the operating scope. SQL acceptance then becomes one documented part of a shared-table contract, with reader results supplying the rest of the evidence.