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

package/bin/skills/clickzetta-query-optimizer/references/explain.md

@@ -0,0 +1,56 @@
+# EXPLAIN 命令参考
+
+> 来源：https://www.yunqi.tech/documents/EXPLAIN
+
+## 语法
+
+```sql
+EXPLAIN [EXTENDED] query_statement
+```
+
+## 两种模式
+
+### 基础模式（EXPLAIN）
+
+显示物理执行计划，用于快速理解查询执行方式。
+
+```sql
+EXPLAIN SELECT * FROM orders LIMIT 5;
+```
+
+输出示例：
+```
+Type: DML
+Plan: PhysicalTableSink() name=TableSink0 stage=stg0
+  PhysicalTableScan(orders, a) as [0] name=TableScan1
+```
+
+### 扩展模式（EXPLAIN EXTENDED）
+
+显示完整的逻辑执行计划 + 物理执行计划，包含表达式转换、系统列、优化过程。
+
+```sql
+EXPLAIN EXTENDED SELECT * FROM orders LIMIT 5;
+```
+
+输出包含：
+- `[LogicalPlan]`：逻辑执行计划
+- `[PhysicalPlan]`：物理执行计划
+- 系统隐藏列信息（`__commit_version`、`__change_type` 等）
+
+## 常见操作符说明
+
+| 操作符 | 说明 | 性能特征 |
+|---|---|---|
+| PhysicalTableScan | 从表读取数据 | 基础 I/O 操作 |
+| PhysicalTableSink | 输出查询结果 | 固定开销 |
+| PhysicalSort | 对数据排序 | O(n log n)，可能成为瓶颈 |
+| PhysicalFilter | 条件过滤 | 线性操作，早期过滤是最佳实践 |
+| PhysicalHashAggregate | 聚合操作 | 根据 GROUP BY 基数变化 |
+| PhysicalJoin | JOIN 操作 | 复杂度取决于 JOIN 策略和数据量 |
+
+## 使用建议
+
+- 先用 `EXPLAIN` 快速确认执行路径
+- 发现异常（如全表扫描、大量 Sort）再用 `EXPLAIN EXTENDED` 深入分析
+- 关注 PhysicalJoin 的策略：是否触发了 MapJoin（小表广播）

package/bin/skills/clickzetta-query-optimizer/references/hints-and-sortkey.md

@@ -0,0 +1,78 @@
+# Map Join 与 Sort Key 推荐参考
+
+> 来源：https://www.yunqi.tech/documents/mapjoin 和 https://www.yunqi.tech/documents/auto-index
+
+---
+
+## Map Join（小表广播优化）
+
+### 语法
+
+```sql
+SELECT /*+ MAPJOIN (small_table_alias) */ *
+FROM large_table t1
+JOIN small_table t2 ON t1.id = t2.id;
+```
+
+### 说明
+
+- 将小表广播到各节点，在 Map 阶段完成 JOIN，避免 Shuffle
+- **小表大小限制：1GB**，超过则 Map Join 失败或退化为普通 JOIN
+- 适用于小表 JOIN 大表，不适用于大表 JOIN 大表
+
+### 示例
+
+```sql
+-- 员工与部门关联
+SELECT /*+ MAPJOIN (dept) */ *
+FROM employees emp
+JOIN departments dept ON emp.dept_id = dept.dept_id;
+
+-- 订单与客户关联
+SELECT /*+ MAPJOIN (customer) */ *
+FROM orders o
+JOIN customers customer ON o.customer_id = customer.customer_id;
+```
+
+---
+
+## Sort Key 推荐（自动索引建议）
+
+### 启用自动收集
+
+```sql
+-- 按天收集（推荐）
+ALTER WORKSPACE workspace_name SET PROPERTIES (auto_index='day');
+
+-- 自定义参数：天/月, 最近N分钟job, 最少重复次数, 最多job数
+ALTER WORKSPACE workspace_name SET PROPERTIES (auto_index='day,150,5,100');
+```
+
+参数说明：
+- 第 1 个参数：`day`（每天）或 `month`（每月 1 号），收集时间为晚上 6 点
+- 第 2 个参数：使用最近多少分钟的 job（默认 150）
+- 第 3 个参数：job 需要重复多少次才被采用（默认 5）
+- 第 4 个参数：每列最多使用的 job 数（默认 100）
+
+### 查询推荐结果
+
+```sql
+SELECT * FROM information_schema.sortkey_candidates;
+```
+
+返回字段：`table_name`、`col`（推荐列）、`statement`（可直接执行的 ALTER 语句）、`ratio`（估算提升效果百分比）
+
+### 应用推荐
+
+```sql
+-- 直接执行 statement 列中的 SQL 即可设置 sort key
+ALTER TABLE schema.table_name SET PROPERTIES("hint.sort.columns"="column_name");
+```
+
+### 建议
+
+执行前先对表收集统计信息，提高推荐准确性：
+
+```sql
+ANALYZE TABLE schema.table_name;
+```

