@clickzetta/cz-cli-darwin-arm64 0.3.81 → 0.3.84

package/bin/skills/clickzetta-pipeline-review/SKILL.md

@@ -0,0 +1,377 @@
+---
+name: clickzetta-pipeline-review
+description: |
+  对 ClickZetta Lakehouse 数据管道进行全面 Review 与诊断。从任意入口（任务名/schema/表名/
+  业务域关键词）出发，自主发现管道涉及的全部对象（Studio 任务、Lakehouse 表、管道对象、
+  运行记录），识别调度依赖缺失、DDL 幂等问题、分层跳层、DT 反模式等常见问题，
+  给出优先级排序的修复建议并执行。
+  当用户说"Review 管道"、"检查数据管道"、"管道诊断"、"管道有问题"、"任务跑失败了"、
+  "数据不对"、"管道 Review"、"pipeline review"、"检查 ETL"、"管道健康检查"、
+  "数据链路检查"、"管道全貌"、"管道梳理"时触发。
+  Keywords: pipeline review, diagnosis, task dependency, data lineage, DT health, pipeline discovery
+---
+
+# ClickZetta 数据管道 Review 指南
+
+## 向导：收集必要信息
+
+收到 Review 请求后，**不要立即开始探索**。先通过向导收集必要信息，再启动五阶段流程。
+
+### 第 0 步：信息收集（必须完成，不得跳过）
+
+优先使用交互式问答工具（如 `question`）收集以下信息并弹出选项菜单；若无此类工具，则用文字一次性列出所有问题：
+
+```
+question({
+  questions: [
+    {
+      question: "Review 范围？",
+      options: [
+        { label: "全量 Review", description: "发现所有问题，给出完整报告" },
+        { label: "专项诊断", description: "只看某类问题，如任务依赖、DT 刷新失败、数据不一致" },
+        { label: "快速健康检查", description: "只看 P0 问题，5 分钟内出结论" }
+      ]
+    },
+    {
+      question: "执行权限？",
+      options: [
+        { label: "可读写", description: "可以执行修复操作（推荐）" },
+        { label: "只读", description: "只能查，输出报告不执行修复" }
+      ]
+    }
+  ]
+})
+```
+
+管道入口（业务域/任务名/schema/表名）和已知症状可在用户回答后追问，或从上下文推断。
+
+### 根据回答调整策略
+
+| Review 范围 | 执行权限 | 策略 |
+|---|---|---|
+| 全量 Review | 可读写 | 走完五阶段，发现问题后询问是否执行修复 |
+| 全量 Review | 只读 | 走完五阶段，输出问题报告，不执行修复 |
+| 专项诊断 | 任意 | 只执行对应阶段的检查项，跳过无关步骤 |
+| 快速健康检查 | 任意 | 只检查 P0 问题（依赖缺失、DT 持续失败），5 分钟内出结论 |
+
+**如果用户已经在请求中提供了足够信息（如"帮我 Review shenyu_gateway 管道，全量 Review，可以修复"），直接进入第一阶段，不再重复询问。**
+
+---
+
+## 工作模式：五阶段 Review 流程
+
+收集到必要信息后，按以下五阶段执行：
+
+```
+发现 → 分析 → 识别问题 → 执行修复 → 验证
+```
+
+---
+
+## 第一阶段：发现（管道全貌探索）
+
+### 入口识别
+
+用户可能从任意层给出入口，从入口向上下游展开：
+
+| 用户给出的入口 | 展开方向 |
+|---|---|
+| 业务域关键词（如"shenyu_gateway"） | 同时搜索 Studio 任务和 Lakehouse schema |
+| Studio 任务名/目录 | 读任务脚本 → 找涉及的表 → 找上下游任务 |
+| Lakehouse 表名/schema | 找写入该表的任务 → 找读取该表的 DT/任务 |
+| 管道对象（Pipe/DT/Stream） | 找源表和目标表 → 找关联任务 |
+| 错误信息/运行 ID | 先定位任务 → 再展开全貌 |
+
+### 探索四层
+
+**无论入口是什么，都要探索以下四层，缺一不可：**
+
+**层 1 — Studio 任务层**
+```bash
+# 按业务域关键词找任务目录
+cz-cli task list-folders
+
+# 列出目录下所有任务
+cz-cli task list --folder <folder>
+
+# 读每个任务的脚本和配置（重点看：task_type、cron_express、task_dependencies、edit_state）
+cz-cli task content <task_id>
+```
+
+**层 2 — Lakehouse 对象层**
+```sql
+-- 找相关 schema
+SHOW SCHEMAS;
+
+-- 列出各层表
+SHOW TABLES IN <ods_schema>;
+SHOW TABLES IN <dwd_schema>;
+SHOW TABLES IN <dws_schema>;
+SHOW TABLES IN <ads_schema>;
+
+-- 找 Dynamic Table
+SHOW TABLES IN <schema> WHERE is_dynamic;
+
+-- 找 Pipe
+SHOW PIPES;
+
+-- 找 Table Stream
+SHOW TABLE STREAMS;
+```
+
+**层 3 — 运行记录层**（配置是"应该怎样"，运行记录是"实际怎样"）
+```bash
+# 查每个关键任务的最近运行记录
+cz-cli runs list --task <task_name> --limit 10
+
+# 发现失败时查日志
+cz-cli runs logs <run_id>
+
+# 查运行统计（成功率、平均耗时）
+cz-cli runs stats --task <task_name>
+```
+
+**层 4 — 管道对象状态层**
+```sql
+-- Dynamic Table 刷新历史（每张 DT 都要查）
+SHOW DYNAMIC TABLE REFRESH HISTORY <schema>.<table> LIMIT 10;
+
+-- Pipe 状态
+DESC PIPE <pipe_name>;
+
+-- Table Stream 积压
+SELECT COUNT(*) FROM <stream_name>;
+```
+
+### 发现阶段输出
+
+完成四层探索后，向用户呈现管道全貌摘要：
+```
+管道全貌：
+- Studio 任务：N 个（列出名称、类型、状态、cron）
+- ODS 层：N 张表
+- DWD 层：N 张表
+- DWS/ADS 层：N 张 Dynamic Table
+- 管道对象：Pipe × N，Table Stream × N
+- 运行记录：最近 N 次，成功率 X%
+```
+
+---
+
+## 第二阶段：分析（深度读取）
+
+发现阶段只是"找到了什么"，分析阶段要"读懂内容"：
+
+```bash
+# 读每个任务的完整脚本
+cz-cli task content <task_id>
+
+# 重点关注：
+# - task_dependencies：是否配置了上下游依赖
+# - cron_express：调度时间是否合理
+# - edit_state：20=DRAFT，30=PUBLISHED
+# - task_type：SQL任务/同步任务/实时同步
+```
+
+**同步任务运行模式判断（不能只看单一字段）：**
+
+| 字段 | 不能单独判断 | 需要综合判断 |
+|---|---|---|
+| `readMode: BINLOG` | ❌ 不代表 CDC 实时 | 还需看 cron_express、pkWriteMode、运行记录 |
+| `pkWriteMode: OVERWRITE` | 覆盖写 → 离线批量 | 结合 cron 和运行记录确认 |
+| 运行记录只有 1 条手动触发 | → 定时调度可能未生效 | 需确认 cron 是否正常触发 |
+
+**综合判断规则**：
+- `cron_express` 有值 + `pkWriteMode: OVERWRITE` + 运行记录为定时触发 → **离线批量同步**
+- `cron_express` 为空 + 任务持续运行状态 → **实时同步（CDC/Kafka）**
+- 运行记录全是手动触发 → **调度未生效，需排查**
+
+---
+
+## 第三阶段：识别问题
+
+### 检查清单（按优先级）
+
+**🔴 P0 — 调度依赖缺失**
+
+```bash
+# 检查每个 ETL/转换任务的依赖配置
+cz-cli task content <task_id>
+# 查看 task_dependencies 字段是否为空数组 []
+```
+
+- ETL 转换任务的 `task_dependencies` 为空 → **P0，必须修复**
+- 上游同步任务未完成时下游就开始执行 → 读到旧数据或空数据
+- 运行记录时间线混乱（多次手动触发、时间间隔异常）→ 依赖缺失的典型症状
+
+**🔴 P0 — Dynamic Table 刷新持续失败**
+
+```sql
+SHOW DYNAMIC TABLE REFRESH HISTORY <schema>.<table> LIMIT 10;
+-- status 连续出现 FAILED → P0
+```
+
+**🟡 P1 — DDL 幂等性问题**
+
+Dynamic Table 的 DDL 应统一使用 `CREATE OR REPLACE`，不要用 `DROP + CREATE` 两步：
+- `DROP` 和 `CREATE` 之间存在竞态条件
+- 如果 `CREATE` 失败，表已被删除，数据丢失
+
+```sql
+-- ❌ 有竞态风险
+DROP DYNAMIC TABLE IF EXISTS schema.table;
+CREATE DYNAMIC TABLE schema.table ...;
+
+-- ✅ 原子操作
+CREATE OR REPLACE DYNAMIC TABLE schema.table ...;
+```
+
+> ⚠️ `CREATE OR REPLACE` 有类型变更限制：字段类型变更（如 `TINYINT → BOOLEAN`）会报错。
+> 解决方案：用 `CAST(col AS TINYINT)` 保持类型兼容，或先 `DROP` 再 `CREATE`。
+
+**🟡 P1 — DWS 层跳过 DWD 直接读 ODS**
+
+```sql
+-- 检查 DWS 层 DT 的 SQL 定义，看 FROM 子句引用的是哪一层
+SHOW CREATE TABLE <dws_schema>.<table>;
+```
+
+- DWS 层应从 DWD 层读取，不应直接读 ODS
+- 跳层问题：重复计算（DWD 已做的 JSON 解析/类型转换在 DWS 又做一遍）、口径不一致、维护成本高
+
+**🟡 P1 — Dynamic Table 定义中包含 ORDER BY**
+
+```sql
+-- 查看 DT 定义
+SHOW CREATE TABLE <schema>.<dt_name>;
+-- 如果 AS 子句中有 ORDER BY → 需要移除
+```
+
+- DT 的 `ORDER BY` 仅在查询时生效，不影响存储顺序
+- 每次刷新额外消耗计算资源做排序，无实际收益
+- 排序逻辑应放在查询端（BI 工具或下游 SQL）
+
+**🟢 P2 — DDL 任务保留 Cron 配置**
+
+```bash
+cz-cli task content <ddl_task_id>
+# edit_state=20（DRAFT）但 cron_express 不为空 → P2
+```
+
+- DRAFT 状态不会实际执行，但保留 Cron 配置容易误导维护者
+- 建议清理，非紧急
+
+**🟢 P2 — Studio 任务脚本与实际 DT 定义不一致**
+
+直接通过 SQL 重建 DT 后，Studio 任务脚本不会自动同步：
+
+```bash
+# 检查：读 Studio 任务脚本
+cz-cli task content <task_id>
+
+# 对比：读实际 DT 定义（执行以下 SQL）
+# SHOW CREATE TABLE <schema>.<table>
+
+# 如果不一致，同步 Studio 任务脚本
+cz-cli task save-content <task_id> --content "<new_sql>"
+```
+
+---
+
+## 第四阶段：执行修复
+
+### 修复依赖配置
+
+```bash
+# 为 ETL 任务配置上游依赖
+cz-cli task save-config <task_id> --deps replace \
+  --dep-tasks '[{"taskId":<upstream_id>,"taskName":"<upstream_name>"}]'
+
+# 部署生效
+cz-cli task deploy <task_id> -y
+```
+
+### 修复 DT DDL（统一为 CREATE OR REPLACE）
+
+```sql
+-- 先确认字段类型，避免类型变更报错
+SHOW CREATE TABLE <schema>.<table>;
+
+-- 执行重建（如有类型变更，用 CAST 保持兼容）
+CREATE OR REPLACE DYNAMIC TABLE <schema>.<table>
+  REFRESH INTERVAL <n> <unit> vcluster <gp_cluster>
+AS
+SELECT ...
+FROM <dwd_schema>.<table>  -- 确保从 DWD 层读取，不跳层
+...;  -- 移除 ORDER BY
+
+-- 立即触发首次刷新
+REFRESH DYNAMIC TABLE <schema>.<table>;
+```
+
+### 同步 Studio 任务脚本
+
+```bash
+# SQL 重建 DT 后，同步 Studio 任务脚本保持一致
+cz-cli task save-content <task_id> --content "<updated_sql>"
+```
+
+### 执行原则
+
+- **直接 SQL 操作**（重建 DT、修改表结构）→ 执行对应 SQL，执行前向用户确认
+- **Studio 任务配置**（依赖、Cron、脚本）→ 用 `cz-cli task save-*` + `deploy`
+- **两者都改时**：先改 SQL（数据层），再同步 Studio（配置层）
+
+---
+
+## 第五阶段：验证
+
+修复完成后，**逐项验证**，不跳过：
+
+```sql
+-- 1. Dynamic Table 刷新状态
+SHOW DYNAMIC TABLE REFRESH HISTORY <schema>.<table> LIMIT 5;
+-- 确认最近一次 status = SUCCESS
+
+-- 2. 各层行数
+SELECT COUNT(*) FROM <ods_schema>.<table>;
+SELECT COUNT(*) FROM <dwd_schema>.<table>;
+SELECT COUNT(*) FROM <dws_schema>.<table>;
+
+-- 3. 关键字段非空率
+SELECT ROUND(COUNT(key_field) * 100.0 / COUNT(*), 2) AS non_null_pct
+FROM <schema>.<table>;
+```
+
+```bash
+# 4. 确认任务依赖已生效
+cz-cli task content <task_id>
+# 查看 task_dependencies 不再为空
+
+# 5. 确认 Studio 任务脚本已同步
+cz-cli task content <task_id>
+# 对比脚本内容与实际 DT 定义一致
+```
+
+向用户输出 Review 结论：
+```
+Review 结论：
+- 发现问题：P0 × N，P1 × N，P2 × N
+- 已修复：（列出每项）
+- 未修复/建议：（列出每项及原因）
+- 验证结果：各层行数、DT 刷新状态
+```
+
+---
+
+## 常见问题速查
+
+| 现象 | 根因 | 排查命令 |
+|---|---|---|
+| ETL 任务读到旧数据 | 依赖缺失，上游未完成就开始执行 | `cz-cli task content` 查 task_dependencies |
+| 运行记录时间线混乱 | 依赖缺失，多次手动触发 | `cz-cli runs list` 看触发方式 |
+| DT 刷新报"表已存在" | DROP+CREATE 竞态，或 CREATE OR REPLACE 类型冲突 | `SHOW CREATE TABLE` 确认字段类型 |
+| DT 刷新时间与预期不符 | REFRESH INTERVAL 以创建时间为基准，不对齐整点 | 创建后立即执行 `REFRESH DYNAMIC TABLE` |
+| Studio 脚本与实际 DT 不一致 | 直接 SQL 重建后未同步 Studio | `cz-cli task save-content` 同步 |
+| 同步任务判断为 CDC 但实为离线 | 只看 readMode 字段，未综合判断 | 结合 cron、pkWriteMode、运行记录综合判断 |
+| DWS 数据与 DWD 口径不一致 | DWS 跳层读 ODS，重复计算 | `SHOW CREATE TABLE` 检查 FROM 子句 |

