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

package/bin/skills/clickzetta-monitoring/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: clickzetta-monitoring
+description: |
+  监控和分析 ClickZetta Lakehouse 作业运行状态、性能和资源使用情况，
+  以及通过 INFORMATION_SCHEMA 查询元数据（表、列、Schema、工作空间等）。
+  覆盖 SHOW JOBS 实时查看作业、information_schema.job_history 历史分析、
+  慢查询识别、集群负载分析、缓存命中率统计、失败作业排查、
+  information_schema.tables/columns/schemas 元数据查询等完整监控与治理工作流。
+  当用户说"查看作业"、"作业历史"、"SHOW JOBS"、"慢查询"、"查询性能"、
+  "集群负载"、"作业失败"、"查询失败"、"监控"、"job history"、
+  "information_schema"、"缓存命中率"、"查询耗时"、"作业状态"、
+  "元数据查询"、"查看所有表"、"表大小"、"列信息"、"资产盘点"时触发。
+  Keywords: monitoring, job status, performance, resource usage, SHOW JOBS, slow query
+---
+
+# ClickZetta 作业监控与分析
+
+阅读 [references/show-jobs.md](references/show-jobs.md) 了解 SHOW JOBS 语法。
+阅读 [references/job-history-analysis.md](references/job-history-analysis.md) 了解历史分析查询。
+
+---
+
+## 实时查看作业（SHOW JOBS）
+
+```sql
+-- 查看所有作业（最近7天）
+SHOW JOBS;
+
+-- 查看指定集群的作业
+SHOW JOBS IN VCLUSTER default_ap;
+
+-- 查看执行时间超过2分钟的慢查询
+SHOW JOBS WHERE execution_time > INTERVAL 2 MINUTE;
+
+-- 查看失败的作业
+SHOW JOBS WHERE status = 'FAILED';
+
+-- 限制返回数量
+SHOW JOBS IN VCLUSTER default_ap LIMIT 50;
+```
+
+---
+
+## 历史作业分析（information_schema）
+
+### 集群负载分析
+
+```sql
+SELECT
+    virtual_cluster,
+    COUNT(*) AS job_count,
+    AVG(execution_time) AS avg_seconds,
+    ROUND(SUM(CASE WHEN status = 'SUCCEED' THEN 1 ELSE 0 END) * 100.0 / COUNT(*), 2) AS success_rate
+FROM sys.information_schema.job_history
+WHERE start_time >= CURRENT_DATE() - INTERVAL 7 DAY
+GROUP BY virtual_cluster
+ORDER BY job_count DESC;
+```
+
+### 慢查询 TOP 20
+
+```sql
+SELECT job_id, virtual_cluster, execution_time, status, start_time
+FROM sys.information_schema.job_history
+WHERE start_time >= CURRENT_DATE() - INTERVAL 7 DAY
+ORDER BY execution_time DESC
+LIMIT 20;
+```
+
+### 失败作业统计
+
+```sql
+SELECT
+    virtual_cluster,
+    COUNT(*) AS failed_count,
+    DATE(start_time) AS date
+FROM sys.information_schema.job_history
+WHERE status = 'FAILED'
+  AND start_time >= CURRENT_DATE() - INTERVAL 7 DAY
+GROUP BY virtual_cluster, DATE(start_time)
+ORDER BY date DESC;
+```
+
+### 高峰期识别
+
+```sql
+SELECT
+    HOUR(start_time) AS hour_of_day,
+    COUNT(*) AS job_count,
+    AVG(execution_time) AS avg_execution_time
+FROM sys.information_schema.job_history
+WHERE start_time >= CURRENT_DATE() - INTERVAL 7 DAY
+GROUP BY HOUR(start_time)
+ORDER BY hour_of_day;
+```
+
+---
+
+## query_tag 标记与过滤
+
+给作业打标，便于按来源过滤：
+
+```sql
+-- 在 SQL 中设置 query_tag
+SET query_tag = 'etl_daily';
+SELECT * FROM orders;
+
+-- 按 query_tag 过滤作业历史
+SELECT job_id, execution_time, status
+FROM sys.information_schema.job_history
+WHERE start_time >= CURRENT_DATE() - INTERVAL 7 DAY
+  AND query_tag = 'etl_daily';
+```
+
+JDBC URL 中设置：
+```
+jdbc:clickzetta://instance.region.api.clickzetta.com/workspace?query_tag=my_app
+```
+
+---
+
+## 常见问题排查
+
+| 现象 | 排查方向 |
+|---|---|
+| 作业长时间"等待执行" | 集群资源不足，考虑扩容 VCluster |
+| 作业长时间"集群启动中" | VCluster 冷启动慢，联系技术支持 |
+| 大量失败作业 | 查看 job_id 详情，检查 SQL 语法或权限 |
+| 平均执行时间突然变长 | 检查数据量变化、索引状态、缓存命中率 |
+
+---
+
+## INFORMATION_SCHEMA 元数据查询
+
+除了 `job_history`，INFORMATION_SCHEMA 还提供丰富的元数据视图，用于资产盘点和治理。
+
+### 空间级视图（当前工作空间）
+
+```sql
+-- 查看当前空间下所有 Schema
+SELECT * FROM information_schema.schemas;
+
+-- 查看所有表及其大小、行数
+SELECT table_schema, table_name, table_type, row_count, bytes
+FROM information_schema.tables
+ORDER BY bytes DESC;
+
+-- 查看所有列的详细信息（字段名、类型、是否可空、注释）
+SELECT table_schema, table_name, column_name, data_type, is_nullable, comment
+FROM information_schema.columns
+WHERE table_schema = 'public';
+
+-- 查看排序列推荐
+SELECT * FROM information_schema.sortkey_candidates;
+```
+
+### 实例级视图（需要 instance_admin 权限，使用 sys 库）
+
+```sql
+-- 查看实例下所有工作空间
+SELECT * FROM sys.information_schema.workspaces;
+
+-- 查看实例下所有 Schema（跨工作空间）
+SELECT * FROM sys.information_schema.schemas;
+
+-- 查看实例用量（费用分析）
+SELECT * FROM sys.information_schema.instance_usage
+WHERE start_time >= CURRENT_DATE() - INTERVAL 7 DAY;
+```
+
+### 常用元数据分析场景
+
+```sql
+-- 找出最大的 10 张表
+SELECT table_schema, table_name, row_count, bytes
+FROM information_schema.tables
+WHERE table_type = 'TABLE'
+ORDER BY bytes DESC
+LIMIT 10;
+
+-- 找出没有注释的表
+SELECT table_schema, table_name
+FROM information_schema.tables
+WHERE comment IS NULL OR comment = '';
+
+-- 找出没有注释的字段
+SELECT table_schema, table_name, column_name
+FROM information_schema.columns
+WHERE (comment IS NULL OR comment = '')
+  AND table_schema NOT IN ('information_schema');
+
+-- 统计各 Schema 下的表数量和总存储
+SELECT table_schema,
+       COUNT(*) AS table_count,
+       SUM(bytes) AS total_storage
+FROM information_schema.tables
+GROUP BY table_schema
+ORDER BY total_storage DESC;
+```