package/bin/skills/clickzetta-query-optimizer/references/optimize.md

@@ -0,0 +1,65 @@
+# OPTIMIZE 命令参考
+
+> 来源：https://www.yunqi.tech/documents/OPTIMIZE 和 https://www.yunqi.tech/documents/small_file_optimization
+
+## 语法
+
+```sql
+OPTIMIZE table_name
+[WHERE predicate]
+[OPTIONS('key' = 'value')]
+```
+
+## 参数说明
+
+- `table_name`：格式为 `[schema_name.]table_name`
+- `WHERE predicate`：（可选）分区过滤条件，必须包含完整分区列匹配
+  - 格式：`partition_column = 'value'` 或 `dt='2023-01-01' AND region='us'`
+- `OPTIONS`：（可选）控制执行模式
+
+## 执行模式
+
+### 异步模式（默认）
+
+立即返回 Job ID，后台执行，不阻塞当前连接。
+
+```sql
+-- 默认异步
+OPTIMIZE my_schema.orders;
+
+-- 显式指定异步
+OPTIMIZE my_schema.orders OPTIONS('cz.sql.optimize.table.async' = 'true');
+```
+
+### 同步模式
+
+阻塞直到完成，适合开发测试和小表优化。
+
+```sql
+OPTIMIZE my_schema.orders OPTIONS('cz.sql.optimize.table.async' = 'false');
+```
+
+## 核心功能
+
+- **小文件合并**：将多个小文件整合为大文件，减少文件元数据开销
+- **删除标记清理**：清理 UPDATE/DELETE 产生的删除标记，回收存储空间
+- **数据重组**：重新整理数据布局，提升查询性能
+
+## 注意事项
+
+- **只能在通用型计算集群（GENERAL PURPOSE VIRTUAL CLUSTER）运行**，分析型集群不生效
+- 后台默认会不定时自动执行文件合并，手动 OPTIMIZE 用于精细控制
+
+## DML 写入时自动触发小文件合并
+
+```sql
+-- 在 DML 执行时同时触发小文件合并
+SET cz.sql.compaction.after.commit = true;
+INSERT INTO my_table VALUES (...);
+```
+
+## 查看分区文件数量
+
+```sql
+SHOW PARTITIONS EXTENDED table_name;
+```

package/bin/skills/clickzetta-query-optimizer/references/result-cache.md

