An Iceberg branch is a named, mutable reference to a table snapshot. It can advance as new snapshots are added, making it useful for development, testing, controlled rollback, and reproducible data workflows. section 11.2.2
At the table level, a branch isolates one table’s evolving state. It differs from a tag, which immutably bookmarks one snapshot, and from catalog-level branching in Project Nessie, which can isolate and atomically merge changes across multiple tables. section 7.4.5 section 11.2.2
Operational use requires treating branches as part of snapshot and retention management:
- Use a development branch that advances with new snapshots while production remains on a stable main branch. section 11.2.2
- Use branches to isolate changes, support testing, and enable rollback without exposing incomplete table state. section 7.4.5 section 11.2.2
- Review branch retention deliberately: protected snapshots cannot expire, so long-lived branches can increase metadata and data-file storage. section 10.3.2
SELECT ref_name, type, snapshot_id, max_reference_age_in_ms FROM "db "."critical_fact_table.refs ";
Inspect a table’s refs metadata to identify each branch, its current snapshot, and any maximum reference age. section 11.2.2
