Hello everyone, Iceberg tables can end up with metadata that references files that don't exist on storage. This can happen through partial copies, storage-side changes, or incomplete metadata operations, and surfaces later as failed queries, data loss on failover, or restore failures. Iceberg doesn't currently have a built-in way to verify that a table's metadata references actually resolve on storage.
*Proposing a new action: ValidateTableIntegrity.* It verifies the referential integrity of an Iceberg table's metadata: does every metadata, data, and delete file the table's metadata references actually exist at its stated location, or at a corresponding rewritten location when a destination is configured? The action walks the full metadata graph — metadata.json log entries, manifest lists, manifests, data files, delete files (including V3 deletion vectors), statistics files, and partition statistics — verifying every referenced file exists at the checked location. The action is standalone: the same interface serves a *self-audit *on a single table and a *source-vs-destination* check between two tables. Tracked across three sequential PRs: 1. API contract (interface + factory + Result base) 2. Spark implementation + core helpers + exception 3. validate_table_integrity Spark procedure + user docs Two supported shapes: *Self-audit* : Single table, no destination. Walks the metadata graph and verifies each referenced file exists at its stated location. Fits post-rollback verification, catalog audits, and detecting storage-side drift (files removed out-of-band while metadata still references them). *Source-vs-destination* : Walks source metadata, applies the configured prefix rewrite, and verifies each referenced file exists at the destination. Fits pre-registration copy verification, DR sync, migration audits, and any out-of-band copy audit (backups, Distcp output, manual file copies). For context, *we run large-scale Iceberg replication* and have found this pattern useful in practice across several scenarios: 1. *Pre-registration verification* of a fresh destination before it goes live as a catalog table 2. *DR replica verification* before promotion to primary (initial or after incremental sync) 3. *Ongoing integrity checks* against out-of-band copies (Distcp output, backup restoration, migration targets) PR (API contract): https://github.com/apache/iceberg/pull/16967 Would appreciate your feedback on the design and API surface.