@@ -0,0 +1,49 @@
+# Result Cache（查询结果缓存）参考
+
+> 来源：https://www.yunqi.tech/documents/result_cache
+
+## 概述
+
+ClickZetta Lakehouse 提供三种缓存：
+1. **查询结果缓存（Result Cache）** — 本文档
+2. 元数据缓存（Metadata Cache）— 工作空间内共享
+3. 虚拟集群本地缓存（Local Disk Cache）— 仅限指定集群
+
+## 启用 / 禁用
+
+```sql
+-- 开启结果缓存（SESSION 级别）
+SET cz.sql.enable.shortcut.result.cache = true;
+
+-- 关闭结果缓存
+SET cz.sql.enable.shortcut.result.cache = false;
+```
+
+> 注意：当前默认未开启，需手动启用。
+
+## 缓存复用条件（同时满足才能命中）
+
+1. 查询中使用的表数据未发生变更
+2. 查询中不包含视图引用
+3. 新 SQL 与之前执行的 SQL 语法精确匹配
+4. 查询中不包含非确定性函数（如 `CURRENT_TIMESTAMP()`）或 UDF
+5. 之前的 Result Cache 未过期
+
+## 过期周期
+
+- 默认保留 **24 小时**
+- 24 小时内有查询复用，则额外延长 24 小时
+- 超过 24 小时无复用则清除
+
+## 约束与限制
+
+| 项目 | 限制 |
+|---|---|
+| 缓存保留周期 | 24 小时 |
+| 单工作空间最大缓存作业数 | 10 万 |
+| 缓存大小 | 无限制（≤10MB 存内存，>10MB 持久化到对象存储） |
+| 不支持 | 含非确定性函数、UDF 的查询 |
+
+## 验证是否命中缓存
+
+第二次执行相同查询后，在 Job Profile 的执行计划图中查看是否出现 `JOB RESULT REUSE` 标记。命中缓存的查询通常在 15ms 内返回。

package/bin/skills/clickzetta-query-optimizer/references/show-jobs.md

@@ -0,0 +1,42 @@
+# SHOW JOBS 参考
+
+> 来源：https://www.yunqi.tech/documents/show-jobs
+
+## 语法
+
+```sql
+SHOW JOBS [IN VCLUSTER vc_name] [LIKE 'pattern'] [WHERE <expr>] [LIMIT num];
+```
+
+## 参数说明
+
+- `IN VCLUSTER vc_name`：（可选）筛选指定计算集群下的作业
+- `WHERE <expr>`：（可选）按字段过滤，支持 SHOW JOBS 返回的所有字段
+- `LIMIT num`：（可选）限制返回数量，范围 1-10000
+- `LIKE 'pattern'`：（可选）按 job_id 模式匹配，支持 `%` 和 `_`
+
+默认显示最近 7 天内提交的任务，最多 10000 条。
+
+## 示例
+
+```sql
+-- 查看执行时间超过 2 分钟的作业
+SHOW JOBS IN VCLUSTER default_ap WHERE execution_time > interval 2 minute;
+
+-- 查看指定集群的所有作业
+SHOW JOBS IN VCLUSTER default_ap;
+
+-- 限制返回 100 条
+SHOW JOBS LIMIT 100;
+
+-- 查看指定集群最近 50 条
+SHOW JOBS IN VCLUSTER default_ap LIMIT 50;
+
+-- 按 job_id 模式匹配
+SHOW JOBS LIKE 'job_2024%';
+```
+
+## 注意事项
+
+- 只能查看最近 7 天内的作业记录
+- 未指定 VCLUSTER 时显示所有集群的作业

package/bin/skills/clickzetta-realtime-sync-pipeline/SKILL.md

