From 40c053e915198e6deac0baceea91c5b6c2eb2bd6 Mon Sep 17 00:00:00 2001
From: zhyass <mytesla@live.com>
Date: Thu, 2 Apr 2026 21:29:31 +0800
Subject: [PATCH 1/5] add table snapshot tag

---
 .../01-data-lifecycle/05-table-versioning.md  | 36 ++++++++
 .../index.md}                                 |  1 +
 docs/cn/guides/57-data-management/index.md    |  2 +-
 .../00-ddl/01-table/90-alter-table.md         | 21 ++++-
 .../01-create-snapshot-tag.md                 | 85 +++++++++++++++++++
 .../02-drop-snapshot-tag.md                   | 48 +++++++++++
 .../21-table-versioning/_category_.json       |  4 +
 .../00-ddl/21-table-versioning/index.md       | 26 ++++++
 .../10-sql-commands/00-ddl/index.md           |  1 +
 .../20-query-syntax/03-query-at.md            | 27 +++++-
 .../01-data-lifecycle/05-table-versioning.md  | 36 ++++++++
 .../index.md}                                 |  1 +
 docs/en/guides/57-data-management/index.md    |  2 +-
 .../00-ddl/01-table/90-alter-table.md         | 12 ++-
 .../01-create-snapshot-tag.md                 | 85 +++++++++++++++++++
 .../02-drop-snapshot-tag.md                   | 48 +++++++++++
 .../21-table-versioning/_category_.json       |  4 +
 .../00-ddl/21-table-versioning/index.md       | 26 ++++++
 .../10-sql-commands/00-ddl/index.md           |  1 +
 .../20-query-syntax/03-query-at.md            | 29 ++++++-
 20 files changed, 488 insertions(+), 7 deletions(-)
 create mode 100644 docs/cn/guides/57-data-management/01-data-lifecycle/05-table-versioning.md
 rename docs/cn/guides/57-data-management/{01-data-lifecycle.md => 01-data-lifecycle/index.md} (99%)
 create mode 100644 docs/cn/sql-reference/10-sql-commands/00-ddl/21-table-versioning/01-create-snapshot-tag.md
 create mode 100644 docs/cn/sql-reference/10-sql-commands/00-ddl/21-table-versioning/02-drop-snapshot-tag.md
 create mode 100644 docs/cn/sql-reference/10-sql-commands/00-ddl/21-table-versioning/_category_.json
 create mode 100644 docs/cn/sql-reference/10-sql-commands/00-ddl/21-table-versioning/index.md
 create mode 100644 docs/en/guides/57-data-management/01-data-lifecycle/05-table-versioning.md
 rename docs/en/guides/57-data-management/{01-data-lifecycle.md => 01-data-lifecycle/index.md} (99%)
 create mode 100644 docs/en/sql-reference/10-sql-commands/00-ddl/21-table-versioning/01-create-snapshot-tag.md
 create mode 100644 docs/en/sql-reference/10-sql-commands/00-ddl/21-table-versioning/02-drop-snapshot-tag.md
 create mode 100644 docs/en/sql-reference/10-sql-commands/00-ddl/21-table-versioning/_category_.json
 create mode 100644 docs/en/sql-reference/10-sql-commands/00-ddl/21-table-versioning/index.md

diff --git a/docs/cn/guides/57-data-management/01-data-lifecycle/05-table-versioning.md b/docs/cn/guides/57-data-management/01-data-lifecycle/05-table-versioning.md
new file mode 100644
index 0000000000..e9ea01e1aa
--- /dev/null
+++ b/docs/cn/guides/57-data-management/01-data-lifecycle/05-table-versioning.md
@@ -0,0 +1,36 @@
+---
+title: 表版本管理
+sidebar_label: 表版本管理
+---
+
+import EEFeature from '@site/src/components/EEFeature';
+
+<EEFeature featureName='TABLE VERSIONING'/>
+
+表版本管理允许您为 FUSE 表的特定快照创建命名引用。这些引用不受自动保留清理的影响，为您提供稳定、可读的历史表状态指针。
+
+:::note
+这是一个实验性功能，使用前需要启用：`SET enable_experimental_table_ref = 1;`
+:::
+
+## 快照标签
+
+快照标签通过名称固定表的某个时间点状态。创建后，标签会持有对特定快照的引用，您可以随时查询该状态，无需记录快照 ID 或时间戳。
+
+**使用场景：**
+- **发布检查点**：在数据管道运行前后标记表状态，便于比较或回滚。
+- **审计与合规**：保留命名快照用于监管审查，无需担心保留期过期。
+- **安全实验**：标记当前状态，运行实验性转换，然后查询标签验证变更。
+- **可复现分析**：固定数据集版本，确保仪表板和报告始终引用相同数据。
+
+**工作原理：**
+
+快照标签为快照附加一个可读的名称。只要标签存在，被引用的快照就会受到保护，不会被 vacuum 和垃圾回收清理 — 即使保留期已过。
+
+- 不带 `RETAIN` 的标签会一直存在，直到显式删除。
+- 带 `RETAIN <n> DAYS | SECONDS` 的标签会在指定时间后，在下次 vacuum 操作时自动移除。
+
+**SQL 命令：**
+- [CREATE SNAPSHOT TAG](/sql/sql-commands/ddl/table-versioning/create-snapshot-tag) — 在表快照上创建命名标签。
+- [DROP SNAPSHOT TAG](/sql/sql-commands/ddl/table-versioning/drop-snapshot-tag) — 删除快照标签。
+- [AT (TAG => ...)](/sql/sql-commands/query-syntax/query-at) — 查询标签对应的快照数据。
diff --git a/docs/cn/guides/57-data-management/01-data-lifecycle.md b/docs/cn/guides/57-data-management/01-data-lifecycle/index.md
similarity index 99%
rename from docs/cn/guides/57-data-management/01-data-lifecycle.md
rename to docs/cn/guides/57-data-management/01-data-lifecycle/index.md
index bf5ed2221e..abe589bc7b 100644
--- a/docs/cn/guides/57-data-management/01-data-lifecycle.md
+++ b/docs/cn/guides/57-data-management/01-data-lifecycle/index.md
@@ -25,6 +25,7 @@ Databend 支持创建和修改以下对象：
 - 授权
 - 计算集群
 - 任务
+- 快照标签
 
 ## 组织数据
 
diff --git a/docs/cn/guides/57-data-management/index.md b/docs/cn/guides/57-data-management/index.md
index c7118a454f..e69cf1ffeb 100644
--- a/docs/cn/guides/57-data-management/index.md
+++ b/docs/cn/guides/57-data-management/index.md
@@ -6,7 +6,7 @@ title: 数据管理
 
 | 类别 | 描述 | 主要功能 | 常用操作 |
 |----------|-------------|--------------|------------------|