package/bin/skills/clickzetta-query-optimizer/LICENSE

@@ -0,0 +1,16 @@
+ClickZetta Skills License
+© 2026 Yunqi Inc. All rights reserved.
+LICENSE: Use of these materials (including all code, prompts, assets, files, and other components of these skills (collectively, "Skills")) is governed by your agreement with ClickZetta for the Service. If no separate agreement exists, use is governed by ClickZetta's Terms of Service (available at: https://yunqi.tech/documents/user-aggrement).
+Your applicable agreement is referred to as the "Agreement." "Service" is as defined in the Agreement.
+ADDITIONAL RESTRICTIONS: Notwithstanding anything in the Agreement to the contrary, you may not:
+
+Extract from the Service or retain copies of the Skills outside use with the Service;
+Reproduce or copy the Skills, except for temporary copies created automatically during authorized use of the Service;
+Create derivative works based on the Skills;
+Distribute, sublicense, or transfer the Skills to any third party;
+Make, offer to sell, sell, or import any inventions embodied in the Skills; nor,
+Reverse engineer, decompile, or disassemble the Skills.
+
+The receipt, viewing, or possession of the Skills does not convey or imply any license or right beyond those expressly granted above.
+Yunqi retains all rights, title, and interest in the Skills, including all copyrights, trademarks, patents, and all other applicable intellectual property rights.
+THE SKILLS ARE PROVIDED "AS IS," WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SKILLS OR THE USE OR OTHER DEALINGS IN THE SKILLS.

