@clickzetta/cz-cli-darwin-x64 0.3.18 → 0.3.20

package/bin/skills/clickzetta-ai-vector-search/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: clickzetta-ai-vector-search
+description: |
+  在 ClickZetta Lakehouse 中实现向量存储、向量索引（HNSW）和向量检索，
+  构建 RAG、语义搜索、图像检索等 AI 应用。覆盖 VECTOR 数据类型定义、
+  向量索引创建（cosine/l2/hamming 距离）、向量数据插入与转换、
+  ANN 近似最近邻检索、向量+倒排索引融合检索等完整工作流。
+  当用户说"向量检索"、"向量索引"、"语义搜索"、"embedding 存储"、
+  "RAG"、"ANN 搜索"、"HNSW"、"cosine_distance"、"l2_distance"、
+  "VECTOR 类型"、"向量数据库"、"相似度搜索"、"向量 + 标量融合检索"、
+  "文本向量化"时触发。
+  Keywords: vector, HNSW, embedding, RAG, semantic search, similarity, VECTOR type
+---
+
+# ClickZetta 向量检索
+
+Lakehouse 原生支持 VECTOR 数据类型和 HNSW 向量索引，无需独立向量数据库即可在同一张表中实现向量检索、全文检索和标量过滤的融合查询。
+
+阅读 [references/vector-search.md](references/vector-search.md) 了解完整语法。
+
+---
+
+## 快速开始
+
+### 1. 建表（含向量索引）
+
+```sql
+CREATE TABLE doc_embeddings (
+    id      INT,
+    content STRING,
+    vec     VECTOR(FLOAT, 1024),
+    INDEX vec_idx (vec) USING VECTOR PROPERTIES (
+        "distance.function" = "cosine_distance",
+        "scalar.type"       = "f32"
+    )
+);
+```
+
+### 2. 插入向量数据
+
+```sql
+-- 直接插入
+INSERT INTO doc_embeddings VALUES
+    (1, '云器 Lakehouse 产品介绍', vector(0.12, 0.34, ...));
+
+-- 从字符串转换（适合 API 返回的 JSON 格式）
+INSERT INTO doc_embeddings (id, content, vec)
+SELECT id, content, CAST(embedding_str AS VECTOR(1024))
+FROM staging_table;
+```
+
+### 3. 向量检索
+
+```sql
+-- 设置探索因子（精度 vs 速度）
+SET cz.vector.index.search.ef = 64;
+
+-- 余弦距离 Top-10 相似文档
+SELECT id, content, cosine_distance(vec, CAST('[0.12, 0.34, ...]' AS VECTOR(1024))) AS dist
+FROM doc_embeddings
+ORDER BY dist
+LIMIT 10;
+```
+
+---
+
+## 向量 + 标量融合检索（RAG 场景）
+
+```sql
+-- 先用标量过滤缩小范围，再用向量排序
+SELECT id, content, cosine_distance(vec, :query_embedding) AS dist
+FROM doc_embeddings
+WHERE category = 'product'
+  AND created_at >= '2024-01-01'
+ORDER BY dist
+LIMIT 5;
+```
+
+---
+
+## 向量 + 全文检索融合
+
+```sql
+-- 建表：同时支持向量索引和倒排索引
+CREATE TABLE hybrid_docs (
+    id      INT,
+    title   STRING,
+    body    STRING,
+    vec     VECTOR(FLOAT, 1024),
+    INDEX body_inv_idx (body) USING INVERTED,
+    INDEX vec_idx (vec) USING VECTOR PROPERTIES (
+        "distance.function" = "cosine_distance"
+    )
+);
+
+-- 融合检索：关键词过滤 + 向量排序
+SELECT id, title, cosine_distance(vec, :query_vec) AS dist
+FROM hybrid_docs
+WHERE body LIKE '%向量检索%'
+ORDER BY dist
+LIMIT 10;
+```
+
+---
+
+## 外部系统写入向量（ARRAY → VECTOR 转换）
+
+外部系统（Python SDK、Kafka 等）不能直接写 VECTOR 类型，需先写 ARRAY 再转换：
+
+```sql
+-- 暂存表（ARRAY 类型）
+CREATE TABLE staging (id INT, vec_array ARRAY<FLOAT>);
+
+-- 转换写入目标表
+INSERT INTO doc_embeddings (id, vec)
+SELECT id, CAST(vec_array AS VECTOR(FLOAT, 1024))
+FROM staging;
+```
+
+---
+
+## 距离函数速查
+
+| 函数 | 适用场景 |
+|---|---|
+| `cosine_distance(v1, v2)` | 文本语义检索（最常用） |
+| `l2_distance(v1, v2)` | 图像/通用向量检索 |
+| `dot_product(v1, v2)` | 归一化向量的相似度 |
+| `hamming_distance(v1, v2)` | 二值向量（高效压缩） |
+| `binary_quantize(v)` | 将 float 向量压缩为二值向量 |
+
+---
+
+## 性能调优
+
+```sql
+-- 调整探索因子（默认 64，越大精度越高但越慢）
+SET cz.vector.index.search.ef = 128;
+
+-- 验证向量索引是否生效
+EXPLAIN SELECT id, cosine_distance(vec, vector(0.1, 0.2)) AS dist
+FROM doc_embeddings ORDER BY dist LIMIT 10;
+-- 查看执行计划中是否有 vector_index_search_type 字样
+```
+
+**最佳实践：**
+- 向量检索建议**单独占用 VCluster**，避免与其他查询争抢缓存
+- 大批量写入后执行 `BUILD INDEX vec_idx ON table_name` 为存量数据构建索引
+- 外部系统写入时先写 ARRAY，再批量 CAST 转换，避免频繁小文件
+
+---
+
+## 常见问题
+
+| 问题 | 原因 | 解决方案 |
+|---|---|---|
+| 向量索引未生效 | 存量数据未构建索引 | 执行 `BUILD INDEX idx ON table` |
+| 检索精度低 | ef 值太小 | 增大 `cz.vector.index.search.ef` |
+| 外部写入报错 | 不支持直接写 VECTOR | 先写 ARRAY，再 CAST 转换 |
+| 向量检索慢 | 与其他查询共用 VCluster | 为向量检索单独分配 VCluster |

