docs: add snapshot tag and table versioning documentation (#3133)

* add table snapshot tag

* fix

* docs: reorganize snapshot tag sections and add note for tag distinction

- Move Snapshot Tag Operations before Swap Tables in ALTER TABLE docs
- Replace comparison table with a concise note distinguishing snapshot tags from governance tags
- Add EEFeature badge to table versioning pages
- Move table versioning guide under data-lifecycle directory

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix

* docs: add explicit anchor IDs for snapshot-tags headings

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: zhyass

docs/cn/guides/57-data-management/01-data-lifecycle.md

@@ -25,6 +25,7 @@ Databend 支持创建和修改以下对象：
 - 授权
 - 计算集群
 - 任务
+- [快照标签](/sql/sql-commands/ddl/table-versioning#snapshot-tags)
 
 ## 组织数据
 

docs/cn/sql-reference/10-sql-commands/00-ddl/01-table/90-alter-table.md

@@ -257,6 +257,20 @@ CREATE CONNECTION s3_role_conn
 ALTER TABLE sales_data CONNECTION=( connection_name = 's3_role_conn' );
 ```
 
+## 快照标签操作 {#snapshot-tag-operations}
+
+<FunctionDescription description="Introduced or updated: v1.2.891"/>
+
+创建或删除引用特定 FUSE 表快照的命名快照标签。快照标签允许您为表的某个时间点状态创建书签，以便稍后通过 [AT](../../20-query-syntax/03-query-at.md) 子句进行查询。
+
+完整语法和示例请参阅：
+- [CREATE SNAPSHOT TAG](../21-table-versioning/01-create-snapshot-tag.md)
+- [DROP SNAPSHOT TAG](../21-table-versioning/02-drop-snapshot-tag.md)
+
+:::note
+快照标签与[治理标签](#tag-operations)不同。快照标签为表快照创建书签用于时间回溯，而治理标签为对象附加键值元数据用于分类。
+:::
+
 ## 交换表 {#swap-tables}
 
 在同一个事务中交换两张表的所有元数据和数据，使双方的列、约束以及数据完全互换。
@@ -298,7 +312,7 @@ DESC t2;
 
 ## Tag 操作 {#tag-operations}
 
-为表分配或移除 Tag。Tag 必须先通过 [CREATE TAG](../08-tag/01-ddl-create-tag.md) 创建。完整说明请参阅 [SET TAG / UNSET TAG](../08-tag/04-ddl-set-tag.md)。
+为表分配或移除治理标签。治理标签是用于分类和数据治理的键值元数据。Tag 必须先通过 [CREATE TAG](../08-tag/01-ddl-create-tag.md) 创建。完整说明请参阅 [SET TAG / UNSET TAG](../08-tag/04-ddl-set-tag.md)。
 
 ### 语法
 

docs/cn/sql-reference/10-sql-commands/00-ddl/21-table-versioning/01-create-snapshot-tag.md

@@ -0,0 +1,85 @@
+---
+title: CREATE SNAPSHOT TAG
+sidebar_position: 1
+---
+
+import FunctionDescription from '@site/src/components/FunctionDescription';
+
+<FunctionDescription description="Introduced or updated: v1.2.891"/>
+
+import EEFeature from '@site/src/components/EEFeature';
+
+<EEFeature featureName='TABLE VERSIONING'/>
+
+在 FUSE 表上创建命名快照标签。快照标签为表的特定时间点状态创建书签，允许您稍后通过 [AT](../../20-query-syntax/03-query-at.md) 子句查询该状态。
+
+:::note
+- 这是一个实验性功能，需要先启用：`SET enable_experimental_table_ref = 1;`
+- 仅支持 FUSE 引擎表，不支持 Memory 引擎表和临时表。
+:::
+
+## 语法
+
+```sql
+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 } ]
+```
+
+## 参数
+
+| 参数 | 说明 |
+|------|------|
+| tag_name | 标签名称，在表内必须唯一。 |
+| AT | 指定标签引用的快照。如果省略，标签引用当前（最新）快照。支持与 [AT](../../20-query-syntax/03-query-at.md) 子句相同的选项，另外支持 `TAG` 从已有标签复制。 |
+| RETAIN | 设置自动过期时间。超过指定时间后，标签将在下次 [VACUUM](/sql/sql-commands/ddl/table/vacuum-table) 操作时被移除。不带 `RETAIN` 的标签会一直存在直到显式删除。 |
+
+## 示例
+
+### 标记当前快照
+
+```sql
+SET enable_experimental_table_ref = 1;
+
+CREATE TABLE t1(a INT, b STRING);
+INSERT INTO t1 VALUES (1, 'a'), (2, 'b'), (3, 'c');
+
+-- 在当前快照创建标签
+ALTER TABLE t1 CREATE TAG v1_0;
+
+-- 插入更多数据
+INSERT INTO t1 VALUES (4, 'd'), (5, 'e');
+
+-- 查询标签对应的快照（返回 3 行，而非 5 行）
+SELECT * FROM t1 AT (TAG => v1_0) ORDER BY a;
+```
+
+### 从已有引用创建标签
+
+```sql
+-- 从已有标签复制
+ALTER TABLE t1 CREATE TAG v1_0_copy AT (TAG => v1_0);
+
+-- 标记特定快照
+ALTER TABLE t1 CREATE TAG before_migration
+    AT (SNAPSHOT => 'aaa4857c5935401790db2c9f0f2818be');
+
+-- 标记 1 小时前的状态
+ALTER TABLE t1 CREATE TAG hourly_checkpoint AT (OFFSET => -3600);
+```
+
+### 创建带自动过期的标签
+
+```sql
+-- 标签 7 天后过期
+ALTER TABLE t1 CREATE TAG temp_tag RETAIN 7 DAYS;
+
+-- 标签 3600 秒后过期
+ALTER TABLE t1 CREATE TAG debug_snapshot RETAIN 3600 SECONDS;
+```

docs/cn/sql-reference/10-sql-commands/00-ddl/21-table-versioning/02-drop-snapshot-tag.md

@@ -0,0 +1,48 @@
+---
+title: DROP SNAPSHOT TAG
+sidebar_position: 2
+---
+
+import FunctionDescription from '@site/src/components/FunctionDescription';
+
+<FunctionDescription description="Introduced or updated: v1.2.891"/>
+
+import EEFeature from '@site/src/components/EEFeature';
+
+<EEFeature featureName='TABLE VERSIONING'/>
+
+从 FUSE 表上删除命名快照标签。删除后，被引用的快照如果没有其他标签或保留策略保护，将可以被垃圾回收。
+
+:::note
+- 这是一个实验性功能，需要先启用：`SET enable_experimental_table_ref = 1;`
+- 仅支持 FUSE 引擎表。
+:::
+
+## 语法
+
+```sql
+ALTER TABLE [<database_name>.]<table_name> DROP TAG <tag_name>
+```
+
+## 参数
+
+| 参数 | 说明 |
+|------|------|
+| tag_name | 要删除的快照标签名称。如果标签不存在，将返回错误。 |
+
+## 示例
+
+```sql
+SET enable_experimental_table_ref = 1;
+
+CREATE TABLE t1(a INT, b STRING);
+INSERT INTO t1 VALUES (1, 'a'), (2, 'b');
+
+-- 创建然后删除标签
+ALTER TABLE t1 CREATE TAG v1_0;
+ALTER TABLE t1 DROP TAG v1_0;
+
+-- 查询已删除的标签会返回错误
+SELECT * FROM t1 AT (TAG => v1_0);
+-- Error: tag 'v1_0' not found
+```

docs/cn/sql-reference/10-sql-commands/00-ddl/21-table-versioning/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "表版本管理",
+  "position": 21
+}

docs/cn/sql-reference/10-sql-commands/00-ddl/21-table-versioning/index.md

@@ -0,0 +1,41 @@
+---
+title: 表版本管理
+---
+
+import EEFeature from '@site/src/components/EEFeature';
+
+<EEFeature featureName='TABLE VERSIONING'/>
+
+表版本管理允许您为 FUSE 表的特定快照创建命名引用。这些引用不受自动保留清理的影响，为您提供稳定、可读的历史表状态指针。
+
+:::note
+表版本管理是一个实验性功能，使用前需要启用：
+
+```sql
+SET enable_experimental_table_ref = 1;
+```
+:::
+
+## 快照标签 {#snapshot-tags}
+
+快照标签通过名称固定表的某个时间点状态。创建后，标签会持有对特定快照的引用，您可以随时通过 [AT](../../20-query-syntax/03-query-at.md) 子句查询该状态，无需记录快照 ID 或时间戳。
+
+**使用场景：**
+- **发布检查点**：在数据管道运行前后标记表状态，便于比较或回滚。
+- **审计与合规**：保留命名快照用于监管审查，无需担心保留期过期。
+- **安全实验**：标记当前状态，运行实验性转换，然后查询标签验证变更。
+- **可复现分析**：固定数据集版本，确保仪表板和报告始终引用相同数据。
+
+**工作原理：**
+
+快照标签为快照附加一个可读的名称。只要标签存在，被引用的快照就会受到保护，不会被 vacuum 和垃圾回收清理 — 即使保留期已过。
+
+- 不带 `RETAIN` 的标签会一直存在，直到显式删除。
+- 带 `RETAIN <n> { DAYS | SECONDS }` 的标签会在指定时间后，在下次 vacuum 操作时自动移除。
+
+**SQL 命令：**
+
+| 命令 | 说明 |
+|------|------|
+| [CREATE SNAPSHOT TAG](01-create-snapshot-tag.md) | 在表快照上创建命名标签 |
+| [DROP SNAPSHOT TAG](02-drop-snapshot-tag.md) | 删除快照标签 |

docs/cn/sql-reference/10-sql-commands/00-ddl/index.md

@@ -10,6 +10,7 @@ title: DDL（Data Definition Language）命令
 |-----------|-------------|
 | **[数据库](00-database/index.md)** | 创建、修改和删除数据库 |
 | **[表](01-table/index.md)** | 创建、修改和管理表 |
+| **[表版本管理 (Table Versioning)](21-table-versioning/index.md)** | 创建命名快照标签用于时间回溯 |
 | **[视图 (View)](05-view/index.md)** | 基于查询创建和管理虚拟表 |
 
 ## 性能和索引

docs/cn/sql-reference/10-sql-commands/20-query-syntax/03-query-at.md

@@ -21,7 +21,8 @@ AT (
        SNAPSHOT => '<snapshot_id>' |
        TIMESTAMP => <timestamp> |
        STREAM => <stream_name> |
-       OFFSET => <time_interval>
+       OFFSET => <time_interval> |
+       TAG => <tag_name>
    )
 ```
 
