@clickzetta/cz-cli-darwin-arm64 0.3.17 → 0.3.19

package/bin/skills/clickzetta-data-ingest-pipeline/SKILL.md

@@ -0,0 +1,220 @@
+---
+name: clickzetta-data-ingest-pipeline
+description: |
+  ClickZetta Lakehouse 数据导入总览与路由。根据用户的数据源类型、实时性要求、数据量等条件，
+  推荐最合适的数据导入方式，并引导到对应的专项 Skill 或直接执行简单导入操作。
+  当用户说"导入数据到 Lakehouse"、"数据入仓"、"数据入湖"、"怎么把数据导进来"、
+  "数据采集"、"数据加载"、"ingest data"、"load data"、"数据导入方案选择"时触发。
+  Keywords: data ingestion, import, routing, pipeline selection, data source
+---
+
+# Lakehouse 数据导入总览与路由
+
+根据用户的数据源、实时性需求、数据规模等条件，推荐最合适的数据导入方式，
+并路由到对应的专项 Pipeline Skill 或直接执行简单导入操作。
+
+## 适用场景
+
+- 用户想把数据导入 ClickZetta Lakehouse，但不确定用哪种方式
+- 用户描述了数据源（Kafka、MySQL、OSS、文件等），需要推荐导入方案
+- 用户需要了解各种导入方式的适用场景和差异
+- 关键词：数据导入、数据入仓、数据入湖、数据采集、数据加载、pipeline 选择
+
+## 前置依赖
+
+- ClickZetta Lakehouse 账户，具备创建工作空间、Schema、表、PIPE、任务等权限
+- **执行环境（满足其一即可，优先使用 cz-cli）**：
+  - **cz-cli 路径**：已安装 cz-cli（`pip install cz-cli`），并完成 `cz-cli configure` 配置
+  - **MCP 路径**：clickzetta-studio-mcp 或 clickzetta-mcp-server 工具可用（`LH_execute_query`、`create_task`、`save_integration_task` 等）
+
+## 环境探测（执行前必读）
+
+在开始任何操作前，先判断当前执行环境：
+
+**第一步：检测 cz-cli 是否可用**
+```bash
+cz-cli --version
+```
+- 若命令存在 → **走 cz-cli 路径**（见本文档末尾"cz-cli 替代路径"章节，以及各专项 Skill 的 cz-cli 替代路径）
+- 若命令不存在 → 继续检测 MCP
+
+**第二步：检测 MCP 是否可用（仅在 cz-cli 不可用时）**
+
+尝试调用 `LH_execute_query` 工具执行一条简单 SQL（如 `SELECT 1`）。
+- 若工具存在于 tool list → **走 MCP 路径**（本文档默认路径）
+- 若工具不存在 → 停止执行，提示用户：
+  > "当前环境既无 cz-cli 也无 MCP 工具，请安装其中之一后重试。
+  > cz-cli 安装：`pip install cz-cli`，然后运行 `cz-cli configure`
+  > MCP 安装：参考 clickzetta-studio-mcp 或 clickzetta-mcp-server 配置文档"
+
+## 数据导入方式决策树
+
+### 步骤 1：确认数据源类型和需求
+
+向用户收集以下信息：
+
+1. **数据源类型**：Kafka / 对象存储(OSS/S3/COS) / 关系型数据库(MySQL/PostgreSQL/SQL Server) / 本地文件 / URL/Web 文件 / Java SDK / ZettaPark
+2. **实时性要求**：实时（秒级延迟）/ 准实时（分钟级）/ 离线批量（小时/天级）
+3. **同步范围**：单表 / 多表 / 整库
+4. **是否需要持续同步**：一次性导入 / 持续增量同步
+5. **是否需要 CDC（变更数据捕获）**：是 / 否
+
+### 步骤 2：根据决策矩阵推荐方案
+
+| 数据源 | 实时性 | 同步范围 | 推荐方式 | 对应 Skill |
+|--------|--------|---------|---------|-----------|
+| Kafka | 实时/准实时 | 单 topic | Kafka PIPE 持续导入（SQL） | `clickzetta-kafka-ingest-pipeline` |
+| Kafka | 实时 | 多 topic | Studio 实时同步 | `clickzetta-realtime-sync-pipeline` |
+| 对象存储 (OSS/S3/COS) | 准实时/批量 | 文件持续到达 | PIPE 持续导入 | `clickzetta-oss-ingest-pipeline` |
+| 对象存储 | 一次性 | 批量文件 | COPY INTO 命令 | `clickzetta-file-import-pipeline`（COPY INTO 部分） |
+| MySQL/PostgreSQL/SQL Server | 实时 CDC | 单表 | Studio 实时同步 | `clickzetta-realtime-sync-pipeline` |
+| MySQL/PostgreSQL/SQL Server | 实时 CDC | 多表/整库 | Studio 多表实时同步 | `clickzetta-cdc-sync-pipeline` |
+| MySQL/PostgreSQL/SQL Server | 离线批量 | 单表 | Studio 离线同步 | `clickzetta-batch-sync-pipeline` |
+| MySQL/PostgreSQL/SQL Server | 离线批量 | 多表 | Studio 多表离线同步 | `clickzetta-batch-sync-pipeline` |
+| 本地文件 / URL | 一次性 | 单文件/多文件 | URL 下载 + COPY INTO | `clickzetta-file-import-pipeline` |
+| 流式增量计算 | 准实时 | 表变更驱动 | Dynamic Table + Stream | `clickzetta-incremental-compute-pipeline` |
+| Java 应用 | 实时/批量 | 程序写入 | Java SDK | （见下方 SDK 导入指引） |
+| Python/ZettaPark | 批量 | DataFrame | ZettaPark save_as_table | （见下方 SDK 导入指引） |
+
+### 步骤 3：路由到专项 Skill 或直接执行
+
+根据推荐方案，执行以下路由逻辑：
+
+**有对应专项 Skill 的场景** → 告知用户推荐方案，引导使用对应 Skill：
+- `clickzetta-kafka-ingest-pipeline`：Kafka PIPE 管道搭建
+- `clickzetta-oss-ingest-pipeline`：对象存储 PIPE 管道搭建
+- `clickzetta-batch-sync-pipeline`：Studio 离线同步任务
+- `clickzetta-realtime-sync-pipeline`：Studio 实时同步任务
+- `clickzetta-cdc-sync-pipeline`：Studio 多表实时同步（CDC）
+- `clickzetta-incremental-compute-pipeline`：Dynamic Table + Stream 增量计算管道
+- `clickzetta-file-import-pipeline`：URL/文件下载导入
+- `clickzetta-table-stream-pipeline`：Table Stream 变更数据捕获
+
+**无专项 Skill 的简单场景** → 直接执行：
+
+#### SQL INSERT 导入（小数据量）
+```sql
+-- 使用 LH_execute_query 执行
+INSERT INTO schema_name.table_name (col1, col2, col3)
+VALUES ('val1', 'val2', 'val3');
+```
+
+#### COPY INTO 快速导入（从 Volume）
+```sql
+-- 1. 确认 Volume 中有文件
+SHOW VOLUME DIRECTORY volume_name;
+
+-- 2. 执行 COPY INTO
+COPY INTO schema_name.table_name
+FROM VOLUME volume_name
+USING CSV
+OPTIONS('header' = 'true');
+```
+
+#### Java SDK 导入指引
+提供 Java SDK 的关键配置信息：
+- Maven 依赖坐标
+- 连接配置（endpoint、workspace、schema、vcluster）
+- 批量写入 API：`BulkloadWriter`
+- 实时写入 API：`RealtimeWriter`
+- 建议用户参考官方文档：`comprehensive_guide_to_ingesting_javasdk_buckload_realtime`
+
+#### ZettaPark (Python) 导入指引
+- `INSERT` 方式：`session.sql("INSERT INTO ...")`
+- `save_as_table` 方式：`df.write.save_as_table("table_name")`
+- 建议用户参考官方文档：`comprehensive_guide_to_ingesting_zettapark_save_as_table`
+
+## 数据入仓 vs 数据入湖
+
+| 维度 | 数据入仓 | 数据入湖 |
+|------|---------|---------|
+| 目标 | Lakehouse 托管表 | 用户 Volume（对象存储） |
+| 格式 | 自动转为内部列式格式 | 保持原始文件格式 |
+| 查询性能 | 高（列式存储 + 索引） | 较低（需扫描原始文件） |
+| 适用场景 | 分析查询、BI 报表、数据仓库 | 数据暂存、原始数据归档、跨系统共享 |
+| 常用方式 | Studio 同步、PIPE、COPY INTO、SDK | PUT 文件、Python 脚本上传 |
+
+## 示例
+
+### 示例 1：用户不确定导入方式
+
+用户说："我有一个 MySQL 数据库，想把里面的订单表实时同步到 Lakehouse"
+
+路由逻辑：
+1. 数据源：MySQL（关系型数据库）
+2. 实时性：实时
+3. 同步范围：单表
+4. 需要 CDC：是（实时同步意味着需要捕获变更）
+→ 推荐：Studio 实时同步
+→ 路由到 `clickzetta-realtime-sync-pipeline` Skill
+
+### 示例 2：多种数据源混合场景
+
+用户说："我们有 Kafka 的用户行为日志，还有 MySQL 的业务数据，都要导入 Lakehouse"
+
+路由逻辑：
+1. Kafka 用户行为日志 → `clickzetta-kafka-ingest-pipeline`（PIPE 持续导入）
+2. MySQL 业务数据 → 确认实时性需求：
+   - 实时 → `clickzetta-realtime-sync-pipeline` 或 `clickzetta-cdc-sync-pipeline`
+   - 离线 → `clickzetta-batch-sync-pipeline`
+→ 分别引导到对应 Skill
+
+### 示例 3：简单的一次性文件导入
+
+用户说："我有一个 CSV 文件要导入"
+
+路由逻辑：
+1. 数据源：本地文件
+2. 一次性导入
+→ 路由到 `clickzetta-file-import-pipeline` Skill（支持文件上传 + COPY INTO）
+
+## 错误处理
+
+| 场景 | 处理方式 |
+|------|---------|
+| 用户无法确定数据源类型 | 询问数据当前存储位置（哪个系统/服务），帮助判断 |
+| 用户需求跨多种导入方式 | 拆分为多个独立的导入任务，分别路由到对应 Skill |
+| 推荐的 Skill 尚未创建 | 提供该导入方式的基本步骤和关键 SQL/API，引导用户参考官方文档 |
+| 用户的云环境不支持某种连接 | 使用 `LH_show_object_list`（object_type=CONNECTIONS）检查可用连接类型，推荐替代方案 |
+| 数据量极大（TB 级） | 建议分批导入，优先使用 PIPE 或 Studio 同步任务（支持断点续传） |
+
+## 注意事项
+
+- 本 Skill 是路由入口，不直接执行复杂的 pipeline 搭建，而是引导到专项 Skill
+- 对于简单场景（SQL INSERT、单次 COPY INTO），可以直接在本 Skill 中完成
+- 推荐方案时需考虑用户的云环境（阿里云/腾讯云/AWS），不同环境支持的连接类型可能不同
+- 使用 `LH_show_object_list`（object_type=VCLUSTERS）确认可用的虚拟集群，同步任务需要 SYNC 类型的 VCluster
+- 数据入仓是最常见的场景，数据入湖主要用于原始数据暂存或跨系统共享
+
+---
+
+## cz-cli 替代路径
+
+> 仅在 cz-cli 可用且 MCP 不可用时使用本节。
+> 本 Skill 是路由入口，cz-cli 路径的核心逻辑在各专项 Skill 的"cz-cli 替代路径"章节中。
+
+### 路由说明
+
+当 MCP 不可用时，各专项 Skill 均已提供 cz-cli 替代路径：
+
+| 数据源 | 推荐方式 | 对应 Skill 的 cz-cli 路径 |
+|--------|---------|--------------------------|
+| Kafka | PIPE 持续导入 | `clickzetta-kafka-ingest-pipeline` → cz-cli 替代路径 |
+| 对象存储 (OSS/S3/COS) | PIPE 持续导入 | `clickzetta-oss-ingest-pipeline` → cz-cli 替代路径 |
+| MySQL/PostgreSQL/SQL Server（实时单表） | Studio 实时同步 | `clickzetta-realtime-sync-pipeline` → cz-cli 替代路径 |
+| MySQL/PostgreSQL/SQL Server（实时多表/整库） | Studio 多表实时同步 | `clickzetta-cdc-sync-pipeline` → cz-cli 替代路径 |
+| MySQL/PostgreSQL/SQL Server（离线批量） | Studio 离线同步 | `clickzetta-batch-sync-pipeline` → cz-cli 替代路径 |
+
+### 简单场景直接执行（cz-cli 版）
+
+对于无需专项 Skill 的简单场景，可直接用 cz-cli agent 完成：
+
+```bash
+# SQL INSERT 导入（小数据量）
+cz-cli agent run "向表 <schema_name>.<table_name> 插入数据：<col1>=<val1>, <col2>=<val2>" \
+  --format a2a --dangerously-skip-permissions
+
+# COPY INTO 快速导入（从 Volume）
+cz-cli agent run "从 Volume <volume_name> 以 CSV 格式（有 header）将数据导入表 <schema_name>.<table_name>" \
+  --format a2a --dangerously-skip-permissions
+```