package/bin/skills/clickzetta-ai-vector-search/eval_cases.jsonl

@@ -0,0 +1,4 @@
+{"case_id":"001","type":"should_call","user_input":"怎么在 ClickZetta 里创建 VECTOR 类型的列存储 embedding？","expected_skill":"clickzetta-ai-vector-search","expected_output_contains":["VECTOR","FLOAT"]}
+{"case_id":"002","type":"should_call","user_input":"HNSW 向量索引怎么创建？支持哪些距离函数？","expected_skill":"clickzetta-ai-vector-search","expected_output_contains":["HNSW","cosine"]}
+{"case_id":"003","type":"should_call","user_input":"怎么做 ANN 近似最近邻检索？SQL 怎么写？","expected_skill":"clickzetta-ai-vector-search","expected_output_contains":["ANN","distance"]}
+{"case_id":"004","type":"should_call","user_input":"向量检索和倒排索引能融合查询吗？怎么写？","expected_skill":"clickzetta-ai-vector-search","expected_output_contains":["向量","检索"]}

package/bin/skills/clickzetta-ai-vector-search/references/vector-search.md

@@ -0,0 +1,155 @@
+# 向量检索参考
+
+> 来源：https://www.yunqi.tech/documents/vector-search 等
+
+## VECTOR 数据类型
+
+```sql
+-- 语法
+vector(scalar_type, dimension)
+vector(dimension)  -- 默认 float 类型
+
+-- 示例
+CREATE TABLE embeddings (
+    id       INT,
+    content  STRING,
+    vec      VECTOR(FLOAT, 1024),   -- 1024 维 float 向量
+    vec_bin  VECTOR(TINYINT, 128)   -- 128 维 tinyint 向量（二值化）
+);
+```
+
+支持的元素类型：`FLOAT`（f32）、`TINYINT`（i8/b1）
+
+---
+
+## 创建向量索引
+
+```sql
+-- 建表时内联创建
+CREATE TABLE doc_embeddings (
+    id      INT,
+    content STRING,
+    vec     VECTOR(FLOAT, 1024),
+    INDEX vec_idx (vec) USING VECTOR PROPERTIES (
+        "distance.function" = "cosine_distance",
+        "scalar.type"       = "f32",
+        "m"                 = "16",
+        "ef.construction"   = "128"
+    )
+);
+
+-- 在已有表上添加向量索引
+ALTER TABLE doc_embeddings ADD INDEX vec_idx (vec) USING VECTOR PROPERTIES (
+    "distance.function" = "cosine_distance",
+    "scalar.type"       = "f32"
+);
+
+-- 为存量数据构建索引
+BUILD INDEX vec_idx ON doc_embeddings;
+```
+
+### 关键参数
+
+| 参数 | 可选值 | 默认值 | 说明 |
+|---|---|---|---|
+| distance.function | l2_distance, cosine_distance, jaccard_distance, hamming_distance | cosine_distance | 距离函数 |
+| scalar.type | f32, f16, i8, b1 | f32 | 索引元素类型 |
+| m | 建议 ≤ 1000 | 16 | HNSW 最大邻居数 |
+| ef.construction | 建议 ≤ 5000 | 128 | 构建时候选集大小 |
+| compress.codec | uncompressed/zstd/lz4 | uncompressed | 压缩算法 |
+
+---
+
+## 插入向量数据
+
+```sql
+-- 直接插入
+INSERT INTO doc_embeddings (id, content, vec) VALUES
+    (1, 'hello world', vector(0.1, 0.2, 0.3, ...)),
+    (2, 'foo bar',     vector(0.4, 0.5, 0.6, ...));
+
+-- 从字符串转换
+INSERT INTO doc_embeddings (id, vec)
+SELECT id, CAST('[0.1, 0.2, 0.3]' AS VECTOR(3))
+FROM source_table;
+
+-- 从 ARRAY 列转换（外部系统写入场景）
+INSERT OVERWRITE doc_embeddings
+SELECT id, content, CAST(vec_array AS VECTOR(FLOAT, 1024))
+FROM staging_table;
+```
+
+---
+
+## 向量检索
+
+```sql
+-- 调整探索因子（精度 vs 速度权衡）
+SET cz.vector.index.search.ef = 64;
+
+-- L2 距离检索（欧几里得距离，越小越相似）
+SELECT id, content, l2_distance(vec, vector(0.1, 0.2, 0.3, ...)) AS dist
+FROM doc_embeddings
+ORDER BY dist
+LIMIT 10;
+
+-- 余弦距离检索（越小越相似）
+SELECT id, content, cosine_distance(vec, CAST('[0.1,0.2,0.3]' AS VECTOR(3))) AS dist
+FROM doc_embeddings
+ORDER BY dist
+LIMIT 10;
+
+-- 带过滤条件的向量检索（向量 + 标量融合）
+SELECT id, content, cosine_distance(vec, :query_vec) AS dist
+FROM doc_embeddings
+WHERE category = 'tech'
+  AND cosine_distance(vec, :query_vec) < 0.3
+ORDER BY dist
+LIMIT 10;
+```
+
+---
+
+## 距离函数速查
+
+| 函数 | 适用场景 | 说明 |
+|---|---|---|
+| `l2_distance(v1, v2)` | 通用语义检索 | 欧几里得距离，越小越相似 |
+| `cosine_distance(v1, v2)` | 文本语义检索 | 余弦距离，越小越相似 |
+| `dot_product(v1, v2)` | 归一化向量 | 点积，越大越相似 |
+| `hamming_distance(v1, v2)` | 二值向量 | 汉明距离，越小越相似 |
+| `jaccard_distance(v1, v2)` | 集合相似度 | 雅卡德距离 |
+| `binary_quantize(v)` | 向量压缩 | 将 float 向量二值化 |
+
+---
+
+## 向量 + 倒排索引融合检索
+
+```sql
+-- 建表：同时支持向量索引和倒排索引
+CREATE TABLE hybrid_search (
+    id      INT,
+    content STRING,
+    vec     VECTOR(FLOAT, 1024),
+    INDEX content_inv_idx (content) USING INVERTED,
+    INDEX vec_idx (vec) USING VECTOR PROPERTIES (
+        "distance.function" = "cosine_distance"
+    )
+);
+
+-- 融合检索：先用倒排过滤，再用向量排序
+SELECT id, content, cosine_distance(vec, :query_vec) AS dist
+FROM hybrid_search
+WHERE content LIKE '%关键词%'
+ORDER BY dist
+LIMIT 10;
+```
+
+---
+
+## 注意事项
+
+- 向量类型不支持 `ORDER BY` 或 `GROUP BY`（只能对距离函数结果排序）
+- 向量索引性能与内存/磁盘缓存直接相关，建议**单独占用 VCluster**
+- 外部系统写入时不能直接写 VECTOR 类型，需先写 ARRAY 再 CAST 转换
+- `ef` 值越大，检索精度越高但延迟越大；建议从 64 开始调优

