Iceberg table metadata maintains a snapshot log, which represents the changes applied to a table. Snapshots are fundamental in Iceberg as they are the basis for reader isolation and time travel queries. For controlling metadata size and storage costs, Iceberg provides snapshot lifecycle management procedures such as expire_snapshots
for removing unused snapshots and no longer neccessary data files based on table snapshot retention properties.
For more sophisticated snapshot lifecycle management, Iceberg supports branches and tags which are named references to snapshots with their own independent lifecycles. This lifecycle is controlled by branch and tag level retention policies. Branches are independent lineages of snapshots and point to the head of the lineage. Branches and tags have a maximum reference age property which control when the reference to the snapshot itself should be expired. Branches have retention properties which define the minimum number of snapshots to retain on a branch as well as the maximum age of individual snapshots to retain on the branch. These properties are used when the expireSnapshots procedure is run. For details on the algorithm for expireSnapshots, refer to the spec.
Branching and tagging can be used for handling GDPR requirements and retaining important historical snapshots for auditing. Branches can also be used as part of data engineering workflows, for enabling experimental branches for testing and validating new jobs. See below for some examples of how branching and tagging can facilitate these use cases.
Tags can be used for retaining important historical snapshots for auditing purposes.
The above diagram demonstrates retaininig important historical snapshot with the following retention policy, defined via Spark SQL.
-- Create a tag for the first end of week snapshot. Retain the snapshot for a week ALTER TABLE prod.db.table CREATE TAG 'EOW-01' AS OF VERSION 7 RETAIN 7 DAYS
-- Create a tag for the first end of month snapshot. Retain the snapshot for 6 months ALTER TABLE prod.db.table CREATE TAG 'EOM-01' AS OF VERSION 30 RETAIN 180 DAYS
-- Create a tag for the end of the year and retain it forever. ALTER TABLE prod.db.table CREATE TAG 'EOY-2023' AS OF VERSION 365
-- Create a branch "test-branch" which will be retained for 7 days along with the latest 2 snapshots ALTER TABLE prod.db.table CREATE BRANCH test-branch RETAIN 7 DAYS WITH RETENTION 2 SNAPSHOTS
The above diagram shows an example of using an audit branch for validating a write workflow.
write.wap.enabled
is set.ALTER TABLE db.table SET TBLPROPERTIES ( 'write.wap.enabled''true' )
audit-branch
starting from snapshot 3, which will be written to and retained for 1 week.ALTER TABLE db.table CREATE BRANCH `audit-branch` AS OF VERSION 3 RETAIN 7 DAYS
audit-branch
independent from the main table history.-- WAP Branch write SET spark.wap.branch = 'audit-branch' INSERT INTO prod.db.table VALUES (3, 'c')
audit-branch
.fastForward
to the head of audit-branch
to update the main table state.table.manageSnapshots().fastForward("main", "audit-branch").commit()
expireSnapshots
is run 1 week later.Creating, querying and writing to branches and tags are supported in the Iceberg Java library, and in Spark and Flink engine integrations.