package/bin/skills/clickzetta-data-ingest-pipeline/eval_cases.jsonl

@@ -0,0 +1,5 @@
+{"case_id":"001","type":"should_call","user_input":"我想把数据导入 Lakehouse，但不确定用哪种方式","expected_skill":"clickzetta-data-ingest-pipeline","expected_output_contains":["数据源","实时","批量"]}
+{"case_id":"002","type":"should_call","user_input":"数据入仓有哪些方案？怎么选择？","expected_skill":"clickzetta-data-ingest-pipeline","expected_output_contains":["Kafka","对象存储","MySQL"]}
+{"case_id":"003","type":"should_call","user_input":"我有 MySQL 和 Kafka 两个数据源要导入 Lakehouse，分别用什么方式？","expected_skill":"clickzetta-data-ingest-pipeline","expected_output_contains":["CDC"]}
+{"case_id":"004","type":"should_call","user_input":"数据导入方案怎么选？实时和离线有什么区别？","expected_skill":"clickzetta-data-ingest-pipeline","expected_output_contains":["实时","离线","延迟"]}
+{"case_id":"005","type":"should_call","user_input":"ingest data into ClickZetta Lakehouse, what options do I have?","expected_skill":"clickzetta-data-ingest-pipeline","expected_output_contains":["Kafka","OSS","SDK"]}

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'` 才删表