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

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

@@ -0,0 +1,5 @@
+{"case_id":"001","type":"should_call","user_input":"怎么用 READ_KAFKA Pipe 把 Kafka topic 数据持续导入 Lakehouse？","expected_skill":"clickzetta-kafka-ingest-pipeline","expected_output_contains":["READ_KAFKA","PIPE"]}
+{"case_id":"002","type":"should_call","user_input":"Kafka 消息是多层嵌套 JSON，怎么解析导入？","expected_skill":"clickzetta-kafka-ingest-pipeline","expected_output_contains":["JSON","READ_KAFKA"]}
+{"case_id":"003","type":"should_call","user_input":"Kafka Pipe 延迟很高怎么排查？怎么监控 offsetLag？","expected_skill":"clickzetta-kafka-ingest-pipeline","expected_output_contains":["pipe_latency","offsetLag"]}
+{"case_id":"004","type":"should_call","user_input":"Kafka 需要 SASL 认证，Pipe 怎么配置？","expected_skill":"clickzetta-kafka-ingest-pipeline","expected_output_contains":["SASL"]}
+{"case_id":"005","type":"should_call","user_input":"Kafka 外部表和 READ_KAFKA Pipe 有什么区别？该选哪个？","expected_skill":"clickzetta-kafka-ingest-pipeline","expected_output_contains":["外部表","READ_KAFKA","Table Stream"]}

package/bin/skills/clickzetta-kafka-ingest-pipeline/references/kafka-pipe-syntax.md

