What is the table metadata file?

The table metadata file is a JSON document that serves as the entry point describing a table's full current state: its schema (with stable column IDs, not just names), all partition specs (current and historical), sort order, the list of all snapshots, and a pointer to which snapshot is currently active.

Every change to the table — a schema change, a partition spec change, or a new snapshot from a data write — produces a brand-new metadata file rather than modifying the existing one in place, and the catalog's pointer is then atomically swapped from the old metadata file to the new one, which is the specific mechanism behind Iceberg's atomic, all-or-nothing commits.

Because the metadata file records the full history of schema and partition spec versions (not just the current one), Iceberg can correctly interpret older data files that were written under a prior schema or partition spec, which is exactly what makes schema and partition evolution possible without needing to rewrite historical data to match the newest definitions.