A metadata table is a queryable representation of an Apache Iceberg table’s internal state, exposing information about files, manifests, partitions, snapshots, and deletes. Standard SQL access makes this operational metadata usable for maintenance, monitoring, auditing, and historical analysis rather than leaving it hidden inside table mechanics. section 10.4 section 11.1.4
Use metadata tables to inspect:
- Data-file counts, sizes, partition distribution, and file statistics; these reveal small-file accumulation and uneven layouts that can impair query planning and execution. section 10.1.1 section 10.4
- Snapshots, manifests, and lineage; these show which operations occurred, when commits were made, and which files or records were added or removed. section 11.2.1
- Delete files, partition evolution, and snapshot growth; these signals help identify when compaction, snapshot expiration, or other corrective maintenance is needed. section 10.4
- Operational metrics for dashboards and alerts, including old snapshots, delete-file counts, uncompacted-file size, and unexpected snapshot-chain growth. section 11.1.4
Investigating an unexpected row-count change
Query the snapshots metadata table, compare operation summaries, and then inspect manifest metadata to locate the files involved. An overwrite showing 50,000 removed records and 48,000 added records becomes an immediate investigation target. section 11.2.1
SELECT snapshot_id, committed_at, operation, summary FROM "db "."critical_fact_table.snapshots "ORDER BY committed_at DESC;
This query illustrates the compact SQL workflow for examining recent snapshot operations and their change summaries. section 11.2.1
