metadata.json is the table-level metadata file for an Apache Iceberg table. It records snapshot history, schema definitions and versions, partition specifications, and related table state, giving query engines the information needed to understand table structure and select data files. section 2.3 section 10.1.3
Use metadata.json to coordinate table discovery, planning, evolution, and recovery:
- Resolve a table through the catalog, which returns the current metadata file location. section 7.1.2
- Plan reads and writes from schemas, partitioning, snapshots, and related file-level statistics. section 7.1.2
- Support schema evolution, time travel, and rollback by retaining current and previous table versions. section 2.3 section 7.1.2
- Coordinate concurrent commits when the catalog atomically updates its metadata pointer; conflicting updates fail rather than silently overwrite state. section 7.1.2
Figure 2.3 The structure and flow of an Apache Iceberg table read-and-write operation
Trace how the catalog, metadata.json, snapshots, manifests, and data files participate in Iceberg table reads and writes. section 2.3
The file is part of a layered metadata path: a snapshot points to one manifest list, which references manifests containing data-file locations and statistics. High-frequency ingestion can make metadata.json inefficient by accumulating many snapshots and repeated rewrites, increasing planning and commit costs. Recovery therefore requires more than restoring the file: referenced data files, paths, snapshot loadability, and client-version compatibility must also be validated. section 10.1.3 section 11.3.6