-| **[数据生命周期](./01-data-lifecycle.md)** | 创建和管理对象 | • 数据库和表 <br/>• 外部表<br/>• Stream 和视图<br/>• 索引和 Stage | • CREATE/DROP/ALTER<br/>• SHOW TABLES<br/>• DESCRIBE TABLE |
+| **[数据生命周期](./01-data-lifecycle/index.md)** | 创建和管理对象 | • 数据库和表 <br/>• 外部表<br/>• Stream 和视图<br/>• 索引和 Stage<br/>• 表版本管理 | • CREATE/DROP/ALTER<br/>• SHOW TABLES<br/>• DESCRIBE TABLE |
 | **[数据恢复](./02-data-recovery.md)** | 访问和恢复历史数据 | • 时间回溯<br/>• 闪回表<br/>• 备份和恢复<br/>• AT 和 UNDROP | • SELECT ... AT<br/>• FLASHBACK TABLE<br/>• BENDSAVE BACKUP |
 | **[数据保护](./03-data-protection.md)** | 安全访问和防止数据丢失 | • 网络策略<br/>• 访问控制<br/>• 时间回溯和故障安全<br/>• 数据加密 | • NETWORK POLICY<br/>• GRANT/REVOKE<br/>• USER/ROLE |
 | **[数据回收](./04-data-recycle.md)** | 释放存储空间 | • VACUUM 命令<br/>• 保留策略<br/>• 孤立文件清理<br/>• 临时文件管理 | • VACUUM TABLE<br/>• VACUUM DROP TABLE<br/>• DATA_RETENTION_TIME |
\ No newline at end of file
diff --git a/docs/cn/sql-reference/10-sql-commands/00-ddl/01-table/90-alter-table.md b/docs/cn/sql-reference/10-sql-commands/00-ddl/01-table/90-alter-table.md
index aec8415a30..eea4e6e516 100644
--- a/docs/cn/sql-reference/10-sql-commands/00-ddl/01-table/90-alter-table.md
+++ b/docs/cn/sql-reference/10-sql-commands/00-ddl/01-table/90-alter-table.md
@@ -296,9 +296,28 @@ DESC t1;
 DESC t2;
 ```
 
+## 快照标签操作 {#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)
+
+### 快照标签 vs. 治理标签 {#snapshot-tags-vs-governance-tags}
+
+| | 快照标签 | 治理标签 |
+|---|---|---|
+| 用途 | 为表快照创建书签，用于时间回溯 | 附加键值元数据，用于分类 |
+| 语法 | `ALTER TABLE ... CREATE TAG <name>` | `ALTER TABLE ... SET TAG <key> = '<value>'` |
+| 查询 | `SELECT ... AT (TAG => "<name>")` | `SELECT * FROM TAG_REFERENCES(...)` |
+| 范围 | 仅限表，引用快照 | 任何对象（表、数据库、视图等） |
+
 ## 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)。
 
 ### 语法
 
diff --git a/docs/cn/sql-reference/10-sql-commands/00-ddl/21-table-versioning/01-create-snapshot-tag.md b/docs/cn/sql-reference/10-sql-commands/00-ddl/21-table-versioning/01-create-snapshot-tag.md
new file mode 100644
index 0000000000..a324a9868e
--- /dev/null
+++ b/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 => <existing_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;
+```
diff --git a/docs/cn/sql-reference/10-sql-commands/00-ddl/21-table-versioning/02-drop-snapshot-tag.md b/docs/cn/sql-reference/10-sql-commands/00-ddl/21-table-versioning/02-drop-snapshot-tag.md
new file mode 100644
index 0000000000..257caee3d4
--- /dev/null
+++ b/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
+```
diff --git a/docs/cn/sql-reference/10-sql-commands/00-ddl/21-table-versioning/_category_.json b/docs/cn/sql-reference/10-sql-commands/00-ddl/21-table-versioning/_category_.json
new file mode 100644
index 0000000000..074fb7887b
--- /dev/null
+++ b/docs/cn/sql-reference/10-sql-commands/00-ddl/21-table-versioning/_category_.json
@@ -0,0 +1,4 @@
+{
+  "label": "表版本管理",
+  "position": 21
+}
diff --git a/docs/cn/sql-reference/10-sql-commands/00-ddl/21-table-versioning/index.md b/docs/cn/sql-reference/10-sql-commands/00-ddl/21-table-versioning/index.md
new file mode 100644
index 0000000000..ee24087afe
--- /dev/null
+++ b/docs/cn/sql-reference/10-sql-commands/00-ddl/21-table-versioning/index.md
@@ -0,0 +1,26 @@
+---
+title: 表版本管理
+---
+
+import EEFeature from '@site/src/components/EEFeature';
+
+<EEFeature featureName='TABLE VERSIONING'/>
+
+表版本管理允许您为 FUSE 表的特定快照创建命名引用。这些引用不受自动保留清理的影响，为您提供稳定、可读的历史表状态指针。
+
+:::note
+表版本管理是一个实验性功能，使用前需要启用：
+
+```sql
+SET enable_experimental_table_ref = 1;
+```
+:::
+
+## 快照标签
+
+快照标签通过名称固定表的某个时间点状态。您可以随时通过 [AT](../../20-query-syntax/03-query-at.md) 子句查询标签对应的状态，无需记录快照 ID 或时间戳。
+
+| 命令 | 说明 |
+|------|------|
+| [CREATE SNAPSHOT TAG](01-create-snapshot-tag.md) | 在表快照上创建命名标签 |
+| [DROP SNAPSHOT TAG](02-drop-snapshot-tag.md) | 删除快照标签 |
diff --git a/docs/cn/sql-reference/10-sql-commands/00-ddl/index.md b/docs/cn/sql-reference/10-sql-commands/00-ddl/index.md
index 988ae50570..7fa51bd219 100644
--- a/docs/cn/sql-reference/10-sql-commands/00-ddl/index.md
+++ b/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)** | 基于查询创建和管理虚拟表 |
 
 ## 性能和索引
diff --git a/docs/cn/sql-reference/10-sql-commands/20-query-syntax/03-query-at.md b/docs/cn/sql-reference/10-sql-commands/20-query-syntax/03-query-at.md
index 2422d65a00..a0cbcc0720 100644
--- a/docs/cn/sql-reference/10-sql-commands/20-query-syntax/03-query-at.md
+++ b/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 │
+└─────────────────┘
+```
diff --git a/docs/en/guides/57-data-management/01-data-lifecycle/05-table-versioning.md b/docs/en/guides/57-data-management/01-data-lifecycle/05-table-versioning.md
new file mode 100644
index 0000000000..c3e2571803
--- /dev/null
+++ b/docs/en/guides/57-data-management/01-data-lifecycle/05-table-versioning.md
@@ -0,0 +1,36 @@
+---
+title: Table Versioning
+sidebar_label: Table Versioning
+---
+
+import EEFeature from '@site/src/components/EEFeature';
+
+<EEFeature featureName='TABLE VERSIONING'/>
+
+Table versioning lets you create named references to specific snapshots of a FUSE table. These references survive automatic retention cleanup, giving you stable, human-readable pointers to historical table states.
+
+:::note
+This is an experimental feature. Enable it before use: `SET enable_experimental_table_ref = 1;`
+:::
+
+## Snapshot Tags
+
+Snapshot tags pin a specific point-in-time state of a table by name. Once created, a tag holds a reference to a particular snapshot so you can query that exact state at any time, without needing to track snapshot IDs or timestamps.
+
+**Use cases:**
+- **Release checkpoints**: Tag the table state before and after a data pipeline run so you can compare or roll back.
+- **Audit and compliance**: Preserve a named snapshot for regulatory review without worrying about retention expiry.
+- **Safe experimentation**: Tag the current state, run experimental transforms, then query the tag to verify what changed.
+- **Reproducible analytics**: Pin a dataset version so dashboards and reports always reference the same data.
+
+**How it works:**
+
+A snapshot tag attaches a human-readable name to a snapshot. As long as the tag exists, the referenced snapshot is protected from vacuum and garbage collection — even if the retention period has passed.
+
+- A tag without `RETAIN` lives until explicitly dropped.
+- A tag with `RETAIN <n> DAYS | SECONDS` is automatically removed after the specified duration during the next vacuum operation.
+
+**SQL Commands:**
+- [CREATE SNAPSHOT TAG](/sql/sql-commands/ddl/table-versioning/create-snapshot-tag) — Create a named tag on a table snapshot.
+- [DROP SNAPSHOT TAG](/sql/sql-commands/ddl/table-versioning/drop-snapshot-tag) — Remove a snapshot tag.
+- [AT (TAG => ...)](/sql/sql-commands/query-syntax/query-at) — Query data at a tagged snapshot.
diff --git a/docs/en/guides/57-data-management/01-data-lifecycle.md b/docs/en/guides/57-data-management/01-data-lifecycle/index.md
similarity index 99%
rename from docs/en/guides/57-data-management/01-data-lifecycle.md
rename to docs/en/guides/57-data-management/01-data-lifecycle/index.md
index e5322eeced..924b2b70d2 100644
--- a/docs/en/guides/57-data-management/01-data-lifecycle.md
+++ b/docs/en/guides/57-data-management/01-data-lifecycle/index.md
@@ -25,6 +25,7 @@ Databend supports the following objects to create and modify them:
 - Grants
 - Warehouse
 - Task