package/bin/skills/clickzetta-data-retention/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: clickzetta-data-retention
+description: |
+  管理 ClickZetta Lakehouse 数据生命周期（TTL 自动回收）和数据恢复（Time Travel / UNDROP / RESTORE）。
+  覆盖数据生命周期设置（data_lifecycle）、Time Travel 保留周期（data_retention_days）、
+  历史数据查询（TIMESTAMP AS OF）、误删表恢复（UNDROP TABLE）、数据回滚（RESTORE TABLE）、
+  变更历史查看（DESC HISTORY）等完整数据管理工作流。
+  当用户说"设置生命周期"、"数据自动清理"、"TTL"、"data_lifecycle"、"表数据过期"、
+  "自动回收数据"、"设置数据保留"、"data_retention_days"、"Time Travel"、
+  "恢复误删的表"、"表被 DROP 了怎么办"、"回滚数据"、"查看历史版本"、
+  "UNDROP"、"RESTORE TABLE"、"误操作恢复"、"数据回滚"、"时间旅行"时触发。
+  Keywords: TTL, data retention, time travel, lifecycle, UNDROP, RESTORE, recovery, rollback
+---
+
+# ClickZetta 数据生命周期与恢复
+
+## 两个核心概念
+
+| 概念 | 属性键 | 作用 | 默认值 | 范围 |
+|---|---|---|---|---|
+| 数据生命周期（TTL） | `data_lifecycle` | 自动回收超期未更新的数据 | `-1`（永不回收） | 任意正整数天 |
+| Time Travel 保留周期 | `data_retention_days` | 历史版本保留时长，支持时间点查询和恢复 | `1`（1天） | 0-90 天 |
+
+两者独立，可同时设置。
+
+---
+
+## 数据生命周期（TTL）
+
+### 设置
+
+```sql
+-- 建表时设置（7天未更新自动清空数据）
+CREATE TABLE orders_archive (id BIGINT, amount DECIMAL(10,2))
+PROPERTIES('data_lifecycle'='7');
+
+-- 到期同时删除表结构
+CREATE TABLE temp_staging (id INT, data STRING)
+PROPERTIES('data_lifecycle'='30', 'data_lifecycle_delete_meta'='true');
+
+-- 修改现有表
+ALTER TABLE my_table SET PROPERTIES ('data_lifecycle'='90');
+
+-- 关闭生命周期
+ALTER TABLE my_table SET PROPERTIES ('data_lifecycle'='-1');
+```
+
+### 查看
+
+```sql
+-- 查看单表
+SHOW CREATE TABLE my_table;
+
+-- 批量查看已设置生命周期的表
+SELECT table_schema, table_name, data_lifecycle, last_modify_time
+FROM information_schema.tables
+WHERE data_lifecycle > 0
+ORDER BY data_lifecycle;
+```
+
+### 注意事项
+- 回收不立即执行，后台每 12 小时轮询，通常 24 小时内完成
+- 默认只清空数据不删表；加 `data_lifecycle_delete_meta='true'` 才删表
+- 分区表按分区独立计算 `last_modified_time`
+
+---
+
+## Time Travel 与数据恢复
+
+### 配置保留周期
+
+```sql
+-- 修改保留周期（默认 1 天，最长 90 天）
+ALTER TABLE my_table SET PROPERTIES ('data_retention_days'='7');
+
+-- 建表时指定
+CREATE TABLE orders (id INT, amount DECIMAL(10,2))
+PROPERTIES ('data_retention_days'='30');
+```
+
+### 查看变更历史
+
+```sql
+DESC HISTORY my_table;
+-- 返回：version, time, total_rows, total_bytes, user, operation, job_id
+
+-- 查看已删除表的记录
+SHOW TABLES HISTORY;
+SHOW TABLES HISTORY LIKE 'orders%';
+```
+
+### Time Travel 查询历史数据
+
+```sql
+-- 查询指定时间点（只读）
+SELECT * FROM orders TIMESTAMP AS OF '2026-03-18 15:00:00';
+
+-- 相对时间
+SELECT * FROM orders TIMESTAMP AS OF CURRENT_TIMESTAMP() - INTERVAL 12 HOURS;
+```
+
+### RESTORE TABLE 回滚
+
+```sql
+-- 将表回滚到指定时间点（覆盖当前数据）
+RESTORE TABLE orders TO TIMESTAMP AS OF '2026-03-18 14:59:00';
+```
+> 支持普通表和动态表，不支持物化视图。
+
+### UNDROP TABLE 恢复误删表
+
+```sql
+-- 恢复被 DROP 的表（需在保留周期内）
+UNDROP TABLE orders;
+```
+> 同名表存在时无法 UNDROP，需先 DROP 新表再 UNDROP。
+
+---
+
+## 典型场景
+
+### 误删表恢复
+```sql
+SHOW TABLES HISTORY LIKE 'orders';
+UNDROP TABLE orders;
+SELECT COUNT(*) FROM orders;
+```
+
+### 误执行 DELETE/UPDATE 回滚
+```sql
+DESC HISTORY analytics.events;
+-- 全量回滚
+RESTORE TABLE analytics.events TO TIMESTAMP AS OF '2026-03-18 14:55:00';
+-- 或仅补回部分数据
+INSERT INTO analytics.events
+SELECT * FROM analytics.events TIMESTAMP AS OF '2026-03-18 14:55:00'
+WHERE date < '2025-01-01';
+```
+
+### 日志表自动清理
+```sql
+CREATE TABLE app_logs (log_id BIGINT, message STRING, log_time TIMESTAMP)
+PROPERTIES('data_lifecycle'='30');
+```
+
+---
+
+## 决策树
+
+```
+数据丢失/损坏
+├── 表被 DROP？
+│   ├── 在保留周期内 → UNDROP TABLE
+│   └── 超出保留周期 → 联系管理员
+└── 数据被 DELETE/UPDATE/TRUNCATE？
+    ├── 在保留周期内
+    │   ├── 全量回滚 → RESTORE TABLE TO TIMESTAMP AS OF
+    │   └── 补回部分 → INSERT INTO ... SELECT ... TIMESTAMP AS OF
+    └── 超出保留周期 → 联系管理员
+```

