Branching and Tagging🔗
Overview🔗
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 necessary 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.
Use Cases🔗
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.
Historical Tags🔗
Tags can be used for retaining important historical snapshots for auditing purposes.
The above diagram demonstrates retaining important historical snapshot with the following retention policy, defined via Spark SQL.
-
Retain 1 snapshot per week for 1 month. This can be achieved by tagging the weekly snapshot and setting the tag retention to be a month. snapshots will be kept, and the branch reference itself will be retained for 1 week.
-
Retain 1 snapshot per month for 6 months. This can be achieved by tagging the monthly snapshot and setting the tag retention to be 6 months.
-
Retain 1 snapshot per year forever. This can be achieved by tagging the annual snapshot. The default retention for branches and tags is forever.
-
Create a temporary "test-branch" which is retained for 7 days and the latest 2 snapshots on the branch are retained.
Audit Branch🔗
The above diagram shows an example of using an audit branch for validating a write workflow.
- First ensure
write.wap.enabled
is set. - Create
audit-branch
starting from snapshot 3, which will be written to and retained for 1 week. - Writes are performed on a separate
audit-branch
independent from the main table history. - A validation workflow can validate (e.g. data quality) the state of
audit-branch
. - After validation, the main branch can be
fastForward
to the head ofaudit-branch
to update the main table state. - The branch reference will be removed when
expireSnapshots
is run 1 week later.
Usage🔗
Creating, querying and writing to branches and tags are supported in the Iceberg Java library, and in Spark and Flink engine integrations.
Schema selection with branches and tags🔗
It is important to understand that the schema tracked for a table is valid across all branches. When working with branches, the table's schema is used as that's the schema being validated when writing data to a branch. On the other hands, querying a tag uses the snapshot's schema, which is the schema id that snapshot pointed to when the snapshot was created.
The below examples show which schema is being used when working with branches.
Create a table and insert some data:
CREATE TABLE db.table (id bigint, data string, col float);
INSERT INTO db.table values (1, 'a', 1.0), (2, 'b', 2.0), (3, 'c', 3.0);
SELECT * FROM db.table;
1 a 1.0
2 b 2.0
3 c 3.0
Create a branch test_branch
that points to the current snapshot and read data from the branch:
ALTER TABLE db.table CREATE BRANCH test_branch;
SELECT * FROM db.table.branch_test_branch;
1 a 1.0
2 b 2.0
3 c 3.0
Modify the table's schema by dropping the col
column and adding a new column named new_col
:
ALTER TABLE db.table drop column float;
ALTER TABLE db.table add column new_col date;
INSERT INTO db.table values (4, 'd', date('2024-04-04')), (5, 'e', date('2024-05-05'));
SELECT * FROM db.table;
1 a NULL
2 b NULL
3 c NULL
4 d 2024-04-04
5 e 2024-05-05
Querying the head of the branch using one of the below statements will return data using the table's schema:
SELECT * FROM db.table.branch_test_branch;
1 a NULL
2 b NULL
3 c NULL
SELECT * FROM db.table VERSION AS OF 'test_branch';
1 a NULL
2 b NULL
3 c NULL
Performing a time travel query using the snapshot id uses the snapshot's schema:
SELECT * FROM db.table.refs;
test_branch BRANCH 8109744798576441359 NULL NULL NULL
main BRANCH 6910357365743665710 NULL NULL NULL
SELECT * FROM db.table VERSION AS OF 8109744798576441359;
1 a 1.0
2 b 2.0
3 c 3.0
When writing to the branch, the table's schema is used for validation: