Skip to main content
Version: Next

Branching and Tagging

Branches and tags are named references to snapshots. They make snapshot history easier to manage for audit, experiments, validation, and release workflows.

Branches vs Tags​

Branch

  • Mutable reference to the head of a snapshot lineage.
  • Can receive new commits.
  • Useful for audit, backfills, experiments, and validation.

Tag

  • Named reference to a specific snapshot.
  • Usually used as a stable marker.
  • Useful for releases, month-end close, audit checkpoints, and reproducible training datasets.

Create a Branch​

ALTER TABLE prod.db.orders
CREATE BRANCH audit_branch;

Create a branch at a specific snapshot:

ALTER TABLE prod.db.orders
CREATE BRANCH audit_branch
AS OF VERSION 8333017788700497002;

Create a Tag​

ALTER TABLE prod.db.orders
CREATE TAG release_2026_05
AS OF VERSION 8333017788700497002;

Query a Branch or Tag​

SELECT *
FROM prod.db.orders
VERSION AS OF 'audit_branch';

SELECT *
FROM prod.db.orders
VERSION AS OF 'release_2026_05';

Some engines also expose branch and tag references using identifier syntax:

SELECT *
FROM prod.db.orders.`branch_audit_branch`;

Retention​

Branches and tags can have retention policies. This matters because snapshot expiration can delete history that is not protected by an active reference.

Use explicit retention for:

  • Regulatory snapshots.
  • Published data releases.
  • Long-running experiments.
  • Reproducible ML training datasets.

Typical Workflows​

Audit Branch​

Create a branch before running validation or audit queries. The branch protects the referenced history while current table writes continue.

Release Tag​

Create a tag after a successful data product release. Consumers can reproduce the exact dataset later.

Experiment Branch​

Run data fixes or backfills on a branch before promoting changes to the main table workflow.

Key Takeaway​

Branches and tags turn raw snapshot IDs into named data states. They are most useful when paired with clear retention rules and naming conventions.