@@ -0,0 +1,276 @@
+---
+name: clickzetta-realtime-sync-pipeline
+description: |
+  创建和管理 ClickZetta Lakehouse 实时同步任务（单表），将外部数据源的数据实时同步到 Lakehouse。
+  支持 Kafka、MySQL、PostgreSQL 等数据源作为来源端，Lakehouse 作为目标端。
+  实时同步任务为持续运行的流式任务，无需配置调度策略，提交后即持续运行。
+  当用户说"Studio 实时同步"、"realtime sync"、"单表 CDC 同步"、"实时数据同步"、"Kafka 实时同步到 Lakehouse"、
+  "MySQL 单表实时同步"、"单表实时同步"、"实时数据迁移"时触发。
+  包含实时同步任务创建、数据源配置、字段映射（含 JSONPath 计算列）、部署运维等
+  ClickZetta Studio 特有逻辑。
+  Keywords: real-time sync, single table, Kafka source, MySQL source, streaming
+---
+
+# 实时同步（单表）Pipeline 工作流
+
+## 适用场景
+
+- 将外部数据源的数据实时同步到 Lakehouse（低延迟、持续运行）
+- Kafka Topic → Lakehouse 表（支持 JSON 消息解析）
+- MySQL / PostgreSQL / SQL Server 等数据库 → Lakehouse 表（CDC 变更捕获）
+- 数据时效性要求高，需要秒级或分钟级延迟
+- 单张源表/Topic 到单张目标表的实时同步
+- 关键词：实时同步、CDC、流式同步、realtime sync、Kafka 实时同步
+
+## 与其他同步方式的区别
+
+| 维度 | 实时同步（本 Skill） | 离线同步 | 多表实时同步 |
+|------|---------------------|---------|------------|
+| 任务类型 ID | `28`（实时同步） | `10` / `291` | `281` |
+| 同步粒度 | 单表/单 Topic | 单表/多表 | 整库/多表 |
+| 运行模式 | 持续运行（流式） | 周期调度（批量） | 持续运行（流式） |
+| 调度策略 | 无需配置，提交即运行 | 需配置 Cron 表达式 | 无需配置，提交即运行 |
+| 延迟 | 秒级~分钟级 | 取决于调度周期 | 秒级~分钟级 |
+| 适用 Skill | `clickzetta-realtime-sync-pipeline` | `clickzetta-batch-sync-pipeline` | `clickzetta-cdc-sync-pipeline` |
+
+## 前置依赖
+
+- ClickZetta Lakehouse Studio 账户，具备创建同步任务、目标表的权限
+- 源端数据源已在 Studio 中配置（Kafka / MySQL / PostgreSQL / SQL Server 等）
+- 目标端 Lakehouse 数据源可用
+- Sync VCluster 可用（实时同步任务 task_type=28 需要 Sync VCluster）
+- **执行环境（满足其一即可，优先使用 cz-cli）**：
+  - **cz-cli 路径**：已安装 cz-cli（`pip install cz-cli`），并完成 `cz-cli configure` 配置
+  - **MCP 路径**：clickzetta-studio-mcp 工具可用（`create_task`、`save_integration_task`、`publish_task`、`list_data_sources`、`LH_show_object_list` 等）
+
+## 环境探测（执行前必读）
+
+在开始任何操作前，先判断当前执行环境：
+
+**第一步：检测 cz-cli 是否可用**
+```bash
+cz-cli --version
+```
+- 若命令存在 → **走 cz-cli 路径**（见本文档末尾"cz-cli 替代路径"章节）
+- 若命令不存在 → 继续检测 MCP
+
+**第二步：检测 MCP 是否可用（仅在 cz-cli 不可用时）**
+
+尝试调用 `list_data_sources` 工具查询数据源列表。
+- 若工具存在于 tool list → **走 MCP 路径**（本文档默认路径）
+- 若工具不存在 → 停止执行，提示用户：
+  > "当前环境既无 cz-cli 也无 MCP 工具，请安装其中之一后重试。
+  > cz-cli 安装：`pip install cz-cli`，然后运行 `cz-cli configure`
+  > MCP 安装：参考 clickzetta-studio-mcp 配置文档"
+
+## 工作流
+
+### 步骤 1：确认 Sync VCluster 可用
+
+```
+使用 LH_show_object_list（object_type='VCLUSTERS'）查看可用虚拟集群。
+筛选 vcluster_type 包含 SYNC 的集群。
+如无可用 Sync VCluster，需先创建后再继续。
+```
+
+### 步骤 2：查找可用数据源
+
+```
+使用 list_data_sources 查看已配置的数据源列表。
+按类型过滤：
+- Kafka: ds_type=2
+- MySQL: ds_type=5
+- PostgreSQL: ds_type=7
+- SQL Server: ds_type=8
+记录源端 datasource_name 和目标端 Lakehouse datasource_name。
+```
+
+### 步骤 3：探查源端数据结构（可选）
+
+```
+使用 list_namespaces 查看源端数据源的命名空间（数据库/Schema）。
+使用 list_metadata_objects 查看命名空间下的表/Topic 列表。
+使用 get_metadata_detail 查看具体表/Topic 的字段结构。
+```
+
+### 步骤 4：创建实时同步任务
+
+```
+使用 create_task 创建任务：
+- task_type: 28（实时同步）
+- task_name: 自定义任务名称（建议包含源和目标信息，如 "rt_sync_kafka_orders"）
+- data_folder_id: 目标文件夹 ID（可通过 list_folders 获取）
+
+记录返回的 task_id 和 studio_url。
+```
+
+### 步骤 5：配置同步内容
+
+```
+使用 save_integration_task 配置同步：
+- task_id: 步骤 4 返回的任务 ID
+- source_datasource_name: 源端数据源名称
+- source_schema: 源端数据库/Schema（Kafka 场景为 Topic 所在命名空间）
+- source_table: 源端表名或 Kafka Topic 名称
+- source_ds_type: 源端类型（2=Kafka, 5=MySQL, 7=PostgreSQL, 8=SQL Server）
+- sink_datasource_name: 目标 Lakehouse 数据源名称
+- sink_schema: 目标 Schema（默认 public）
+- sink_table: 目标表名（可选，默认与源表同名）
+- sink_ds_type: 1（Lakehouse）
+```
+
+> **说明**：系统会自动获取源端和目标端的元数据，生成字段映射。如目标表不存在，会自动创建。
+
+### 步骤 6：Kafka JSON 消息解析（Kafka 数据源专用）
+
+如果 Kafka Topic 的消息格式为 JSON，可在 Studio UI 中通过新增计算列解析嵌套字段：
+
+- 使用 JSONPath 规则解析 value 字段中的内容
+- 示例：`$.id` 提取顶层 id 字段，`$.data.code` 提取嵌套字段
+- 默认使用 Kafka Topic 内置字段（key、value、timestamp、partition、offset）进行映射
+- 计算列配置需在 Studio UI 中完成（通过 studio_url 打开）
+
+### 步骤 7：提交部署
+
+```
+实时同步任务不需要配置调度策略（无需调用 save_task_configuration）。
+直接使用 publish_task 提交任务：
+- task_id: 任务 ID
+- task_version: 当前版本号（通过 get_task_detail 获取）
+
+提交后任务即开始持续运行。
+```
+
+> **重要**：实时同步任务不支持开发状态下的测试运行，提交即为正式部署。
+
+### 步骤 8：运维监控
+
+```
+提交后在运维中心管理实时同步任务：
+
+查看任务状态：get_task_detail
+查看运行记录：list_task_run（注意实时任务为持续运行，不同于离线任务的周期实例）
+
+Studio UI 中可进行：
+- 启动/停止任务
+- 查看同步延迟和吞吐量
+- 查看错误日志
+```
+
+---
+
+## 支持的数据源
+
+### 来源端
+
+| 数据源 | ds_type | 说明 |
+|--------|---------|------|
+| Kafka | 2 | 支持 JSON 消息解析（JSONPath 计算列） |
+| MySQL | 5 | CDC 变更捕获 |
+| PostgreSQL | 7 | CDC 变更捕获 |
+| SQL Server | 8 | CDC 变更捕获 |
+| Aurora MySQL | 39 | CDC 变更捕获 |
+| Aurora PostgreSQL | 40 | CDC 变更捕获 |
+| PolarDB MySQL | 19 | CDC 变更捕获 |
+| PolarDB PostgreSQL | 48 | CDC 变更捕获 |
+
+### 目标端
+
+| 数据源 | ds_type |
+|--------|---------|
+| Lakehouse | 1 |
+
+## 故障排除
+
+| 问题 | 排查方向 |
+|------|---------|
+| 任务创建失败 | 检查是否有可用的 Sync VCluster（`LH_show_object_list` 查看 VCLUSTERS，筛选 SYNC 类型） |
+| 源端连接失败 | 检查数据源配置中的连接信息、网络可达性、账号权限 |
+| Kafka 消费无数据 | 检查 Topic 名称是否正确、消费位点设置、Kafka 集群连通性 |
+| JSON 解析失败 | 检查 JSONPath 表达式是否正确、消息格式是否为合法 JSON |
+| 同步延迟增大 | 检查 Sync VCluster 资源是否充足、源端数据量是否突增 |
+| 目标表写入失败 | 检查目标表是否存在、字段类型是否兼容、权限是否充足 |
+| 任务异常停止 | 查看执行日志（`list_executions` + `get_execution_log`）排查具体错误 |
+
+## 注意事项
+
+### 运行模式
+
+- 实时同步任务为持续运行的流式任务，提交后即开始运行，无需配置调度
+- 不支持开发状态下的测试运行
+- 停止后需手动重新启动
+
+### Sync VCluster 要求
+
+- 实时同步任务（task_type=28）必须使用 Sync VCluster
+- 创建任务前需确认有可用的 Sync VCluster
+- 可通过 `LH_show_object_list`（object_type='VCLUSTERS'）查看，筛选 vcluster_type 包含 SYNC 的集群
+
+### Kafka 数据源特殊说明
+
+- 支持指定消费起始位点（earliest / latest / 指定 offset）
+- JSON 消息可通过 JSONPath 计算列解析嵌套字段
+- 默认字段包括：key、value、timestamp、partition、offset
+
+### 与多表实时同步的选择
+
+- 单表实时同步（本 Skill）：适合单张表/Topic 的精细化同步
+- 多表实时同步（`clickzetta-cdc-sync-pipeline`）：适合整库 CDC、多表批量实时同步
+- 如需同步整个数据库的所有表，建议使用多表实时同步
+
+---
+
+## cz-cli 替代路径
+
+> 仅在 cz-cli 可用且 MCP 不可用时使用本节。步骤编号与上方 MCP 路径对应。
+> 所有操作通过 `cz-cli agent run` 委托给内置 agent 完成，agent 内置完整的 Studio MCP 工具访问能力。
+
+### 单表实时同步（cz-cli 版）
+
+cz-cli agent 内置 Studio MCP 工具，可直接处理实时同步任务创建和配置：
+
+```bash
+# 步骤 1-7 合并：让 agent 完成完整的实时同步任务创建
+cz-cli agent run "创建实时同步任务（task_type=28），将数据源 <source_ds_name> 中 <schema>.<table>（或 Kafka topic <topic>）实时同步到 Lakehouse public schema，使用 Sync VCluster，任务名 rt_sync_<table>，放在 <folder_name> 文件夹下" \
+  --format a2a --dangerously-skip-permissions
+```
+
+对于需要精细控制的场景，可拆分步骤：
+
+```bash
+# 步骤 1：确认 Sync VCluster 可用
+cz-cli agent run "列出所有可用的 VCluster，筛选 vcluster_type 包含 SYNC 的集群，确认有可用的 Sync VCluster" \
+  --format a2a --dangerously-skip-permissions
+
+# 步骤 2：查找数据源
+cz-cli agent run "列出所有已配置的数据源，按类型过滤（Kafka: ds_type=2, MySQL: ds_type=5, PostgreSQL: ds_type=7, SQL Server: ds_type=8），记录源端和目标端 Lakehouse 数据源名称" \
+  --format a2a --dangerously-skip-permissions
+
+# 步骤 3（可选）：探查源端数据结构
+cz-cli agent run "查看数据源 <source_ds_name> 的命名空间列表，以及 <schema> 下的表/Topic 列表和字段结构" \
+  --format a2a --dangerously-skip-permissions
+
+# 步骤 4-5：创建并配置实时同步任务
+cz-cli agent run "创建实时同步任务（task_type=28），源端 datasource=<source_ds_name>，schema=<schema>，table=<table>（source_ds_type=<type>），目标 Lakehouse public.<table>，任务名 rt_sync_<table>" \
+  --format a2a --dangerously-skip-permissions
+
+# 步骤 7：提交部署
+cz-cli agent run "提交实时同步任务 rt_sync_<table>，使其开始持续运行" \
+  --format a2a --dangerously-skip-permissions
+```
+
+> **注意**：实时同步任务不需要配置调度策略，提交即开始持续运行。Kafka JSON 消息的计算列配置需在 Studio UI 中完成。
+
+---
+
+### 运维监控（cz-cli 版）
+
+```bash
+# 查看任务状态
+cz-cli agent run "查看实时同步任务 <task_name> 的运行状态和详细信息" \
+  --format a2a --dangerously-skip-permissions
+
+# 查看运行记录
+cz-cli agent run "查看实时同步任务 <task_name> 的最近运行记录" \
+  --format a2a --dangerously-skip-permissions
+```