package/bin/skills/clickzetta-query-optimizer/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: clickzetta-query-optimizer
+description: |
+  诊断和优化 ClickZetta Lakehouse SQL 查询性能。覆盖执行计划分析、慢查询排查、
+  结果缓存、小文件合并、Map Join 优化、Sort Key 推荐等完整调优工作流。
+  当用户说"查询慢"、"SQL 性能优化"、"执行计划"、"EXPLAIN"、"查看 Job"、
+  "慢查询"、"小文件"、"OPTIMIZE"、"结果缓存"、"Result Cache"、
+  "Map Join"、"排序列"、"sort key"、"查询调优"、"性能诊断"时触发。
+  Keywords: query optimization, EXPLAIN, execution plan, slow query, cache, Map Join, Sort Key
+---
+
+# ClickZetta 查询性能优化
+
+## ⚠️ 注意事项
+
+- `OPTIMIZE` 命令只能在**通用型（GENERAL PURPOSE）计算集群**运行，分析型集群不生效
+- Result Cache 默认未开启，需手动 `SET cz.sql.enable.shortcut.result.cache = true`
+- Map Join 小表限制为 **1GB**，超过则失败
+
+---
+
+## 诊断流程
+
+```
+查询慢
+├── 1. 先看执行计划（EXPLAIN）
+│   ├── 发现全表扫描 → 考虑加索引或设置 sort key
+│   ├── 发现大表 JOIN → 考虑 MAPJOIN hint
+│   └── 发现大量 Sort → 检查 ORDER BY 是否必要
+├── 2. 查看 Job 历史（SHOW JOBS）
+│   └── 找到慢 Job → 在 Studio Job Profile 查看详细执行统计
+├── 3. 检查小文件问题
+│   └── 频繁写入的表 → OPTIMIZE 合并小文件
+└── 4. 利用缓存
+    └── 重复查询 → 开启 Result Cache
+```
+
+---
+
+## 步骤 1：分析执行计划
+
+阅读 [references/explain.md](references/explain.md)
+
+```sql
+-- 快速查看物理执行计划
+EXPLAIN SELECT ...;
+
+-- 详细查看逻辑+物理执行计划
+EXPLAIN EXTENDED SELECT ...;
+```
+
+重点关注：
+- `PhysicalTableScan` 是否扫描了过多数据
+- `PhysicalJoin` 的策略（是否触发 MapJoin）
+- `PhysicalSort` 是否可以避免
+
+---
+
+## 步骤 2：查看慢查询 Job
+
+阅读 [references/show-jobs.md](references/show-jobs.md)
+
+```sql
+-- 查看执行超过 2 分钟的 Job
+SHOW JOBS IN VCLUSTER default_ap WHERE execution_time > interval 2 minute;
+
+-- 查看最近 50 条 Job
+SHOW JOBS LIMIT 50;
+```
+
+找到 Job ID 后，在 Studio → Job Profile 查看详细执行统计和执行计划图。
+
+---
+
+## 步骤 3：小文件优化
+
+阅读 [references/optimize.md](references/optimize.md)
+
+```sql
+-- 手动合并小文件（异步，立即返回）
+OPTIMIZE my_schema.orders;
+
+-- 指定分区合并
+OPTIMIZE my_schema.orders WHERE dt = '2024-01-01';
+
+-- 同步执行（等待完成）
+OPTIMIZE my_schema.orders OPTIONS('cz.sql.optimize.table.async' = 'false');
+
+-- 写入时自动触发合并
+SET cz.sql.compaction.after.commit = true;
+```
+
+---
+
+## 步骤 4：开启结果缓存
+
+阅读 [references/result-cache.md](references/result-cache.md)
+
+```sql
+-- 开启 Result Cache（SESSION 级别）
+SET cz.sql.enable.shortcut.result.cache = true;
+
+-- 关闭
+SET cz.sql.enable.shortcut.result.cache = false;
+```
+
+命中缓存的查询通常在 15ms 内返回。在 Job Profile 中可看到 `JOB RESULT REUSE` 标记。
+
+---
+
+## 步骤 5：Map Join 与 Sort Key
+
+阅读 [references/hints-and-sortkey.md](references/hints-and-sortkey.md)
+
+```sql
+-- Map Join：小表（<1GB）与大表 JOIN 时使用
+SELECT /*+ MAPJOIN (small_table) */ *
+FROM large_table t1
+JOIN small_table t2 ON t1.id = t2.id;
+
+-- 查看系统推荐的 Sort Key
+SELECT * FROM information_schema.sortkey_candidates;
+
+-- 应用推荐（直接执行 statement 列中的 SQL）
+ALTER TABLE schema.table_name SET PROPERTIES("hint.sort.columns"="column_name");
+
+-- 开启自动收集 Sort Key 推荐
+ALTER WORKSPACE my_workspace SET PROPERTIES (auto_index='day');
+
+-- 收集表统计信息（Sort Key 推荐为空时先执行）
+ANALYZE TABLE schema.table_name;
+```
+
+---
+
+## 常见问题
+
+| 问题 | 排查方向 |
+|---|---|
+| 查询慢但执行计划看起来正常 | 检查小文件数量（`SHOW PARTITIONS EXTENDED`），考虑 OPTIMIZE |
+| Result Cache 未命中 | 检查 SQL 是否完全一致、是否含 UDF 或非确定性函数、表数据是否有变更 |
+| OPTIMIZE 无效 | 确认使用的是通用型（GP）集群，不是分析型集群 |
+| Map Join 失败 | 小表超过 1GB，改用普通 JOIN 或拆分查询 |
+| Sort Key 推荐为空 | 先执行 `ANALYZE TABLE`，再等待自动收集周期 |
+
+---
+
+## 参考文档
+
+- [EXPLAIN](https://www.yunqi.tech/documents/EXPLAIN)
+- [SHOW JOBS](https://www.yunqi.tech/documents/show-jobs)
+- [Result Cache](https://www.yunqi.tech/documents/result_cache)
+- [OPTIMIZE](https://www.yunqi.tech/documents/OPTIMIZE)
+- [小文件优化](https://www.yunqi.tech/documents/small_file_optimization)
+- [Map Join](https://www.yunqi.tech/documents/mapjoin)
+- [推荐排序列](https://www.yunqi.tech/documents/auto-index)

package/bin/skills/clickzetta-query-optimizer/eval_cases.jsonl

@@ -0,0 +1,5 @@
+{"case_id":"001","type":"should_call","user_input":"为什么这个 JOIN 查询这么慢？SELECT t1.user_id, t2.tenant_name FROM public.dim_studio_user_dmin_f t1 JOIN public.dim_studio_tenant_dmin_f t2 ON t1.tenant_id = t2.tenant_id","expected_skill":"clickzetta-query-optimizer","expected_output_contains":["JOIN","优化"]}
+{"case_id":"002","type":"should_call","user_input":"public.dwd_studio_lakehouse_jobs_dd_i 表适合设置什么 Sort Key？","expected_skill":"clickzetta-query-optimizer","expected_output_contains":["sort","key"]}
+{"case_id":"003","type":"should_call","user_input":"怎么开启结果缓存？Result Cache 的使用限制是什么？","expected_skill":"clickzetta-query-optimizer","expected_output_contains":["cache","cz.sql.enable"]}
+{"case_id":"004","type":"should_call","user_input":"表有很多小文件影响查询性能，怎么合并优化？","expected_skill":"clickzetta-query-optimizer","expected_output_contains":["OPTIMIZE","小文件"]}
+{"case_id":"005","type":"should_call","user_input":"怎么用 EXPLAIN 分析执行计划？Map Join 什么时候用？","expected_skill":"clickzetta-query-optimizer","expected_output_contains":["EXPLAIN","Map Join"]}

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;
+```