package/bin/skills/clickzetta-data-retention/eval_cases.jsonl

@@ -0,0 +1,5 @@
+{"case_id":"001","type":"should_call","user_input":"怎么给表设置数据生命周期？超过 30 天自动清理","expected_skill":"clickzetta-data-retention","expected_output_contains":["data_lifecycle","PROPERTIES"]}
+{"case_id":"002","type":"should_call","user_input":"表被误删了怎么恢复？UNDROP 怎么用？","expected_skill":"clickzetta-data-retention","expected_output_contains":["UNDROP","TABLE"]}
+{"case_id":"003","type":"should_call","user_input":"怎么用 Time Travel 查询昨天的历史数据？","expected_skill":"clickzetta-data-retention","expected_output_contains":["TIMESTAMP AS OF"]}
+{"case_id":"004","type":"should_call","user_input":"误执行了 DELETE，怎么回滚到操作前的状态？","expected_skill":"clickzetta-data-retention","expected_output_contains":["RESTORE","TIMESTAMP"]}
+{"case_id":"005","type":"should_call","user_input":"data_retention_days 和 data_lifecycle 有什么区别？","expected_skill":"clickzetta-data-retention","expected_output_contains":["data_retention_days","data_lifecycle"]}

package/bin/skills/clickzetta-data-retention/references/lifecycle-reference.md