+- Tag
 
 ## Organizing Data
 
diff --git a/docs/en/guides/57-data-management/index.md b/docs/en/guides/57-data-management/index.md
index 7b0d5e4167..df878e7f60 100644
--- a/docs/en/guides/57-data-management/index.md
+++ b/docs/en/guides/57-data-management/index.md
@@ -6,7 +6,7 @@ title: Data Management
 
 | Category | Description | Key Features | Common Operations |
 |----------|-------------|--------------|------------------|
-| **[Data Lifecycle](./01-data-lifecycle.md)** | Create and manage objects | • Database & Table <br/>• External Tables<br/>• Streams & Views<br/>• Indexes & Stages | • CREATE/DROP/ALTER<br/>• SHOW TABLES<br/>• DESCRIBE TABLE |
+| **[Data Lifecycle](./01-data-lifecycle/index.md)** | Create and manage objects | • Database & Table <br/>• External Tables<br/>• Streams & Views<br/>• Indexes & Stages<br/>• Table Versioning | • CREATE/DROP/ALTER<br/>• SHOW TABLES<br/>• DESCRIBE TABLE |
 | **[Data Recovery](./02-data-recovery.md)** | Access and restore past data | • Time Travel<br/>• Flashback Tables<br/>• Backup & Restore<br/>• AT & UNDROP | • SELECT ... AT<br/>• FLASHBACK TABLE<br/>• BENDSAVE BACKUP |
 | **[Data Protection](./03-data-protection.md)** | Secure access and prevent loss | • Network Policies<br/>• Access Control<br/>• Time Travel & Fail-safe<br/>• Data Encryption | • NETWORK POLICY<br/>• GRANT/REVOKE<br/>• USER/ROLE |
 | **[Data Recycle](./04-data-recycle.md)** | Free up storage space | • VACUUM Commands<br/>• Retention Policies<br/>• Orphan File Cleanup<br/>• Temporary File Management | • VACUUM TABLE<br/>• VACUUM DROP TABLE<br/>• DATA_RETENTION_TIME |
