Skip to main content

Manage Tags

A tag retains a snapshot and its referenced manifests and data files. Use tags to keep a dataset version available for batch reads or training. The examples assume a catalog from Catalogs and Tables. For separate writable histories, see Branches and Rollback.

Create and Delete Tag​

You can create a tag with given name and snapshot ID, and delete a tag with given name.


table = catalog.get_table('database_name.table_name')
table.create_tag("snapshot_2", snapshot_id=2)  # requires snapshot 2 to exist
table.create_tag("latest_data")  # retain the latest snapshot under another name
table.delete_tag("snapshot_2")

If snapshot_id unset, snapshot_id defaults to the latest.

Rename Tag​

You can rename a tag to a new name.


table = catalog.get_table('database_name.table_name')
table.rename_tag("old_tag", "new_tag")  # rename old_tag to new_tag

Read Tag​

You can read data from a specific tag.


table = catalog.get_table('database_name.table_name')
table.create_tag("tag2", snapshot_id=2)

# Read from tag2 using scan.tag-name option
table_with_tag = table.copy({"scan.tag-name": "tag2"})
read_builder = table_with_tag.new_read_builder()
table_scan = read_builder.new_scan()
table_read = read_builder.new_read()
result = table_read.to_arrow(table_scan.plan().splits())