@@ -0,0 +1,175 @@
+# 数据生命周期管理参考
+
+> 来源：https://www.yunqi.tech/documents/data-lifecycle
+> 已通过实际 Lakehouse 连接验证（cn-shanghai-alicloud, f8866243, quick_start）
+
+---
+
+## 核心属性
+
+| 属性键 | 类型 | 默认值 | 说明 |
+|---|---|---|---|
+| `data_lifecycle` | 正整数 / -1 | `-1` | 数据自动回收周期（天）。-1 表示永不回收 |
+| `data_lifecycle_delete_meta` | boolean string | `'false'` | 到期时是否同时删除表结构。默认只清空数据 |
+| `data_retention_days` | 整数 0-90 | `1` | Time Travel 历史版本保留天数 |
+
+---
+
+## CREATE TABLE 语法
+
+```sql
+CREATE TABLE tname (
+    col1 datatype1,
+    col2 datatype2
+) PROPERTIES(
+    'data_lifecycle'='<天数>',
+    'data_lifecycle_delete_meta'='true',   -- 可选，到期删表结构
+    'data_retention_days'='<天数>'          -- 可选，Time Travel 保留周期
+);
+```
+
+**验证结果**：`SHOW CREATE TABLE` 输出中属性显示在 `TBLPROPERTIES` 块内：
+```sql
+CREATE TABLE quick_start.mcp_demo.lifecycle_test_table(
+  `id` int,
+  `name` string,
+  `created_at` timestamp)
+USING PARQUET
+TBLPROPERTIES(
+  'data_lifecycle'='7',
+  'data_retention_days'='7');
+```
+
+---
+
+## ALTER TABLE 语法
+
+```sql
+-- 设置/修改生命周期
+ALTER TABLE tname SET PROPERTIES ('data_lifecycle'='<天数>');
+
+-- 关闭生命周期
+ALTER TABLE tname SET PROPERTIES ('data_lifecycle'='-1');
+
+-- 设置到期删除表结构
+ALTER TABLE tname SET PROPERTIES ('data_lifecycle_delete_meta'='true');
+
+-- 设置 Time Travel 保留周期
+ALTER TABLE tname SET PROPERTIES ('data_retention_days'='<天数>');
+
+-- 同时设置多个属性
+ALTER TABLE tname SET PROPERTIES (
+    'data_lifecycle'='90',
+    'data_lifecycle_delete_meta'='true',
+    'data_retention_days'='30'
+);
+```
+
+---
+
+## 查看配置
+
+### DESC EXTENDED
+
+```sql
+DESC EXTENDED tname;
+```
+
+**实际输出结构**（验证结果）：
+
+| column_name | data_type | comment |
+|---|---|---|
+| id | int | |
+| name | string | |
+| ... | ... | |
+| # detailed table information | | |
+| workspace | quick_start | |
+| schema | mcp_demo | |
+| name | lifecycle_test_table | |
+| creator | qiliang | |
+| created_time | 2026-05-01 11:05:08.904 | |
+| last_modified_time | 2026-05-01 11:05:26.442 | |
+| comment | | |
+| properties | (("data_lifecycle","7"),("data_retention_days","7")) | |
+| version | 3377453148768716241 | |
+| type | TABLE | |
+| format | PARQUET | |
+| statistics | 1 rows 2445 bytes | |
+
+关键字段：
+- `last_modified_time`：生命周期从此时间起算
+- `properties`：显示所有 TBLPROPERTIES
+
+### SHOW CREATE TABLE
+
+```sql
+SHOW CREATE TABLE tname;
+-- 返回完整 DDL，TBLPROPERTIES 中包含 data_lifecycle 等属性
+```
+
+### information_schema.tables
+
+```sql
+SELECT table_name, data_lifecycle, last_modify_time
+FROM information_schema.tables
+WHERE table_schema = 'my_schema';
+-- data_lifecycle = -1 表示永久保留（未设置生命周期）
+-- data_lifecycle > 0 表示已设置生命周期（单位：天）
+```
+
+---
+
+## 分区表
+
+分区表的生命周期按**分区**计算，每个分区独立判断 `last_modified_time`。
+
+```sql
+-- 查看分区的修改时间
+SHOW PARTITIONS EXTENDED tname;
+```
+
+**实际输出字段**（验证结果）：
+
+| 字段 | 说明 |
+|---|---|
+| partitions | 分区值（如 dt=2024-01-01） |
+| total_rows | 分区行数 |
+| bytes | 分区大小 |
+| total_files | 文件数 |
+| created_time | 分区创建时间 |
+| last_modified_time | 分区最后修改时间（生命周期从此起算） |
+| last_data_time | 最后数据写入时间 |
+| last_compaction_time | 最后 compaction 时间 |
+
+---
+
+## Time Travel 语法
+
+```sql
+-- 查询历史时间点数据
+SELECT * FROM tname TIMESTAMP AS OF '<timestamp>';
+SELECT * FROM tname TIMESTAMP AS OF CURRENT_TIMESTAMP - INTERVAL 12 HOURS;
+
+-- 查看版本历史
+DESC HISTORY tname;
+-- 返回：version, time, total_rows, total_bytes, user, operation, job_id, stats
+
+-- 恢复到历史版本（注意：目标时间点必须晚于表创建时间）
+RESTORE TABLE tname TO TIMESTAMP AS OF '<timestamp>';
+
+-- 恢复被删除的表
+UNDROP TABLE tname;
+```
+
+**注意**：`RESTORE TABLE` 的目标时间点不能早于表创建时间，否则报错：
+`InvalidArgument: toTimestamp is smaller than timestamp of fromTimestamp`
+
+---
+
+## 工作原理
+
+1. 生命周期回收依赖 `last_modified_time`（DDL/DML 操作会更新此时间）
+2. 后台进程每 **12 小时**轮询一次，到期数据通常在 **24 小时内**被回收
+3. 到期数据不立即删除，仍可查询，直到后台进程执行
+4. 被回收的数据仍遵守 `data_retention_days`，可用 Time Travel 查询
+5. 默认行为：只清空数据，**保留表结构**；设置 `data_lifecycle_delete_meta='true'` 才删表