A field ID gives each column a stable logical identity independent of its name, position, or physical representation. Apache Iceberg uses these identifiers to separate table schema from individual file schemas, allowing files written under different schemas to coexist safely. section 5.3.1 section 6.1.3
Field IDs support schema changes without rewriting existing data files:
- Rename columns while preserving their logical identity. section 5.3.1 section 6.1.3
- Reorder columns without treating their positions as new meanings. section 5.3.1 section 6.1.3
- Widen compatible types and keep older and newer schemas queryable together. section 5.3.1 section 6.1.3
Evolving an ingestion schema
An ingestion job reads the current Iceberg schema, compares it with incoming data, and maps a renamed, reordered, or newly added field to the appropriate table identity. Existing files remain valid while the table adopts the updated definition. section 6.1.3 section 5.3.1
