@clickzetta/cz-cli-linux-x64 0.3.0 → 0.3.1

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

@@ -0,0 +1,165 @@
+---
+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、任务等权限
+- clickzetta-studio-mcp 工具可用（`LH_execute_query`、`create_task`、`save_integration_task` 等）
+
+## 数据导入方式决策树
+
+### 步骤 1：确认数据源类型和需求
+
+向用户收集以下信息：
+
+1. **数据源类型**：Kafka / 对象存储(OSS/S3/COS) / 关系型数据库(MySQL/PostgreSQL/SQL Server) / 本地文件 / URL/Web 文件 / Java SDK / ZettaPark
+2. **实时性要求**：实时（秒级延迟）/ 准实时（分钟级）/ 离线批量（小时/天级）
+3. **同步范围**：单表 / 多表 / 整库
+4. **是否需要持续同步**：一次性导入 / 持续增量同步
+5. **是否需要 CDC（变更数据捕获）**：是 / 否
+
+### 步骤 2：根据决策矩阵推荐方案
+
+| 数据源 | 实时性 | 同步范围 | 推荐方式 | 对应 Skill |
+|--------|--------|---------|---------|-----------|
+| Kafka | 实时/准实时 | 单 topic | PIPE 持续导入 | `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
+- 数据入仓是最常见的场景，数据入湖主要用于原始数据暂存或跨系统共享

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

@@ -0,0 +1,211 @@
+---
+name: clickzetta-data-lifecycle
+description: |
+  管理 ClickZetta Lakehouse 表的数据生命周期（TTL）和 Time Travel 数据保留周期。
+  数据生命周期：自动回收超过指定天数未更新的数据（表或分区），释放存储空间。
+  Time Travel 保留周期：控制历史版本数据保留时长，支持时间点查询和数据恢复。
+  当用户说"设置生命周期"、"数据自动清理"、"TTL"、"data_lifecycle"、
+  "表数据过期"、"自动回收数据"、"设置数据保留"、"data_retention_days"、
+  "Time Travel 保留周期"、"查看哪些表有生命周期"、"批量设置生命周期"、
+  "生命周期到期"、"数据生命周期管理"时触发。
+  Keywords: TTL, data retention, time travel, lifecycle, auto-purge, storage
+---
+
+# ClickZetta 数据生命周期管理
+
+阅读 [references/lifecycle-reference.md](references/lifecycle-reference.md) 了解完整语法。
+
+## 两个独立概念
+
+| 概念 | 属性键 | 作用 | 默认值 |
+|---|---|---|---|
+| 数据生命周期（TTL） | `data_lifecycle` | 自动回收超期未更新的数据 | `-1`（永不回收） |
+| Time Travel 保留周期 | `data_retention_days` | 历史版本保留时长，支持时间点查询和恢复 | `1`（1天） |
+
+两者可同时设置，互不影响。
+
+---
+
+## 设置数据生命周期（TTL）
+
+### 建表时设置
+
+```sql
+-- 数据 7 天未更新则自动清空（保留表结构）
+CREATE TABLE orders_archive (
+    order_id BIGINT,
+    amount DECIMAL(10,2),
+    created_at TIMESTAMP
+) PROPERTIES('data_lifecycle'='7');
+
+-- 数据 30 天未更新则自动删除表结构和数据
+CREATE TABLE temp_staging (
+    id INT,
+    data STRING
+) PROPERTIES('data_lifecycle'='30', 'data_lifecycle_delete_meta'='true');
+```
+
+### 修改现有表
+
+```sql
+-- 设置生命周期为 90 天
+ALTER TABLE my_table SET PROPERTIES ('data_lifecycle'='90');
+
+-- 同时设置生命周期和到期删除表结构
+ALTER TABLE my_table SET PROPERTIES ('data_lifecycle'='90', 'data_lifecycle_delete_meta'='true');
+
+-- 关闭生命周期（永久保留）
+ALTER TABLE my_table SET PROPERTIES ('data_lifecycle'='-1');
+```
+
+---
+
+## 设置 Time Travel 保留周期
+
+```sql
+-- 设置保留 7 天历史版本（范围 0-90 天）
+ALTER TABLE my_table SET PROPERTIES ('data_retention_days'='7');
+
+-- 建表时同时设置两个属性
+CREATE TABLE important_data (
+    id INT,
+    val STRING
+) PROPERTIES('data_lifecycle'='365', 'data_retention_days'='30');
+```
+
+---
+
+## 查看生命周期配置
+
+### 查看单张表
+
+```sql
+-- 查看表属性（含 data_lifecycle 和 data_retention_days）
+SHOW CREATE TABLE my_table;
+
+-- 查看详细信息（含 last_modified_time 和 properties）
+DESC EXTENDED my_table;
+```
+
+### 批量查询（通过 information_schema）
+
+```sql
+-- 查看当前 Schema 下所有表的生命周期配置
+-- data_lifecycle = -1 表示永久保留
+SELECT table_name, data_lifecycle, last_modify_time
+FROM information_schema.tables
+WHERE table_schema = 'my_schema'
+ORDER BY data_lifecycle DESC;
+
+-- 找出已设置生命周期的表（data_lifecycle > 0）
+SELECT table_schema, table_name, data_lifecycle, last_modify_time
+FROM information_schema.tables
+WHERE data_lifecycle > 0
+ORDER BY data_lifecycle;
+
+-- 找出未设置生命周期的表（潜在存储浪费）
+SELECT table_schema, table_name, bytes / 1024 / 1024 AS size_mb, last_modify_time
+FROM information_schema.tables
+WHERE data_lifecycle = -1
+  AND table_type = 'MANAGED_TABLE'
+  AND bytes > 100 * 1024 * 1024  -- 大于 100MB
+ORDER BY bytes DESC;
+```
+
+### 查看分区表的分区修改时间
+
+```sql
+-- 分区表生命周期按分区的 last_modified_time 计算
+SHOW PARTITIONS EXTENDED my_partitioned_table;
+-- 返回字段：partitions, total_rows, bytes, total_files,
+--           created_time, last_modified_time, last_data_time, last_compaction_time
+```
+
+---
+
+## Time Travel 查询历史数据
+
+```sql
+-- 查询指定时间点的历史数据
+SELECT * FROM my_table
+TIMESTAMP AS OF '2024-01-15 10:00:00';
+
+-- 查询 N 小时前的数据
+SELECT * FROM my_table
+TIMESTAMP AS OF CURRENT_TIMESTAMP - INTERVAL 12 HOURS;
+
+-- 查看表的版本历史
+DESC HISTORY my_table;
+-- 返回：version, time, total_rows, total_bytes, user, operation, job_id, stats
+```
+
+---
+
+## 数据恢复
+
+```sql
+-- 恢复表到指定时间点（覆盖当前数据）
+RESTORE TABLE my_table TO TIMESTAMP AS OF '2024-01-15 10:00:00';
+
+-- 恢复被误删的表
+UNDROP TABLE my_table;
+```
+
+---
+
+## 典型场景
+
+### 场景 1：日志表按月清理
+
+```sql
+CREATE TABLE app_logs (
+    log_id BIGINT,
+    level STRING,
+    message STRING,
+    log_time TIMESTAMP
+) PROPERTIES('data_lifecycle'='30');
+```
+
+### 场景 2：临时中间表自动清理
+
+```sql
+CREATE TABLE etl_staging_temp (
+    id INT,
+    raw_data STRING
+) PROPERTIES('data_lifecycle'='3', 'data_lifecycle_delete_meta'='true');
+```
+
+### 场景 3：重要业务表保留长历史
+
+```sql
+-- 数据永久保留，但保留 30 天历史版本用于审计回溯
+ALTER TABLE orders SET PROPERTIES ('data_retention_days'='30');
+```
+
+### 场景 4：批量为未设置生命周期的大表设置 TTL
+
+```sql
+-- 先查出未设置生命周期的大表
+SELECT table_name, bytes / 1024 / 1024 AS size_mb
+FROM information_schema.tables
+WHERE table_schema = 'my_schema'
+  AND data_lifecycle = -1
+  AND table_type = 'MANAGED_TABLE'
+ORDER BY bytes DESC;
+
+-- 逐一设置（需手动执行每条）
+ALTER TABLE table_a SET PROPERTIES ('data_lifecycle'='180');
+ALTER TABLE table_b SET PROPERTIES ('data_lifecycle'='90');
+```
+
+---
+
+## 注意事项
+
+1. **回收不立即执行**：生命周期到期后，后台进程每 12 小时轮询一次，通常 24 小时内完成回收
+2. **默认保留表结构**：到期只清空数据，不删除表；加 `data_lifecycle_delete_meta='true'` 才删表
+3. **分区表按分区计算**：每个分区独立计算 `last_modified_time`，分区到期独立回收
+4. **`data_lifecycle=-1`**：表示永久保留，`information_schema.tables` 中显示为 `-1`
+5. **Time Travel 默认 1 天**：默认只能查 1 天内历史；需要更长回溯窗口须提前设置 `data_retention_days`
+6. **`data_retention_days` 范围 0-90**：最长 90 天，超出范围报错
+7. **策略变更竞态**：修改生命周期天数时，极少数情况下回收任务可能按旧策略执行一次，属正常机制

package/bin/skills/clickzetta-data-lifecycle/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'` 才删表