package/bin/skills/clickzetta-monitoring/eval_cases.jsonl

@@ -0,0 +1,5 @@
+{"case_id":"001","type":"should_call","user_input":"SHOW JOBS 的语法是什么？怎么过滤特定状态的作业？","expected_skill":"clickzetta-monitoring","expected_output_contains":["SHOW JOBS"]}
+{"case_id":"002","type":"should_call","user_input":"怎么查询失败的作业？用什么 SQL？","expected_skill":"clickzetta-monitoring","expected_output_contains":["FAILED"]}
+{"case_id":"003","type":"should_call","user_input":"过去 7 天各集群的作业执行情况怎么查？","expected_skill":"clickzetta-monitoring","expected_output_contains":["job_history","virtual_cluster"]}
+{"case_id":"004","type":"should_call","user_input":"怎么查看慢查询？执行超过 2 分钟的作业有哪些？","expected_skill":"clickzetta-monitoring","expected_output_contains":["execution_time"]}
+{"case_id":"005","type":"should_call","user_input":"怎么通过 information_schema 查看所有表的大小和行数？","expected_skill":"clickzetta-monitoring","expected_output_contains":["information_schema","tables"]}

package/bin/skills/clickzetta-monitoring/references/job-history-analysis.md

@@ -0,0 +1,97 @@
+# information_schema 作业历史分析参考
+
+> 来源：https://www.yunqi.tech/documents/job_history_analysis_with_information_schema
+
+## 数据源
+
+表名：`sys.information_schema.job_history`
+
+### 关键字段
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| workspace_name | String | 工作空间名称 |
+| virtual_cluster | String | 计算集群名称 |
+| job_id | String | 作业唯一标识 |
+| execution_time | Float | 执行时长（秒） |
+| start_time | Timestamp | 开始时间 |
+| status | String | 状态（SUCCEED/FAILED/CANCELLED/...） |
+| input_tables | String | 输入表（JSON 格式） |
+| input_bytes | String | 读取字节数 |
+| cache_hit | String | 缓存命中字节数 |
+
+---
+
+## 常用分析查询
+
+### 1. 集群负载分析（近 30 天）
+
+```sql
+SELECT
+    virtual_cluster,
+    COUNT(*) AS job_count,
+    SUM(execution_time) AS total_execution_time,
+    AVG(execution_time) AS avg_execution_time,
+    ROUND(SUM(CASE WHEN status = 'SUCCEED' THEN 1 ELSE 0 END) * 100.0 / COUNT(*), 2) AS success_rate
+FROM sys.information_schema.job_history
+WHERE start_time >= CURRENT_DATE() - INTERVAL 30 DAY
+GROUP BY virtual_cluster
+ORDER BY total_execution_time DESC;
+```
+
+### 2. 慢查询分析（执行时间 TOP 20）
+
+```sql
+SELECT
+    job_id,
+    virtual_cluster,
+    execution_time,
+    status,
+    start_time
+FROM sys.information_schema.job_history
+WHERE start_time >= CURRENT_DATE() - INTERVAL 7 DAY
+ORDER BY execution_time DESC
+LIMIT 20;
+```
+
+### 3. 失败作业分析
+
+```sql
+SELECT
+    virtual_cluster,
+    COUNT(*) AS failed_count,
+    DATE(start_time) AS date
+FROM sys.information_schema.job_history
+WHERE status = 'FAILED'
+  AND start_time >= CURRENT_DATE() - INTERVAL 7 DAY
+GROUP BY virtual_cluster, DATE(start_time)
+ORDER BY date DESC, failed_count DESC;
+```
+
+### 4. 缓存命中率分析
+
+```sql
+SELECT
+    virtual_cluster,
+    SUM(CAST(input_bytes AS BIGINT)) AS total_input_bytes,
+    SUM(CAST(cache_hit AS BIGINT)) AS total_cache_hit,
+    ROUND(SUM(CAST(cache_hit AS BIGINT)) * 100.0 /
+          NULLIF(SUM(CAST(input_bytes AS BIGINT)), 0), 2) AS cache_hit_rate
+FROM sys.information_schema.job_history
+WHERE start_time >= CURRENT_DATE() - INTERVAL 7 DAY
+  AND input_bytes IS NOT NULL
+GROUP BY virtual_cluster;
+```
+
+### 5. 按小时统计作业量（识别高峰期）
+
+```sql
+SELECT
+    HOUR(start_time) AS hour_of_day,
+    COUNT(*) AS job_count,
+    AVG(execution_time) AS avg_execution_time
+FROM sys.information_schema.job_history
+WHERE start_time >= CURRENT_DATE() - INTERVAL 7 DAY
+GROUP BY HOUR(start_time)
+ORDER BY hour_of_day;
+```

