@clickzetta/cz-cli-linux-x64 0.3.4 → 0.3.5

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

@@ -1,165 +0,0 @@
----
-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 | 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
-- 数据入仓是最常见的场景，数据入湖主要用于原始数据暂存或跨系统共享

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

@@ -1,211 +0,0 @@
----
-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

@@ -1,175 +0,0 @@
-# 数据生命周期管理参考
-
-> 来源：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'` 才删表