@@ -0,0 +1,324 @@
+# Kafka Pipe SQL 语法参考
+
+> 来源：https://www.yunqi.tech/documents/pipe-kafka 和 https://www.yunqi.tech/documents/pipe-kafka-bestpractice-1
+
+> **⚠️ ClickZetta READ_KAFKA 使用位置参数（positional parameters）**
+> - ❌ 不支持 `=>` 命名参数语法（如 `KAFKA_BROKER => 'host:port'`）
+> - ❌ 不支持 `TABLE(READ_KAFKA(...))` 包装
+> - ✅ 正确：`FROM read_kafka('broker', 'topic', '', 'group', '', '', '', '', 'raw', 'raw', 0, MAP(...))`
+
+## CREATE PIPE（READ_KAFKA 方式）
+
+```sql
+CREATE [ OR REPLACE ] PIPE <pipe_name>
+  VIRTUAL_CLUSTER = '<vcluster_name>'
+  [ BATCH_INTERVAL_IN_SECONDS = '<seconds>' ]
+  [ BATCH_SIZE_PER_KAFKA_PARTITION = '<count>' ]
+  [ MAX_SKIP_BATCH_COUNT_ON_ERROR = '<count>' ]
+  [ INITIAL_DELAY_IN_SECONDS = '<seconds>' ]
+  [ RESET_KAFKA_GROUP_OFFSETS = '<offset_value>' ]
+  [ COPY_JOB_HINT = '<json>' ]
+AS
+COPY INTO <target_table> FROM (
+  SELECT <expr> [, ...]
+  FROM read_kafka(
+    '<bootstrap_servers>',   -- 位置 1：Kafka 集群地址（必填）
+    '<topic_name>',          -- 位置 2：Topic 名称（必填）
+    '',                      -- 位置 3：Topic pattern（保留，填空字符串）
+    '<group_id>',            -- 位置 4：消费者组 ID（必填）
+    '',                      -- 位置 5：starting_offsets（Pipe 中留空）
+    '',                      -- 位置 6：ending_offsets（Pipe 中留空）
+    '',                      -- 位置 7：starting_timestamp（Pipe 中留空）
+    '',                      -- 位置 8：ending_timestamp（Pipe 中留空）
+    'raw',                   -- 位置 9：key 格式（目前只支持 raw）
+    'raw',                   -- 位置 10：value 格式（目前只支持 raw）
+    0,                       -- 位置 11：max_errors
+    MAP(<kafka_config>)      -- 位置 12：Kafka 配置参数
+  )
+);
+```
+
+### Pipe 参数说明
+
+| 参数 | 必填 | 默认值 | 说明 |
+|------|------|--------|------|
+| `VIRTUAL_CLUSTER` | 是 | — | 执行 Pipe 任务的计算集群 |
+| `BATCH_INTERVAL_IN_SECONDS` | 否 | 60 | 批处理间隔（秒），即数据新鲜度 |
+| `BATCH_SIZE_PER_KAFKA_PARTITION` | 否 | 500000 | 每个 Kafka 分区每批最大消息数 |
+| `MAX_SKIP_BATCH_COUNT_ON_ERROR` | 否 | 30 | 出错时跳过批次的最大重试次数 |
+| `INITIAL_DELAY_IN_SECONDS` | 否 | 0 | 首个作业调度延迟 |
+| `RESET_KAFKA_GROUP_OFFSETS` | 否 | — | 启动时消费位点（仅创建时生效） |
+| `COPY_JOB_HINT` | 否 | — | JSON 格式的作业参数 |
+
+### RESET_KAFKA_GROUP_OFFSETS 可选值
+
+| 值 | 说明 |
+|----|------|
+| `'none'` | 无操作，使用 Kafka `auto.offset.reset`（默认 latest） |
+| `'valid'` | 检查当前位点是否过期，将过期分区重置到 earliest |
+| `'earliest'` | 重置到最早位点 |
+| `'latest'` | 重置到最新位点 |
+| `'<毫秒时间戳>'` | 重置到指定时间戳对应位点（如 `'1737789688000'`） |
+
+### READ_KAFKA 参数（在 Pipe 中 vs 独立使用）
+
+| 特性 | 独立使用 read_kafka | 在 Pipe 中使用 |
+|------|-------------------|---------------|
+| 消费者组 | 临时，执行完即销毁 | 持久，保持消费位置 |
+| 位置管理 | 在 MAP 中设置 `kafka.auto.offset.reset` | Pipe 自动管理，位置参数**必须留空** |
+| 执行方式 | 一次性查询 | 持续调度执行 |
+| 默认起始位置 | latest（可在 MAP 中改为 earliest） | latest（由 RESET_KAFKA_GROUP_OFFSETS 控制） |
+
+### MAP 配置参数
+
+| 参数 | 说明 |
+|------|------|
+| `kafka.security.protocol` | 安全协议：`PLAINTEXT` 或 `SASL_PLAINTEXT` |
+| `kafka.sasl.mechanism` | SASL 机制：`PLAIN` |
+| `kafka.sasl.username` | SASL 用户名 |
+| `kafka.sasl.password` | SASL 密码 |
+| `kafka.auto.offset.reset` | 独立探查时的起始位点（`earliest` / `latest`） |
+| `cz.kafka.fetch.retry.enable` | 启用 fetch 重试（`true`/`false`） |
+| `cz.kafka.fetch.retry.times` | 重试次数 |
+| `cz.kafka.fetch.retry.intervalMs` | 重试间隔（毫秒） |
+
+### JSON 字段提取语法
+
+```sql
+-- key 和 value 都是 binary 类型，需要先转换
+value::string                                    -- 转为字符串
+parse_json(value::string)                        -- 解析为 JSON 对象
+parse_json(value::string)['field']::TYPE         -- 提取顶层字段
+parse_json(value::string)['nested']['key']::TYPE -- 提取嵌套字段
+
+-- 推荐模式：在子查询中先 parse_json，外层直接用 j['field']
+SELECT j['order_id']::STRING, j['amount']::DECIMAL(10,2)
+FROM (
+  SELECT parse_json(value::string) AS j
+  FROM read_kafka(...)
+)
+```
+
+### 完整示例
+
+```sql
+-- 无认证 Kafka Pipe
+CREATE PIPE kafka_orders_pipe
+  VIRTUAL_CLUSTER = 'default'
+  BATCH_INTERVAL_IN_SECONDS = '60'
+AS
+COPY INTO ods.orders FROM (
+  SELECT
+    j['order_id']::STRING AS order_id,
+    j['user_id']::STRING AS user_id,
+    j['amount']::DECIMAL(10,2) AS amount,
+    CAST(`timestamp` AS TIMESTAMP) AS kafka_ts
+  FROM (
+    SELECT `timestamp`, parse_json(value::string) AS j
+    FROM read_kafka(
+      'kafka.example.com:9092',
+      'orders',
+      '',
+      'lakehouse_orders',
+      '', '', '', '',
+      'raw', 'raw', 0,
+      MAP('kafka.security.protocol', 'PLAINTEXT')
+    )
+  )
+);
+
+-- SASL 认证 + 指定时间点消费
+CREATE PIPE kafka_secure_pipe
+  VIRTUAL_CLUSTER = 'pipe_vc'
+  BATCH_INTERVAL_IN_SECONDS = '60'
+  RESET_KAFKA_GROUP_OFFSETS = '1737789688000'
+AS
+COPY INTO ods.secure_events FROM (
+  SELECT
+    j['id']::STRING AS event_id,
+    j['payload']::STRING AS payload,
+    CAST(`timestamp` AS TIMESTAMP) AS kafka_ts
+  FROM (
+    SELECT `timestamp`, parse_json(value::string) AS j
+    FROM read_kafka(
+      'kafka.example.com:9092',
+      'secure_events',
+      '',
+      'cz_secure',
+      '', '', '', '',
+      'raw', 'raw', 0,
+      MAP(
+        'kafka.security.protocol', 'SASL_PLAINTEXT',
+        'kafka.sasl.mechanism', 'PLAIN',
+        'kafka.sasl.username', 'my_user',
+        'kafka.sasl.password', 'my_password'
+      )
+    )
+  )
+);
+```
+
+---
+
+## 独立探查（验证连接和数据格式）
+
+```sql
+-- 无认证
+SELECT value::string
+FROM read_kafka(
+  'kafka.example.com:9092',
+  'orders',
+  '',
+  'test_explore',
+  '', '', '', '',
+  'raw', 'raw', 0,
+  MAP('kafka.security.protocol', 'PLAINTEXT', 'kafka.auto.offset.reset', 'earliest')
+)
+LIMIT 10;
+
+-- SASL 认证
+SELECT value::string
+FROM read_kafka(
+  'kafka.example.com:9092',
+  'orders',
+  '',
+  'test_explore',
+  '', '', '', '',
+  'raw', 'raw', 0,
+  MAP(
+    'kafka.security.protocol', 'SASL_PLAINTEXT',
+    'kafka.sasl.mechanism', 'PLAIN',
+    'kafka.sasl.username', 'my_user',
+    'kafka.sasl.password', 'my_password',
+    'kafka.auto.offset.reset', 'earliest'
+  )
+)
+LIMIT 10;
+```
+
+---
+
+## CREATE PIPE（Kafka 外部表 + Table Stream 方式）
+
+### 步骤 1：创建 Kafka Storage Connection
+
+```sql
+CREATE STORAGE CONNECTION IF NOT EXISTS <conn_name>
+  TYPE KAFKA
+  BOOTSTRAP_SERVERS = ['<host1>:<port1>', '<host2>:<port2>']
+  SECURITY_PROTOCOL = 'PLAINTEXT';
+```
+
+### 步骤 2：创建 Kafka 外部表
+
+```sql
+-- ⚠️ 必须显式指定列定义（不能省略）
+-- ⚠️ offset 是保留字，必须用反引号转义
+CREATE EXTERNAL TABLE <ext_table_name> (
+  topic STRING,
+  partition INT,
+  `offset` BIGINT,
+  `timestamp` TIMESTAMP,
+  timestamp_type STRING,
+  headers STRING,
+  key BINARY,
+  value BINARY
+)
+USING KAFKA
+OPTIONS (
+  'group_id' = '<consumer_group>',
+  'topics' = '<topic_name>',
+  'starting_offset' = '<earliest | latest>'
+)
+CONNECTION <conn_name>;
+```
+
+> **注意**：
+> - 列定义是**必须的**，省略会报错 `failed to detect columns`
+> - `offset` 和 `timestamp` 是保留字，需要反引号转义
+> - 删除外部表用 `DROP TABLE`（不是 `DROP EXTERNAL TABLE`）
+
+### 步骤 3：创建 Table Stream
+
+```sql
+CREATE TABLE STREAM <stream_name>
+  ON TABLE <ext_table_name>
+  WITH PROPERTIES ('TABLE_STREAM_MODE' = 'APPEND_ONLY');
+```
+
+### 步骤 4：创建 Pipe
+
+```sql
+CREATE PIPE <pipe_name>
+  VIRTUAL_CLUSTER = '<vcluster_name>'
+  BATCH_INTERVAL_IN_SECONDS = '60'
+AS
+COPY INTO <target_table>
+SELECT <expr> [, ...]
+FROM <stream_name>;
+```
+
+---
+
+## ALTER PIPE
+
+```sql
+-- 暂停
+ALTER PIPE <pipe_name> SET PIPE_EXECUTION_PAUSED = true;
+
+-- 恢复
+ALTER PIPE <pipe_name> SET PIPE_EXECUTION_PAUSED = false;
+
+-- 修改 VCluster
+ALTER PIPE <pipe_name> SET VIRTUAL_CLUSTER = 'new_vc';
+
+-- 修改 COPY_JOB_HINT
+ALTER PIPE <pipe_name> SET COPY_JOB_HINT = '{"cz.sql.split.kafka.strategy":"size","cz.mapper.kafka.message.size":"200000"}';
+```
+
+> ⚠️ **ALTER PIPE 支持的属性**：
+> - ✅ `PIPE_EXECUTION_PAUSED`
+> - ✅ `VIRTUAL_CLUSTER`
+> - ✅ `COPY_JOB_HINT`
+> - ❌ `BATCH_INTERVAL_IN_SECONDS`（不支持，需删除重建）
+> - ❌ `BATCH_SIZE_PER_KAFKA_PARTITION`（不支持，需删除重建）
+>
+> 不支持修改 COPY/INSERT 语句逻辑，需删除 Pipe 后重建。
+> 修改 `COPY_JOB_HINT` 会覆盖所有已有 hints，需一次性设置全部参数。
+
+---
+
+## 监控
+
+```sql
+-- 查看 Pipe 详情（含延迟信息 pipe_latency）
+DESC PIPE EXTENDED <pipe_name>;
+
+-- 查看所有 Pipe
+SHOW PIPES;
+
+-- 查看加载历史
+SELECT * FROM load_history('<schema>.<table>')
+ORDER BY last_load_time DESC LIMIT 20;
+
+-- 通过 query_tag 查看 Pipe 作业
+-- 格式：pipe.<workspace_name>.<schema_name>.<pipe_name>
+SHOW JOBS WHERE query_tag = 'pipe.my_workspace.ods.kafka_orders_pipe';
+```
+
+---
+
+## DROP PIPE
+
+```sql
+DROP PIPE [ IF EXISTS ] <pipe_name>;
+```
+
+## 参考文档
+
+- [Pipe 简介](https://www.yunqi.tech/documents/pipe-summary)
+- [借助 read_kafka 函数持续导入](https://www.yunqi.tech/documents/pipe-kafka)
+- [借助 Kafka 外表 Table Stream 持续导入](https://www.yunqi.tech/documents/pipe-kafka-table-stream)
+- [最佳实践：使用 Pipe 高效接入 Kafka 数据](https://www.yunqi.tech/documents/pipe-kafka-bestpractice-1)
+- [Kafka 外部表](https://www.yunqi.tech/documents/kafka-external-table)
+- [Kafka Storage Connection](https://www.yunqi.tech/documents/Kafka_connection)

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 启动 |
+| 等待执行 | 排队等待资源 |
+| 正在执行 | 正在处理数据 |
+| 执行成功 | 运行结束 |
+| 执行失败 | 运行失败 |