package/bin/skills/clickzetta-monitoring/references/show-jobs.md

@@ -0,0 +1,48 @@
+# 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
+-- 查看所有作业（最近7天）
+SHOW JOBS;
+
+-- 查看指定集群的作业
+SHOW JOBS IN VCLUSTER default_ap;
+
+-- 查看执行时间超过2分钟的作业
+SHOW JOBS IN VCLUSTER default_ap WHERE execution_time > INTERVAL 2 MINUTE;
+
+-- 限制返回100条
+SHOW JOBS LIMIT 100;
+
+-- 按 job_id 模糊匹配
+SHOW JOBS LIKE '2024%';
+```
+
+## 作业状态说明
+
+| 状态 | 含义 |
+|---|---|
+| 初始化 | SQL 编译优化阶段 |
+| 集群启动中 | 等待 VCluster 启动 |
+| 等待执行 | 排队等待资源 |
+| 正在执行 | 正在处理数据 |
+| 执行成功 | 运行结束 |
+| 执行失败 | 运行失败 |

package/bin/skills/clickzetta-overview/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: clickzetta-overview
+description: |
+  ClickZetta Lakehouse 产品全貌：核心概念、对象模型、架构设计、Studio 功能介绍。
+  覆盖：账户/实例/工作空间/Schema 对象层级，Workspace 与 Database/Catalog 的对应关系，
+  VCluster 三种类型与 CRU 计费，Dynamic Table 增量刷新机制，Table Stream CDC，
+  三层缓存体系，Pipe 持续导入，Synonym 跨 Schema 别名，权限体系（RBAC/ACL），
+  与 Snowflake/Databricks 的关键差异对比，存算分离架构，
+  品牌关系（ClickZetta = 云器 = Singdata）及各环境服务地址，
+  Studio 六大模块（数据开发 IDE、任务调度、数据集成、数据目录、数据质量、运维监控）。
+  当用户说"工作空间是什么"、"Schema 和 Database 什么关系"、"Catalog 是什么"、
+  "VCluster 是什么"、"CRU 是什么"、"内部表和外部表区别"、"Lakehouse 架构"、
+  "对象层级"、"权限体系"、"和 Snowflake 概念对比"、"和 Databricks 概念对比"、
+  "存算分离"、"云器是什么"、"Singdata 是什么"、"ClickZetta 和云器什么关系"、
+  "Studio 是什么"、"Studio 有哪些功能"、"任务调度怎么用"、"数据集成怎么用"、
+  "数据目录"、"数据质量"、"运维监控"时触发。
+  不适合：具体 SQL 语法（用 sql-syntax-guide）、具体元数据查询（用 metadata）、
+  具体数据导入操作（用 pipeline skill）、具体权限操作（用 access-control）。
+  Keywords: concepts, architecture, workspace, schema, VCluster, Studio, overview, object model
+---
+
+# ClickZetta Lakehouse 产品全貌
+
+## 参考文档
+
+| 文档 | 内容 |
+|------|------|
+| [references/object-model.md](references/object-model.md) | 对象层级、概念对比、独特设计详解 |
+| [references/brands-and-endpoints.md](references/brands-and-endpoints.md) | 品牌关系、各环境服务地址 |
+| [references/studio-modules.md](references/studio-modules.md) | Studio 六大模块详细功能 |
+
+---
+
+## 对象层级总览
+
+```
+账户 (Account)
+└── 服务实例 (Instance)          ← 资源隔离单元
+    └── 工作空间 (Workspace)      ← ≈ Snowflake Database / Databricks Catalog
+        ├── Schema               ← 命名空间，权限边界
+        │   ├── 内部表 / 外部表 / 视图 / 动态表 / 物化视图
+        │   ├── Volume / Table Stream / Pipe / 索引 / Synonym
+        │   └── 函数 / External Function
+        ├── Share / Connection / External Catalog
+        └── VCluster（计算集群）
+```
+
+---
+
+## 核心概念速查
+
+| 概念 | 说明 |
+|------|------|
+| CRU | 跨云统一算力单位，按 CRU×时 计费，集群停止不计费 |
+| VCluster | 三种类型：通用型(GP)、分析型(AP)、同步型(INTEGRATION) |
+| Dynamic Table | 声明式增量计算，基于 CBO 自适应增量/全量，最小 1 分钟刷新 |
+| Table Stream | CDC 变更捕获对象，需先开启 change_tracking |
+| Pipe | 持续导入对象（Kafka/OSS），每个 Pipe 对应独立 Volume |
+| Synonym | 跨 Schema 别名，无需复制数据 |
+| 三层缓存 | 结果缓存 + 元数据缓存 + 本地磁盘缓存（AP 支持 PRELOAD） |
+
+---
+
+## 与 Snowflake/Databricks 关键差异
+
+| ClickZetta | Snowflake | Databricks | 差异点 |
+|---|---|---|---|
+| Workspace | Database | Catalog | 一个账户可多实例多云 |
+| VCluster (3 类型) | Warehouse | SQL Warehouse | GP/AP/INTEGRATION 分离 |
+| Studio（内置） | 需第三方 | 需第三方 | 内置调度/集成/质量/目录 |
+| Dynamic Table (CBO) | Dynamic Table | Streaming Table | 基于 CBO 非流式 |
+| Synonym | — | — | ClickZetta 特有 |
+
+---
+
+## Studio 六大模块
+
+| 模块 | 核心能力 |
+|------|---------|
+| 数据开发 | Web IDE，支持 SQL/Python/Shell/JDBC/动态表/同步任务 |
+| 任务调度 | Cron 调度 + DAG 编排 + 任务组 + 补数据 + 参数变量 |
+| 数据集成 | 30+ 数据源无代码同步（离线/实时/CDC） |
+| 数据目录 | 全局搜索、表详情、数据血缘、数据预览 |
+| 数据质量 | 6 维度规则（完整性/唯一性/一致性/准确性/有效性/及时性） |
+| 运维监控 | 任务实例运维 + 告警规则 + 飞书/企微通知 |
+
+---
+
+## 品牌关系
+
+ClickZetta（技术品牌）= 云器（国内品牌）= Singdata（国际品牌）
+
+详见 [references/brands-and-endpoints.md](references/brands-and-endpoints.md) 获取各环境服务地址。
+
+---
+
+## 存储架构
+
+- 存算分离：VCluster 停止不产生计算费用
+- 开放格式：内部表基于 Apache Iceberg
+- 多云多地域：阿里云/腾讯云/AWS
+- 私有存储（BYOS）：支持自有 OSS/S3/COS

package/bin/skills/clickzetta-overview/eval_cases.jsonl

@@ -0,0 +1,5 @@
+{"case_id":"001","type":"should_call","user_input":"ClickZetta 的对象层级是什么？工作空间和 Schema 什么关系？","expected_skill":"clickzetta-overview","expected_output_contains":["工作空间","Schema"]}
+{"case_id":"002","type":"should_call","user_input":"VCluster 有哪几种类型？CRU 是什么计费单位？","expected_skill":"clickzetta-overview","expected_output_contains":["通用","分析","CRU"]}
+{"case_id":"003","type":"should_call","user_input":"云器和 ClickZetta 和 Singdata 是什么关系？","expected_skill":"clickzetta-overview","expected_output_contains":["云器","ClickZetta"]}
+{"case_id":"004","type":"should_call","user_input":"Studio 有哪些功能模块？任务调度怎么配置？","expected_skill":"clickzetta-overview","expected_output_contains":["Studio","任务"]}
+{"case_id":"005","type":"should_call","user_input":"ClickZetta 和 Snowflake 在概念上有什么关键差异？","expected_skill":"clickzetta-overview","expected_output_contains":["Snowflake"]}

package/bin/skills/clickzetta-overview/references/brands-and-endpoints.md

@@ -0,0 +1,79 @@
+# ClickZetta 品牌关系与服务地址
+
+## 品牌关系
+
+ClickZetta 是技术品牌名，同一产品在不同市场使用不同品牌：
+
+| 品牌 | 市场 | 官网 | 文档 |
+|---|---|---|---|
+| **云器（Yunqi）** | 国内 | www.yunqi.tech | www.yunqi.tech/documents |
+| **Singdata** | 国际 | www.singdata.com | www.singdata.com/documents |
+| **ClickZetta** | 技术品牌（通用） | — | — |
+
+> **云器 Lakehouse = ClickZetta Lakehouse = Singdata Lakehouse**，三者指同一产品。
+> 用户提到"云器"、"Singdata"、"ClickZetta"时，均指同一 Lakehouse 平台。
+
+---
+
+## 国内（云器）服务地址
+
+控制台：`https://<instance_name>.app.clickzetta.com`
+
+JDBC URL 格式：`jdbc:clickzetta://<instance_name>.<region_code>.api.clickzetta.com/<workspace>`
+
+| 云服务商 | 区域 | Region Code | API 地址 |
+|---|---|---|---|
+| 阿里云 | 上海 | `cn-shanghai-alicloud` | `<instance>.cn-shanghai-alicloud.api.clickzetta.com` |
+| 阿里云 | 杭州 | `cn-hangzhou-alicloud` | `<instance>.cn-hangzhou-alicloud.api.clickzetta.com` |
+| 阿里云 | 北京 | `cn-beijing-alicloud` | `<instance>.cn-beijing-alicloud.api.clickzetta.com` |
+| 腾讯云 | 上海 | `cn-shanghai-tencentcloud` | `<instance>.cn-shanghai-tencentcloud.api.clickzetta.com` |
+| 华为云 | 上海 | `cn-shanghai-huaweicloud` | `<instance>.cn-shanghai-huaweicloud.api.clickzetta.com` |
+
+---
+
+## 国际（Singdata）服务地址
+
+账户控制台：`https://accounts.app.singdata.com` 或 `https://<account_name>.accounts.app.singdata.com`
+
+实例控制台：`https://<instance_name>.app.singdata.com`
+
+工作空间列表：`https://<instance_name>.app.lakehouse.singdata.com/workspace`
+
+JDBC URL 格式：`jdbc:clickzetta://<instance_name>.<region_code>.api.singdata.com/<workspace>`
+
+Streaming API Host：`<instance_name>.streamingapi.singdata.com`
+
+| 云服务商 | 区域 | Region Code | API 地址 |
+|---|---|---|---|
+| 阿里云 | 新加坡 | `ap-southeast-1-alicloud` | `<instance>.ap-southeast-1-alicloud.api.singdata.com` |
+| Amazon Web Services | 新加坡 | `ap-southeast-1-aws` | `<instance>.ap-southeast-1-aws.api.singdata.com` |
+
+---
+
+## SDK / 连接参数中的地址格式
+
+Python SDK（`clickzetta-connector-python`）的 `service` 参数填 API 地址（不含 `jdbc:clickzetta://` 前缀和实例名）：
+
+```python
+# 国内（云器）
+conn = connect(service='cn-shanghai-alicloud.api.clickzetta.com', instance='your_instance', ...)
+
+# 国际（Singdata）
+conn = connect(service='ap-southeast-1-alicloud.api.singdata.com', instance='your_instance', ...)
+```
+
+Java SDK（`clickzetta-java`）的 `.service()` 参数同理：
+
+```java
+// 国内（云器）
+ClickZettaClient.newBuilder()
+    .service("cn-shanghai-alicloud.api.clickzetta.com")
+    .instance("your_instance")
+    ...
+
+// 国际（Singdata）
+ClickZettaClient.newBuilder()
+    .service("ap-southeast-1-alicloud.api.singdata.com")
+    .instance("your_instance")
+    ...
+```