diff --git a/docs/en/sql-reference/10-sql-commands/00-ddl/01-table/90-alter-table.md b/docs/en/sql-reference/10-sql-commands/00-ddl/01-table/90-alter-table.md
index c233824b25..80e558c357 100644
--- a/docs/en/sql-reference/10-sql-commands/00-ddl/01-table/90-alter-table.md
+++ b/docs/en/sql-reference/10-sql-commands/00-ddl/01-table/90-alter-table.md
@@ -402,9 +402,19 @@ DESC t1;
 DESC t2;
 ```
 
+## 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)
+
 ## 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
 
diff --git a/docs/en/sql-reference/10-sql-commands/00-ddl/21-table-versioning/01-create-snapshot-tag.md b/docs/en/sql-reference/10-sql-commands/00-ddl/21-table-versioning/01-create-snapshot-tag.md
new file mode 100644
index 0000000000..d0d2925fd4
--- /dev/null
+++ b/docs/en/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'/>
+
+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](../../20-query-syntax/03-query-at.md) clause.
+
+:::note
+- This is an experimental feature. Enable it first: `SET enable_experimental_table_ref = 1;`
+- Only supported on FUSE engine tables. Memory engine tables and temporary tables are not supported.
+:::
+
+## Syntax
+
+```sql
+ALTER TABLE [<database_name>.]<table_name> CREATE TAG <tag_name>
+    [ AT (
+        SNAPSHOT => '<snapshot_id>' |
+        TIMESTAMP => <timestamp> |
+        STREAM => <stream_name> |
+        OFFSET => <time_interval> |
+        TAG => <existing_tag_name>
+    ) ]
+    [ RETAIN <n> DAYS | SECONDS ]
+```
+
+## Parameters
+
+| Parameter | Description |
+|-----------|-------------|
+| tag_name  | The name of the tag. Must be unique within the table. |
+| AT        | Specifies which snapshot the tag references. If omitted, the tag references the current (latest) snapshot. Supports the same options as the [AT](../../20-query-syntax/03-query-at.md) clause, plus `TAG` to copy from an existing tag. |
+| RETAIN    | Sets an automatic expiration period. After the specified duration, the tag is removed during the next [VACUUM](/sql/sql-commands/ddl/table/vacuum-table) operation. Without `RETAIN`, the tag persists until explicitly dropped. |
+
+## Examples
+
+### Tag the Current Snapshot
+
+```sql
+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
+
+```sql
+-- 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
+
+```sql
+-- 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;
+```
diff --git a/docs/en/sql-reference/10-sql-commands/00-ddl/21-table-versioning/02-drop-snapshot-tag.md b/docs/en/sql-reference/10-sql-commands/00-ddl/21-table-versioning/02-drop-snapshot-tag.md
new file mode 100644
index 0000000000..502b826ad5
--- /dev/null
+++ b/docs/en/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'/>
+
+Drops a named snapshot tag from a FUSE table. Once dropped, the referenced snapshot becomes eligible for garbage collection if no other tags or retention policies protect it.
+
+:::note
+- This is an experimental feature. Enable it first: `SET enable_experimental_table_ref = 1;`
+- Only supported on FUSE engine tables.
+:::
+
+## Syntax
+
+```sql
+ALTER TABLE [<database_name>.]<table_name> DROP TAG <tag_name>
+```
+
+## Parameters
+
+| Parameter | Description |
+|-----------|-------------|
+| tag_name  | The name of the snapshot tag to drop. An error is returned if the tag does not exist. |
+
+## Examples
+
+```sql
+SET enable_experimental_table_ref = 1;
+
+CREATE TABLE t1(a INT, b STRING);
+INSERT INTO t1 VALUES (1, 'a'), (2, 'b');
+
+-- Create and then drop a tag
+ALTER TABLE t1 CREATE TAG v1_0;
+ALTER TABLE t1 DROP TAG v1_0;
+
+-- Querying a dropped tag returns an error
+SELECT * FROM t1 AT (TAG => "v1_0");
+-- Error: tag 'v1_0' not found
+```
diff --git a/docs/en/sql-reference/10-sql-commands/00-ddl/21-table-versioning/_category_.json b/docs/en/sql-reference/10-sql-commands/00-ddl/21-table-versioning/_category_.json
new file mode 100644
index 0000000000..b0bebd6329
--- /dev/null
+++ b/docs/en/sql-reference/10-sql-commands/00-ddl/21-table-versioning/_category_.json
@@ -0,0 +1,4 @@
+{
+  "label": "Table Versioning",
+  "position": 21
+}
diff --git a/docs/en/sql-reference/10-sql-commands/00-ddl/21-table-versioning/index.md b/docs/en/sql-reference/10-sql-commands/00-ddl/21-table-versioning/index.md
new file mode 100644
index 0000000000..471c818206
--- /dev/null
+++ b/docs/en/sql-reference/10-sql-commands/00-ddl/21-table-versioning/index.md
@@ -0,0 +1,26 @@
+---
+title: Table Versioning
+---
+
+import EEFeature from '@site/src/components/EEFeature';
+
+<EEFeature featureName='TABLE VERSIONING'/>
+
+Table versioning lets you create named references to specific snapshots of a FUSE table. These references survive automatic retention cleanup, giving you stable, human-readable pointers to historical table states.
+
+:::note
+Table versioning is an experimental feature. Enable it before use:
+
+```sql
+SET enable_experimental_table_ref = 1;
+```
+:::
+
+## Snapshot Tags
+
+A snapshot tag pins a specific point-in-time state of a table by name. You can query the tagged state at any time using the [AT](../../20-query-syntax/03-query-at.md) clause, without needing to track snapshot IDs or timestamps.
+
+| Command | Description |
+|---------|-------------|
+| [CREATE SNAPSHOT TAG](01-create-snapshot-tag.md) | Create a named tag on a table snapshot |
+| [DROP SNAPSHOT TAG](02-drop-snapshot-tag.md) | Remove a snapshot tag |
diff --git a/docs/en/sql-reference/10-sql-commands/00-ddl/index.md b/docs/en/sql-reference/10-sql-commands/00-ddl/index.md
index d2e49bdd11..18969db93a 100644
--- a/docs/en/sql-reference/10-sql-commands/00-ddl/index.md
+++ b/docs/en/sql-reference/10-sql-commands/00-ddl/index.md
@@ -10,6 +10,7 @@ These topics provide reference information for the DDL (Data Definition Language
 |-----------|-------------|
 | **[Database](00-database/index.md)** | Create, alter, and drop databases |
 | **[Table](01-table/index.md)** | Create, alter, and manage tables |
+| **[Table Versioning](21-table-versioning/index.md)** | Create named snapshot tags for time travel |
 | **[View](05-view/index.md)** | Create and manage virtual tables based on queries |
 
 ## Performance & Indexing
diff --git a/docs/en/sql-reference/10-sql-commands/20-query-syntax/03-query-at.md b/docs/en/sql-reference/10-sql-commands/20-query-syntax/03-query-at.md
index 576067058f..30c0779226 100644
--- a/docs/en/sql-reference/10-sql-commands/20-query-syntax/03-query-at.md
+++ b/docs/en/sql-reference/10-sql-commands/20-query-syntax/03-query-at.md
@@ -20,8 +20,9 @@ AT (
        SNAPSHOT => '<snapshot_id>' |
        TIMESTAMP => <timestamp> | 
        STREAM => <stream_name> |
-       OFFSET => <time_interval> 
-   )   
+       OFFSET => <time_interval> |
+       TAG => '<tag_name>'
+   )
 ```
 
 | Parameter | Description                                                                                                                                                                                                                                                                                                      |
