Skip to main content

CLI: Tags and Branches

Retain a dataset snapshot with a tag or work on a separate table history with a branch. Configure the CLI first, and use a table that already has committed data. Commands below illustrate separate operations; choose the ones you need.

Tag Commands​

Manage tags (named snapshots) on a table. Tags are useful for time travel and pinning a snapshot for later access.

paimon tag <create|list|get|delete> mydb.users ...

Tag Create​

# Tag the latest snapshot
paimon tag create mydb.users v1

# Tag a specific snapshot
paimon tag create mydb.users v1 --snapshot-id 3

# Do not error if the tag already exists
paimon tag create mydb.users v1 --ignore-if-exists

Options:

  • --snapshot-id, -s: Snapshot id to tag (default: the latest snapshot)
  • --ignore-if-exists, -i: Do not raise an error if the tag already exists

Tag List​

# List all tags
paimon tag list mydb.users

# Only tags with a name prefix
paimon tag list mydb.users --prefix prod_

# JSON output
paimon tag list mydb.users --format json

Options:

  • --prefix, -p: Only list tags whose name starts with this prefix
  • --format, -f: Output format, table (default) or json

Tag Get​

paimon tag get mydb.users v1

# JSON output
paimon tag get mydb.users v1 --format json

Options:

  • --format, -f: Output format, table (default) or json

Tag Delete​

paimon tag delete mydb.users v1

Branch Commands​

Manage separate table histories. Create an empty branch with the current schema, or initialize a branch with data from a retained tag. A branch can later be fast-forwarded into main. See Branches and Rollback for the Python API.

paimon branch <create|list|delete|rename|fast-forward> mydb.users ...

Branch Create​

# Create an empty branch with the current schema
paimon branch create mydb.users b1

# Create a branch from an existing tag
paimon branch create mydb.users b1 --tag v1

Options:

  • --tag, -t: Initialize the branch from this tag (default: an empty branch with the current schema)

Branch List​

# List all branches
paimon branch list mydb.users

# JSON output
paimon branch list mydb.users --format json

Options:

  • --format, -f: Output format, table (default) or json

Branch Delete​

paimon branch delete mydb.users b1

Branch Rename​

paimon branch rename mydb.users b1 b2

Branch Fast-Forward​

Fast-forward the main branch to the given branch (main adopts the branch's snapshots).

paimon branch fast-forward mydb.users b1