@@ -31,6 +32,7 @@ AT (
 | TIMESTAMP | 指定要从中检索数据的特定时间戳。                                                                                                |
 | STREAM    | 表示查询创建指定流时的数据。                                                                                                    |
 | OFFSET    | 指定从当前时间回溯的秒数。它应该采用负整数的形式，其中绝对值表示以秒为单位的时间差。例如，`-3600` 表示回溯 1 小时（3,600 秒）。 |
+| TAG       | 指定通过 `ALTER TABLE ... CREATE TAG` 创建的命名标签，用于查询该标签关联的快照。这是一个实验性功能，需要 `SET enable_experimental_table_ref = 1`。参见[快照标签操作](/sql/sql-commands/ddl/table/alter-table#snapshot-tag-operations)。 |
 
 ## 获取快照 ID 和时间戳
 
@@ -94,3 +96,26 @@ SELECT * FROM t AT (STREAM => s);
 -- 检索表 't' 中的所有列，其中包含 60 秒前的数据
 SELECT * FROM t AT (OFFSET => -60);
 ```
+
+4. 使用命名标签查询数据（实验性功能）。
+
+```sql
+SET enable_experimental_table_ref = 1;
+
+-- 在当前快照创建标签
+ALTER TABLE t CREATE TAG v1_0;
+
+-- 插入更多数据
+INSERT INTO t VALUES(4);
+
+-- 查询标签对应的快照（返回最后一次插入之前的数据）
+SELECT * FROM t AT (TAG => v1_0) ORDER BY a;
+
+┌─────────────────┐
+│        a        │
+├─────────────────┤
+│               1 │
+│               2 │
+│               3 │
+└─────────────────┘
+```

docs/en/guides/57-data-management/01-data-lifecycle.md

@@ -25,6 +25,7 @@ Databend supports the following objects to create and modify them:
 - Grants
 - Warehouse
 - Task
+- [Snapshot Tag](/sql/sql-commands/ddl/table-versioning#snapshot-tags)
 
 ## Organizing Data
 

docs/en/sql-reference/10-sql-commands/00-ddl/01-table/90-alter-table.md

@@ -359,6 +359,20 @@ CREATE CONNECTION s3_role_conn
 ALTER TABLE sales_data CONNECTION=( connection_name = 's3_role_conn' );
 ```
 
+## Snapshot Tag Operations {#snapshot-tag-operations}
+
+<FunctionDescription description="Introduced or updated: v1.2.891"/>
+
+Creates or drops a named snapshot tag that references a specific FUSE table snapshot. Snapshot tags let you bookmark a point-in-time state of a table so you can query it later with the [AT](../../20-query-syntax/03-query-at.md) clause.
+
+For full details, see:
+- [CREATE SNAPSHOT TAG](../21-table-versioning/01-create-snapshot-tag.md)
+- [DROP SNAPSHOT TAG](../21-table-versioning/02-drop-snapshot-tag.md)
+
+:::note
+Snapshot tags are different from [governance tags](#tag-operations). Snapshot tags bookmark a table snapshot for time travel, while governance tags attach key-value metadata to objects for classification.
+:::
+
 ## Swap Tables {#swap-tables}
 
 Swaps all table metadata and data between two tables atomically in a single transaction. This operation exchanges the table schemas, including all columns, constraints, and data, effectively making each table take on the identity of the other.
@@ -404,7 +418,7 @@ DESC t2;
 
 ## Tag Operations {#tag-operations}
 
-Assigns or removes tags on a table. Tags must be created with [CREATE TAG](../08-tag/01-ddl-create-tag.md) first. For full details, see [SET TAG / UNSET TAG](../08-tag/04-ddl-set-tag.md).
+Assigns or removes governance tags on a table. Governance tags are key-value metadata for classification and data governance. Tags must be created with [CREATE TAG](../08-tag/01-ddl-create-tag.md) first. For full details, see [SET TAG / UNSET TAG](../08-tag/04-ddl-set-tag.md).
 
 ### Syntax