@@ -30,6 +31,7 @@ AT (
 | TIMESTAMP | Specifies a particular timestamp to retrieve data from.                                                                                                                                                                                                                                                          |
 | STREAM    | Indicates querying the data at the time the specified stream was created.                                                                                                                                                                                                                                        |
 | OFFSET    | Specifies the number of seconds to go back from the current time. It should be in the form of a negative integer, where the absolute value represents the time difference in seconds. For example, `-3600` represents traveling back in time by 1 hour (3,600 seconds). |
+| TAG       | Specifies a named tag created by `ALTER TABLE ... CREATE TAG` to query the snapshot associated with that tag. This is an experimental feature and requires `SET enable_experimental_table_ref = 1`. See [Snapshot Tag Operations](/sql/sql-commands/ddl/table/alter-table#snapshot-tag-operations). |
 
 ## Obtaining Snapshot ID and Timestamp
 
@@ -92,4 +94,27 @@ SELECT * FROM t AT (STREAM => s);
 
 -- Retrieve all columns from table 't' with data from 60 seconds ago
 SELECT * FROM t AT (OFFSET => -60);
+```
+
+4. Query data using a named tag (experimental).
+
+```sql
+SET enable_experimental_table_ref = 1;
+
+-- Create a tag at the current snapshot
+ALTER TABLE t CREATE TAG v1_0;
+
+-- Insert more data
+INSERT INTO t VALUES(4);
+
+-- Query the tagged snapshot (returns data before the last insert)
+SELECT * FROM t AT (TAG => "v1_0") ORDER BY a;
+
+┌─────────────────┐
+│        a        │
+├─────────────────┤
+│               1 │
+│               2 │
+│               3 │
+└─────────────────┘
 ```
\ No newline at end of file

From b3c7e5dad5f35e317ab732d7d787eaf154f37c56 Mon Sep 17 00:00:00 2001
From: zhyass <mytesla@live.com>
Date: Thu, 2 Apr 2026 22:05:16 +0800
Subject: [PATCH 2/5] fix

---
 .../00-ddl/21-table-versioning/01-create-snapshot-tag.md      | 2 +-
 .../00-ddl/21-table-versioning/02-drop-snapshot-tag.md        | 2 +-
 .../10-sql-commands/20-query-syntax/03-query-at.md            | 4 ++--
 .../00-ddl/21-table-versioning/01-create-snapshot-tag.md      | 2 +-
 .../00-ddl/21-table-versioning/02-drop-snapshot-tag.md        | 2 +-
 .../10-sql-commands/20-query-syntax/03-query-at.md            | 4 ++--
 6 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/docs/cn/sql-reference/10-sql-commands/00-ddl/21-table-versioning/01-create-snapshot-tag.md b/docs/cn/sql-reference/10-sql-commands/00-ddl/21-table-versioning/01-create-snapshot-tag.md
index a324a9868e..bd352bbaea 100644
--- a/docs/cn/sql-reference/10-sql-commands/00-ddl/21-table-versioning/01-create-snapshot-tag.md
+++ b/docs/cn/sql-reference/10-sql-commands/00-ddl/21-table-versioning/01-create-snapshot-tag.md
@@ -57,7 +57,7 @@ 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;
+SELECT * FROM t1 AT (TAG => v1_0) ORDER BY a;
 ```
 
 ### 从已有引用创建标签
diff --git a/docs/cn/sql-reference/10-sql-commands/00-ddl/21-table-versioning/02-drop-snapshot-tag.md b/docs/cn/sql-reference/10-sql-commands/00-ddl/21-table-versioning/02-drop-snapshot-tag.md
index 257caee3d4..42f483a300 100644
--- a/docs/cn/sql-reference/10-sql-commands/00-ddl/21-table-versioning/02-drop-snapshot-tag.md
+++ b/docs/cn/sql-reference/10-sql-commands/00-ddl/21-table-versioning/02-drop-snapshot-tag.md
@@ -43,6 +43,6 @@ ALTER TABLE t1 CREATE TAG v1_0;
 ALTER TABLE t1 DROP TAG v1_0;
 
 -- 查询已删除的标签会返回错误
-SELECT * FROM t1 AT (TAG => "v1_0");
+SELECT * FROM t1 AT (TAG => v1_0);
 -- Error: tag 'v1_0' not found
 ```
diff --git a/docs/cn/sql-reference/10-sql-commands/20-query-syntax/03-query-at.md b/docs/cn/sql-reference/10-sql-commands/20-query-syntax/03-query-at.md
index a0cbcc0720..d3b16f2e87 100644
--- a/docs/cn/sql-reference/10-sql-commands/20-query-syntax/03-query-at.md
+++ b/docs/cn/sql-reference/10-sql-commands/20-query-syntax/03-query-at.md
@@ -22,7 +22,7 @@ AT (
        TIMESTAMP => <timestamp> |
        STREAM => <stream_name> |
        OFFSET => <time_interval> |
-       TAG => '<tag_name>'
+       TAG => <tag_name>
    )
 ```
 
@@ -109,7 +109,7 @@ ALTER TABLE t CREATE TAG v1_0;
 INSERT INTO t VALUES(4);
 
 -- 查询标签对应的快照（返回最后一次插入之前的数据）
-SELECT * FROM t AT (TAG => "v1_0") ORDER BY a;
+SELECT * FROM t AT (TAG => v1_0) ORDER BY a;
 
 ┌─────────────────┐
 │        a        │
diff --git a/docs/en/sql-reference/10-sql-commands/00-ddl/21-table-versioning/01-create-snapshot-tag.md b/docs/en/sql-reference/10-sql-commands/00-ddl/21-table-versioning/01-create-snapshot-tag.md
index d0d2925fd4..c36d112c71 100644
--- a/docs/en/sql-reference/10-sql-commands/00-ddl/21-table-versioning/01-create-snapshot-tag.md
+++ b/docs/en/sql-reference/10-sql-commands/00-ddl/21-table-versioning/01-create-snapshot-tag.md
@@ -57,7 +57,7 @@ ALTER TABLE t1 CREATE TAG v1_0;
 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;
+SELECT * FROM t1 AT (TAG => v1_0) ORDER BY a;
 ```
 
 ### Tag from an Existing Reference
diff --git a/docs/en/sql-reference/10-sql-commands/00-ddl/21-table-versioning/02-drop-snapshot-tag.md b/docs/en/sql-reference/10-sql-commands/00-ddl/21-table-versioning/02-drop-snapshot-tag.md
index 502b826ad5..a380b5f849 100644
--- a/docs/en/sql-reference/10-sql-commands/00-ddl/21-table-versioning/02-drop-snapshot-tag.md
+++ b/docs/en/sql-reference/10-sql-commands/00-ddl/21-table-versioning/02-drop-snapshot-tag.md
@@ -43,6 +43,6 @@ ALTER TABLE t1 CREATE TAG v1_0;
 ALTER TABLE t1 DROP TAG v1_0;
 
 -- Querying a dropped tag returns an error
-SELECT * FROM t1 AT (TAG => "v1_0");
+SELECT * FROM t1 AT (TAG => v1_0);
 -- Error: tag 'v1_0' not found
 ```
diff --git a/docs/en/sql-reference/10-sql-commands/20-query-syntax/03-query-at.md b/docs/en/sql-reference/10-sql-commands/20-query-syntax/03-query-at.md
index 30c0779226..765dffa044 100644
--- a/docs/en/sql-reference/10-sql-commands/20-query-syntax/03-query-at.md
+++ b/docs/en/sql-reference/10-sql-commands/20-query-syntax/03-query-at.md
@@ -21,7 +21,7 @@ AT (
        TIMESTAMP => <timestamp> | 
        STREAM => <stream_name> |
        OFFSET => <time_interval> |
-       TAG => '<tag_name>'
+       TAG => <tag_name>
    )
 ```
 
@@ -108,7 +108,7 @@ ALTER TABLE t CREATE TAG v1_0;
 INSERT INTO t VALUES(4);
 
 -- Query the tagged snapshot (returns data before the last insert)
-SELECT * FROM t AT (TAG => "v1_0") ORDER BY a;
+SELECT * FROM t AT (TAG => v1_0) ORDER BY a;
 
 ┌─────────────────┐
 │        a        │

From ae94cdb673b9c70547ebd520838437b02bf06f58 Mon Sep 17 00:00:00 2001
From: zhyass <mytesla@live.com>
Date: Thu, 2 Apr 2026 22:18:48 +0800
Subject: [PATCH 3/5] 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>
---
 .../00-ddl/01-table/90-alter-table.md         | 33 ++++++++-----------
 .../00-ddl/01-table/90-alter-table.md         | 24 ++++++++------
 2 files changed, 28 insertions(+), 29 deletions(-)

diff --git a/docs/cn/sql-reference/10-sql-commands/00-ddl/01-table/90-alter-table.md b/docs/cn/sql-reference/10-sql-commands/00-ddl/01-table/90-alter-table.md
index eea4e6e516..ad0ac9dd3b 100644
--- a/docs/cn/sql-reference/10-sql-commands/00-ddl/01-table/90-alter-table.md
+++ b/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}
 
 在同一个事务中交换两张表的所有元数据和数据，使双方的列、约束以及数据完全互换。
@@ -296,25 +310,6 @@ DESC t1;
 DESC t2;
 ```
 
-## 快照标签操作 {#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)
-
-### 快照标签 vs. 治理标签 {#snapshot-tags-vs-governance-tags}
-
-| | 快照标签 | 治理标签 |
-|---|---|---|
-| 用途 | 为表快照创建书签，用于时间回溯 | 附加键值元数据，用于分类 |
-| 语法 | `ALTER TABLE ... CREATE TAG <name>` | `ALTER TABLE ... SET TAG <key> = '<value>'` |
-| 查询 | `SELECT ... AT (TAG => "<name>")` | `SELECT * FROM TAG_REFERENCES(...)` |
-| 范围 | 仅限表，引用快照 | 任何对象（表、数据库、视图等） |
-
 ## Tag 操作 {#tag-operations}
 
 为表分配或移除治理标签。治理标签是用于分类和数据治理的键值元数据。Tag 必须先通过 [CREATE TAG](../08-tag/01-ddl-create-tag.md) 创建。完整说明请参阅 [SET TAG / UNSET TAG](../08-tag/04-ddl-set-tag.md)。
diff --git a/docs/en/sql-reference/10-sql-commands/00-ddl/01-table/90-alter-table.md b/docs/en/sql-reference/10-sql-commands/00-ddl/01-table/90-alter-table.md
index 80e558c357..355d7d8b66 100644
--- a/docs/en/sql-reference/10-sql-commands/00-ddl/01-table/90-alter-table.md
+++ b/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.
@@ -402,16 +416,6 @@ DESC t1;
 DESC t2;
 ```
 
-## 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)
-
 ## Tag Operations {#tag-operations}
 
 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).

From 030547603920b2ab5f06c71e0ac7ba46d5114a4a Mon Sep 17 00:00:00 2001
From: zhyass <mytesla@live.com>
Date: Thu, 2 Apr 2026 22:42:31 +0800
Subject: [PATCH 4/5] fix

---
 .../index.md => 01-data-lifecycle.md}         |  2 +-
 .../01-data-lifecycle/05-table-versioning.md  | 36 -------------------
 docs/cn/guides/57-data-management/index.md    |  2 +-
 .../01-create-snapshot-tag.md                 |  4 +--
 .../00-ddl/21-table-versioning/index.md       | 17 ++++++++-
 .../index.md => 01-data-lifecycle.md}         |  2 +-
 .../01-data-lifecycle/05-table-versioning.md  | 36 -------------------
 docs/en/guides/57-data-management/index.md    |  2 +-
 .../01-create-snapshot-tag.md                 |  4 +--
 .../00-ddl/21-table-versioning/index.md       | 17 ++++++++-
 10 files changed, 40 insertions(+), 82 deletions(-)
 rename docs/cn/guides/57-data-management/{01-data-lifecycle/index.md => 01-data-lifecycle.md} (97%)
 delete mode 100644 docs/cn/guides/57-data-management/01-data-lifecycle/05-table-versioning.md
 rename docs/en/guides/57-data-management/{01-data-lifecycle/index.md => 01-data-lifecycle.md} (97%)
 delete mode 100644 docs/en/guides/57-data-management/01-data-lifecycle/05-table-versioning.md

diff --git a/docs/cn/guides/57-data-management/01-data-lifecycle/index.md b/docs/cn/guides/57-data-management/01-data-lifecycle.md
similarity index 97%
rename from docs/cn/guides/57-data-management/01-data-lifecycle/index.md
rename to docs/cn/guides/57-data-management/01-data-lifecycle.md
index abe589bc7b..19fdda9d74 100644
--- a/docs/cn/guides/57-data-management/01-data-lifecycle/index.md
+++ b/docs/cn/guides/57-data-management/01-data-lifecycle.md
@@ -25,7 +25,7 @@ Databend 支持创建和修改以下对象：
 - 授权
 - 计算集群
 - 任务
-- 快照标签
+- [快照标签](/sql/sql-commands/ddl/table-versioning#snapshot-tags)
 
 ## 组织数据
 
diff --git a/docs/cn/guides/57-data-management/01-data-lifecycle/05-table-versioning.md b/docs/cn/guides/57-data-management/01-data-lifecycle/05-table-versioning.md
deleted file mode 100644
index e9ea01e1aa..0000000000
--- a/docs/cn/guides/57-data-management/01-data-lifecycle/05-table-versioning.md
+++ /dev/null
@@ -1,36 +0,0 @@
----
-title: 表版本管理
-sidebar_label: 表版本管理
----
-
-import EEFeature from '@site/src/components/EEFeature';
-
-<EEFeature featureName='TABLE VERSIONING'/>
-
-表版本管理允许您为 FUSE 表的特定快照创建命名引用。这些引用不受自动保留清理的影响，为您提供稳定、可读的历史表状态指针。
-
-:::note
-这是一个实验性功能，使用前需要启用：`SET enable_experimental_table_ref = 1;`
-:::
-
-## 快照标签
-
-快照标签通过名称固定表的某个时间点状态。创建后，标签会持有对特定快照的引用，您可以随时查询该状态，无需记录快照 ID 或时间戳。
-
-**使用场景：**
-- **发布检查点**：在数据管道运行前后标记表状态，便于比较或回滚。
-- **审计与合规**：保留命名快照用于监管审查，无需担心保留期过期。
-- **安全实验**：标记当前状态，运行实验性转换，然后查询标签验证变更。
-- **可复现分析**：固定数据集版本，确保仪表板和报告始终引用相同数据。
-
-**工作原理：**
-
-快照标签为快照附加一个可读的名称。只要标签存在，被引用的快照就会受到保护，不会被 vacuum 和垃圾回收清理 — 即使保留期已过。
-
-- 不带 `RETAIN` 的标签会一直存在，直到显式删除。
-- 带 `RETAIN <n> DAYS | SECONDS` 的标签会在指定时间后，在下次 vacuum 操作时自动移除。
-
-**SQL 命令：**
-- [CREATE SNAPSHOT TAG](/sql/sql-commands/ddl/table-versioning/create-snapshot-tag) — 在表快照上创建命名标签。
-- [DROP SNAPSHOT TAG](/sql/sql-commands/ddl/table-versioning/drop-snapshot-tag) — 删除快照标签。
-- [AT (TAG => ...)](/sql/sql-commands/query-syntax/query-at) — 查询标签对应的快照数据。
diff --git a/docs/cn/guides/57-data-management/index.md b/docs/cn/guides/57-data-management/index.md
index e69cf1ffeb..c7118a454f 100644
--- a/docs/cn/guides/57-data-management/index.md
+++ b/docs/cn/guides/57-data-management/index.md
@@ -6,7 +6,7 @@ title: 数据管理
 
 | 类别 | 描述 | 主要功能 | 常用操作 |
 |----------|-------------|--------------|------------------|
-| **[数据生命周期](./01-data-lifecycle/index.md)** | 创建和管理对象 | • 数据库和表 <br/>• 外部表<br/>• Stream 和视图<br/>• 索引和 Stage<br/>• 表版本管理 | • CREATE/DROP/ALTER<br/>• SHOW TABLES<br/>• DESCRIBE TABLE |
+| **[数据生命周期](./01-data-lifecycle.md)** | 创建和管理对象 | • 数据库和表 <br/>• 外部表<br/>• Stream 和视图<br/>• 索引和 Stage | • CREATE/DROP/ALTER<br/>• SHOW TABLES<br/>• DESCRIBE TABLE |
 | **[数据恢复](./02-data-recovery.md)** | 访问和恢复历史数据 | • 时间回溯<br/>• 闪回表<br/>• 备份和恢复<br/>• AT 和 UNDROP | • SELECT ... AT<br/>• FLASHBACK TABLE<br/>• BENDSAVE BACKUP |
 | **[数据保护](./03-data-protection.md)** | 安全访问和防止数据丢失 | • 网络策略<br/>• 访问控制<br/>• 时间回溯和故障安全<br/>• 数据加密 | • NETWORK POLICY<br/>• GRANT/REVOKE<br/>• USER/ROLE |
 | **[数据回收](./04-data-recycle.md)** | 释放存储空间 | • VACUUM 命令<br/>• 保留策略<br/>• 孤立文件清理<br/>• 临时文件管理 | • VACUUM TABLE<br/>• VACUUM DROP TABLE<br/>• DATA_RETENTION_TIME |
\ No newline at end of file
diff --git a/docs/cn/sql-reference/10-sql-commands/00-ddl/21-table-versioning/01-create-snapshot-tag.md b/docs/cn/sql-reference/10-sql-commands/00-ddl/21-table-versioning/01-create-snapshot-tag.md
index bd352bbaea..4ee593f87c 100644
--- a/docs/cn/sql-reference/10-sql-commands/00-ddl/21-table-versioning/01-create-snapshot-tag.md
+++ b/docs/cn/sql-reference/10-sql-commands/00-ddl/21-table-versioning/01-create-snapshot-tag.md
@@ -27,9 +27,9 @@ ALTER TABLE [<database_name>.]<table_name> CREATE TAG <tag_name>
         TIMESTAMP => <timestamp> |
         STREAM => <stream_name> |
         OFFSET => <time_interval> |
-        TAG => <existing_tag_name>
+        TAG => <tag_name>
     ) ]
-    [ RETAIN <n> DAYS | SECONDS ]
+    [ RETAIN <n> { DAYS | SECONDS } ]
 ```
 
 ## 参数
diff --git a/docs/cn/sql-reference/10-sql-commands/00-ddl/21-table-versioning/index.md b/docs/cn/sql-reference/10-sql-commands/00-ddl/21-table-versioning/index.md
index ee24087afe..41dfdb4693 100644
--- a/docs/cn/sql-reference/10-sql-commands/00-ddl/21-table-versioning/index.md
+++ b/docs/cn/sql-reference/10-sql-commands/00-ddl/21-table-versioning/index.md
@@ -18,7 +18,22 @@ SET enable_experimental_table_ref = 1;
 
 ## 快照标签
 
-快照标签通过名称固定表的某个时间点状态。您可以随时通过 [AT](../../20-query-syntax/03-query-at.md) 子句查询标签对应的状态，无需记录快照 ID 或时间戳。
+快照标签通过名称固定表的某个时间点状态。创建后，标签会持有对特定快照的引用，您可以随时通过 [AT](../../20-query-syntax/03-query-at.md) 子句查询该状态，无需记录快照 ID 或时间戳。
+
+**使用场景：**
+- **发布检查点**：在数据管道运行前后标记表状态，便于比较或回滚。
+- **审计与合规**：保留命名快照用于监管审查，无需担心保留期过期。
+- **安全实验**：标记当前状态，运行实验性转换，然后查询标签验证变更。
+- **可复现分析**：固定数据集版本，确保仪表板和报告始终引用相同数据。
+
+**工作原理：**
+
+快照标签为快照附加一个可读的名称。只要标签存在，被引用的快照就会受到保护，不会被 vacuum 和垃圾回收清理 — 即使保留期已过。
+
+- 不带 `RETAIN` 的标签会一直存在，直到显式删除。
+- 带 `RETAIN <n> { DAYS | SECONDS }` 的标签会在指定时间后，在下次 vacuum 操作时自动移除。
+
+**SQL 命令：**
 
 | 命令 | 说明 |
 |------|------|
diff --git a/docs/en/guides/57-data-management/01-data-lifecycle/index.md b/docs/en/guides/57-data-management/01-data-lifecycle.md
similarity index 97%
rename from docs/en/guides/57-data-management/01-data-lifecycle/index.md
rename to docs/en/guides/57-data-management/01-data-lifecycle.md
index 924b2b70d2..8cbbf02b18 100644
--- a/docs/en/guides/57-data-management/01-data-lifecycle/index.md
+++ b/docs/en/guides/57-data-management/01-data-lifecycle.md
@@ -25,7 +25,7 @@ Databend supports the following objects to create and modify them:
 - Grants
 - Warehouse
 - Task
-- Tag
+- [Snapshot Tag](/sql/sql-commands/ddl/table-versioning#snapshot-tags)
 
 ## Organizing Data
 
diff --git a/docs/en/guides/57-data-management/01-data-lifecycle/05-table-versioning.md b/docs/en/guides/57-data-management/01-data-lifecycle/05-table-versioning.md
deleted file mode 100644
index c3e2571803..0000000000
--- a/docs/en/guides/57-data-management/01-data-lifecycle/05-table-versioning.md
+++ /dev/null
@@ -1,36 +0,0 @@
----
-title: Table Versioning
-sidebar_label: Table Versioning
----
-
-import EEFeature from '@site/src/components/EEFeature';
-
-<EEFeature featureName='TABLE VERSIONING'/>
-
-Table versioning lets you create named references to specific snapshots of a FUSE table. These references survive automatic retention cleanup, giving you stable, human-readable pointers to historical table states.
-
-:::note
-This is an experimental feature. Enable it before use: `SET enable_experimental_table_ref = 1;`
-:::
-
-## Snapshot Tags
-
-Snapshot tags pin a specific point-in-time state of a table by name. Once created, a tag holds a reference to a particular snapshot so you can query that exact state at any time, without needing to track snapshot IDs or timestamps.
-
-**Use cases:**
-- **Release checkpoints**: Tag the table state before and after a data pipeline run so you can compare or roll back.
-- **Audit and compliance**: Preserve a named snapshot for regulatory review without worrying about retention expiry.
-- **Safe experimentation**: Tag the current state, run experimental transforms, then query the tag to verify what changed.
-- **Reproducible analytics**: Pin a dataset version so dashboards and reports always reference the same data.
-
-**How it works:**
-
-A snapshot tag attaches a human-readable name to a snapshot. As long as the tag exists, the referenced snapshot is protected from vacuum and garbage collection — even if the retention period has passed.
-
-- A tag without `RETAIN` lives until explicitly dropped.
-- A tag with `RETAIN <n> DAYS | SECONDS` is automatically removed after the specified duration during the next vacuum operation.
-
-**SQL Commands:**
-- [CREATE SNAPSHOT TAG](/sql/sql-commands/ddl/table-versioning/create-snapshot-tag) — Create a named tag on a table snapshot.
-- [DROP SNAPSHOT TAG](/sql/sql-commands/ddl/table-versioning/drop-snapshot-tag) — Remove a snapshot tag.
-- [AT (TAG => ...)](/sql/sql-commands/query-syntax/query-at) — Query data at a tagged snapshot.
diff --git a/docs/en/guides/57-data-management/index.md b/docs/en/guides/57-data-management/index.md
index df878e7f60..7b0d5e4167 100644
--- a/docs/en/guides/57-data-management/index.md
+++ b/docs/en/guides/57-data-management/index.md
@@ -6,7 +6,7 @@ title: Data Management
 
 | Category | Description | Key Features | Common Operations |
 |----------|-------------|--------------|------------------|
-| **[Data Lifecycle](./01-data-lifecycle/index.md)** | Create and manage objects | • Database & Table <br/>• External Tables<br/>• Streams & Views<br/>• Indexes & Stages<br/>• Table Versioning | • CREATE/DROP/ALTER<br/>• SHOW TABLES<br/>• DESCRIBE TABLE |
+| **[Data Lifecycle](./01-data-lifecycle.md)** | Create and manage objects | • Database & Table <br/>• External Tables<br/>• Streams & Views<br/>• Indexes & Stages | • CREATE/DROP/ALTER<br/>• SHOW TABLES<br/>• DESCRIBE TABLE |
 | **[Data Recovery](./02-data-recovery.md)** | Access and restore past data | • Time Travel<br/>• Flashback Tables<br/>• Backup & Restore<br/>• AT & UNDROP | • SELECT ... AT<br/>• FLASHBACK TABLE<br/>• BENDSAVE BACKUP |
 | **[Data Protection](./03-data-protection.md)** | Secure access and prevent loss | • Network Policies<br/>• Access Control<br/>• Time Travel & Fail-safe<br/>• Data Encryption | • NETWORK POLICY<br/>• GRANT/REVOKE<br/>• USER/ROLE |
 | **[Data Recycle](./04-data-recycle.md)** | Free up storage space | • VACUUM Commands<br/>• Retention Policies<br/>• Orphan File Cleanup<br/>• Temporary File Management | • VACUUM TABLE<br/>• VACUUM DROP TABLE<br/>• DATA_RETENTION_TIME |
diff --git a/docs/en/sql-reference/10-sql-commands/00-ddl/21-table-versioning/01-create-snapshot-tag.md b/docs/en/sql-reference/10-sql-commands/00-ddl/21-table-versioning/01-create-snapshot-tag.md
index c36d112c71..760a13b1f9 100644
--- a/docs/en/sql-reference/10-sql-commands/00-ddl/21-table-versioning/01-create-snapshot-tag.md
+++ b/docs/en/sql-reference/10-sql-commands/00-ddl/21-table-versioning/01-create-snapshot-tag.md
@@ -27,9 +27,9 @@ ALTER TABLE [<database_name>.]<table_name> CREATE TAG <tag_name>
         TIMESTAMP => <timestamp> |
         STREAM => <stream_name> |
         OFFSET => <time_interval> |
-        TAG => <existing_tag_name>
+        TAG => <tag_name>
     ) ]
-    [ RETAIN <n> DAYS | SECONDS ]
+    [ RETAIN <n> { DAYS | SECONDS } ]
 ```
 
 ## Parameters
diff --git a/docs/en/sql-reference/10-sql-commands/00-ddl/21-table-versioning/index.md b/docs/en/sql-reference/10-sql-commands/00-ddl/21-table-versioning/index.md
index 471c818206..e6a69a9ed1 100644
--- a/docs/en/sql-reference/10-sql-commands/00-ddl/21-table-versioning/index.md
+++ b/docs/en/sql-reference/10-sql-commands/00-ddl/21-table-versioning/index.md
@@ -18,7 +18,22 @@ SET enable_experimental_table_ref = 1;
 
 ## Snapshot Tags
 
-A snapshot tag pins a specific point-in-time state of a table by name. You can query the tagged state at any time using the [AT](../../20-query-syntax/03-query-at.md) clause, without needing to track snapshot IDs or timestamps.
+Snapshot tags pin a specific point-in-time state of a table by name. Once created, a tag holds a reference to a particular snapshot so you can query that exact state at any time using the [AT](../../20-query-syntax/03-query-at.md) clause, without needing to track snapshot IDs or timestamps.
+
+**Use cases:**
+- **Release checkpoints**: Tag the table state before and after a data pipeline run so you can compare or roll back.
+- **Audit and compliance**: Preserve a named snapshot for regulatory review without worrying about retention expiry.
+- **Safe experimentation**: Tag the current state, run experimental transforms, then query the tag to verify what changed.
+- **Reproducible analytics**: Pin a dataset version so dashboards and reports always reference the same data.
+
+**How it works:**
+
+A snapshot tag attaches a human-readable name to a snapshot. As long as the tag exists, the referenced snapshot is protected from vacuum and garbage collection — even if the retention period has passed.
+
+- A tag without `RETAIN` lives until explicitly dropped.
+- A tag with `RETAIN <n> { DAYS | SECONDS }` is automatically removed after the specified duration during the next vacuum operation.
+
+**SQL Commands:**
 
 | Command | Description |
 |---------|-------------|

From 57a46a3f897d7bafd1451e740e7df9d3e4903f47 Mon Sep 17 00:00:00 2001
From: zhyass <mytesla@live.com>
Date: Thu, 2 Apr 2026 23:14:53 +0800
Subject: [PATCH 5/5] docs: add explicit anchor IDs for snapshot-tags headings

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 .../10-sql-commands/00-ddl/21-table-versioning/index.md         | 2 +-
 .../10-sql-commands/00-ddl/21-table-versioning/index.md         | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/cn/sql-reference/10-sql-commands/00-ddl/21-table-versioning/index.md b/docs/cn/sql-reference/10-sql-commands/00-ddl/21-table-versioning/index.md
index 41dfdb4693..47517918bf 100644
--- a/docs/cn/sql-reference/10-sql-commands/00-ddl/21-table-versioning/index.md
+++ b/docs/cn/sql-reference/10-sql-commands/00-ddl/21-table-versioning/index.md
@@ -16,7 +16,7 @@ SET enable_experimental_table_ref = 1;
 ```
 :::
 
-## 快照标签
+## 快照标签 {#snapshot-tags}
 
 快照标签通过名称固定表的某个时间点状态。创建后，标签会持有对特定快照的引用，您可以随时通过 [AT](../../20-query-syntax/03-query-at.md) 子句查询该状态，无需记录快照 ID 或时间戳。
 
diff --git a/docs/en/sql-reference/10-sql-commands/00-ddl/21-table-versioning/index.md b/docs/en/sql-reference/10-sql-commands/00-ddl/21-table-versioning/index.md
index e6a69a9ed1..5fbfea7409 100644
--- a/docs/en/sql-reference/10-sql-commands/00-ddl/21-table-versioning/index.md
+++ b/docs/en/sql-reference/10-sql-commands/00-ddl/21-table-versioning/index.md
@@ -16,7 +16,7 @@ SET enable_experimental_table_ref = 1;
 ```
 :::
 
-## Snapshot Tags
+## Snapshot Tags {#snapshot-tags}
 
 Snapshot tags pin a specific point-in-time state of a table by name. Once created, a tag holds a reference to a particular snapshot so you can query that exact state at any time using the [AT](../../20-query-syntax/03-query-at.md) clause, without needing to track snapshot IDs or timestamps.