CREATE SNAPSHOT TAG

Creates a named snapshot tag on a FUSE table. A snapshot tag bookmarks a specific point-in-time state of the table, allowing you to query that state later with the AT clause.

Syntax

ALTER TABLE [<database_name>.]<table_name> CREATE TAG <tag_name>
    [ AT (
        SNAPSHOT => '<snapshot_id>' |
        TIMESTAMP => <timestamp> |
        STREAM => <stream_name> |
        OFFSET => <time_interval> |
        TAG => <tag_name>
    ) ]
    [ RETAIN <n> { DAYS | SECONDS } ]

Parameters

Examples

Tag the Current Snapshot

SET enable_experimental_table_ref = 1;

CREATE TABLE t1(a INT, b STRING);
INSERT INTO t1 VALUES (1, 'a'), (2, 'b'), (3, 'c');

-- Create a tag at the current snapshot
ALTER TABLE t1 CREATE TAG v1_0;

-- Insert more data
INSERT INTO t1 VALUES (4, 'd'), (5, 'e');

-- Query the tagged snapshot (returns 3 rows, not 5)
SELECT * FROM t1 AT (TAG => v1_0) ORDER BY a;

Tag from an Existing Reference

-- Copy from an existing tag
ALTER TABLE t1 CREATE TAG v1_0_copy AT (TAG => v1_0);

-- Tag a specific snapshot
ALTER TABLE t1 CREATE TAG before_migration
    AT (SNAPSHOT => 'aaa4857c5935401790db2c9f0f2818be');

-- Tag the state from 1 hour ago
ALTER TABLE t1 CREATE TAG hourly_checkpoint AT (OFFSET => -3600);

Tag with Automatic Expiration

-- Tag expires after 7 days
ALTER TABLE t1 CREATE TAG temp_tag RETAIN 7 DAYS;

-- Tag expires after 3600 seconds
ALTER TABLE t1 CREATE TAG debug_snapshot RETAIN 3600 SECONDS;