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

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

@@ -1,402 +0,0 @@
----
-name: clickzetta-oss-ingest-pipeline
-description: |
-  搭建 ClickZetta 对象存储（OSS/S3/COS）数据导入管道，覆盖持续导入（PIPE）和批量一次性导入
-  两大场景。持续导入支持 LIST_PURGE 扫描模式和 EVENT_NOTIFICATION 消息通知模式；批量导入支持
-  Volume + INSERT INTO 和 Volume + COPY INTO 两种方式。当用户说"对象存储导入"、"OSS 数据管道"、
-  "S3 数据导入"、"PIPE 持续导入"、"文件自动加载"、"存储桶数据同步"、"COS 导入"、
-  "批量导入 OSS"、"从 OSS 加载数据"、"Volume 导入"时触发。
-  包含 PIPE 持续导入（两种 INGEST_MODE）、批量导入（Volume + COPY/INSERT）、Connection/Volume 创建、
-  监控管理等 ClickZetta 特有逻辑。
-  Keywords: OSS, S3, COS, object storage, PIPE, COPY INTO, file ingestion
----
-
-# 对象存储数据管道搭建工作流
-
-## 适用场景
-
-- 从对象存储（阿里云 OSS / AWS S3 / 腾讯云 COS）持续自动导入数据到 Lakehouse（PIPE 模式）
-- 从对象存储批量一次性导入数据到 Lakehouse（Volume + COPY/INSERT 模式）
-- 需要微批处理方式加载新增文件，实现近实时数据同步
-- 需要选择扫描模式（LIST_PURGE）或消息通知模式（EVENT_NOTIFICATION）
-- 需要对导入数据进行过滤转换（WHERE 条件、指定文件）
-- 关键词：OSS PIPE、S3 导入、对象存储管道、文件自动加载、PIPE 持续导入、COS 数据同步、批量导入、Volume 导入
-
-## 前置依赖
-
-- ClickZetta Lakehouse 账户，具备创建 PIPE、表、存储连接、Volume 等权限
-- 对象存储桶可达（Endpoint、AccessKey 或 Role ARN）
-- clickzetta-studio-mcp 工具可用（`LH_execute_query`、`LH_show_object_list` 等）
-
-## 核心概念
-
-### INGEST_MODE 选择指引
-
-| 模式 | 触发方式 | 适用场景 | 云平台支持 | 授权方式 |
-|------|---------|---------|-----------|---------|
-| `LIST_PURGE` | 定期扫描目录 | 通用场景，导入后删除源文件 | 所有云平台 | 密钥 或 Role ARN |
-| `EVENT_NOTIFICATION` | 消息服务通知 | 低延迟场景，文件上传即触发 | 仅阿里云 OSS + AWS S3 | 仅 Role ARN |
-
-### 关键限制
-
-- 每个 PIPE 需对应独立的 Volume，不可复用
-- 不支持修改 COPY 语句逻辑，需删除 PIPE 重新创建
-- PIPE 中的 COPY 语句不支持 `files` / `regexp` / `subdirectory` 参数
-- 数据加载无法保证严格有序
-- `load_history` 去重记录保留 7 天
-- 修改 `COPY_JOB_HINT` 会覆盖所有已有 hints，需一次性设置全部参数
-- **Volume PIPE 不支持 Kafka 专用参数**：`BATCH_INTERVAL_IN_SECONDS`、`BATCH_SIZE_PER_KAFKA_PARTITION`、`MAX_SKIP_BATCH_COUNT_ON_ERROR` 仅适用于 Kafka PIPE
-- **`COPY_JOB_HINT` 必须是合法 JSON 格式**，键值都要用双引号：`'{"IGNORE_TMP_FILE": "true"}'`，不能用 `KEY=VALUE` 格式
-
-### 文件大小建议
-
-- gzip 压缩文件：≈ 50MB
-- CSV / PARQUET 未压缩文件：128MB ~ 256MB
-
-## 工作流
-
-### 模式 A：LIST_PURGE 扫描模式（通用）
-
-#### 步骤 1：创建存储连接（Storage Connection）
-
-```sql
--- 使用 LH_execute_query 执行
--- 密钥方式（LIST_PURGE 模式支持）
-CREATE STORAGE CONNECTION IF NOT EXISTS my_oss_connection
-  TYPE OSS
-  ENDPOINT = 'oss-cn-hangzhou.aliyuncs.com'
-  ACCESS_KEY = '<your_access_key>'
-  SECRET_KEY = '<your_secret_key>'
-  COMMENT = 'OSS connection for data pipeline';
-```
-
-> **提示**：如果使用 Role ARN 方式（EVENT_NOTIFICATION 模式必须），参见下方"模式 B"中的 Connection 创建语法。
-
-#### 步骤 2：创建外部 Volume
-
-```sql
--- 使用 LH_execute_query 执行
-CREATE EXTERNAL VOLUME IF NOT EXISTS pipe_volume
-  STORAGE_CONNECTION = my_oss_connection
-  LOCATION = 'oss://my-bucket/data-path/'
-  COMMENT = 'Volume for OSS PIPE ingestion';
-```
-
-> **关键参数**：
-> - 如需递归扫描子目录：添加 `recursive = true`
-> - 如需自动刷新目录元数据：添加 `directory = (enable = true, auto_refresh = true)`
-
-#### 步骤 3：验证 COPY INTO 可独立运行
-
-在创建 PIPE 之前，先用 COPY INTO 验证数据能正常加载：
-
-```sql
--- 使用 LH_execute_query 执行
-COPY INTO my_schema.target_table
-FROM VOLUME pipe_volume
-USING CSV
-OPTIONS (
-  'header' = 'true',
-  'delimiter' = ','
-);
-```
-
-> **重要**：PIPE 中的 COPY 语句不支持 `files`、`regexp`、`subdirectory` 参数。确保此处验证时也不使用这些参数。
-
-#### 步骤 4：创建 PIPE（LIST_PURGE 模式）
-
-```sql
--- 使用 LH_execute_query 执行
-CREATE PIPE IF NOT EXISTS my_oss_pipe
-  INGEST_MODE = 'LIST_PURGE'
-  VIRTUAL_CLUSTER = 'my_vc'
-  COMMENT = 'OSS data pipeline - scan mode'
-AS
-COPY INTO my_schema.target_table
-FROM VOLUME pipe_volume
-USING CSV
-OPTIONS (
-  'header' = 'true',
-  'delimiter' = ',',
-  'purge' = 'true'
-);
-```
-
-> **参数说明**：
-> - `INGEST_MODE = 'LIST_PURGE'`：定期扫描 Volume 目录，发现新文件即加载
-> - `purge = true`：**LIST_PURGE 模式必须设置**，加载成功后删除源文件（避免重复导入）。即使不想删除源文件，LIST_PURGE 模式也需要此参数，否则会重复导入同一文件
-> - `VIRTUAL_CLUSTER`：指定执行 PIPE 任务的虚拟集群
-
-#### 步骤 5：验证 PIPE 状态
-
-```sql
--- 使用 LH_execute_query 执行
-DESC PIPE EXTENDED my_oss_pipe;
-```
-
-确认 `pipe_execution_paused = false`（PIPE 已启动运行）。
-
----
-
-### 模式 B：EVENT_NOTIFICATION 消息通知模式（低延迟）
-
-> 仅支持阿里云 OSS + AWS S3。文件上传到桶后，通过消息服务（MNS/SQS）通知 Lakehouse 立即加载。
-
-#### 前置准备（阿里云 OSS 示例）
-
-1. **开通阿里云 MNS 消息服务**：在阿里云控制台开通消息服务 MNS
-2. **配置 OSS 事件通知**：在 OSS 桶 → 事件通知 → 创建规则，事件类型选择 `ObjectCreated`，目标选择 MNS 队列
-3. **授权 OSS 读取权限**：创建 RAM 角色，授予 `oss:GetObject`、`oss:ListBucket` 权限，记录 Role ARN
-4. **授权 MNS 到 Lakehouse**：将 Lakehouse 服务账号添加到 MNS 队列的授权策略中
-
-#### 步骤 1：创建存储连接（Role ARN 方式）
-
-```sql
--- 使用 LH_execute_query 执行
-CREATE STORAGE CONNECTION IF NOT EXISTS my_oss_role_connection
-  TYPE OSS
-  ENDPOINT = 'oss-cn-hangzhou.aliyuncs.com'
-  ROLE_ARN = 'acs:ram::1234567890:role/clickzetta-oss-role'
-  REGION = 'cn-hangzhou'
-  COMMENT = 'OSS connection via Role ARN for event notification mode';
-```
-
-#### 步骤 2：创建外部 Volume
-
-```sql
--- 使用 LH_execute_query 执行
-CREATE EXTERNAL VOLUME IF NOT EXISTS pipe_event_volume
-  STORAGE_CONNECTION = my_oss_role_connection
-  LOCATION = 'oss://my-bucket/data-path/';
-```
-
-#### 步骤 3：创建 PIPE（EVENT_NOTIFICATION 模式）
-
-```sql
--- 使用 LH_execute_query 执行
-CREATE PIPE IF NOT EXISTS my_oss_event_pipe
-  INGEST_MODE = 'EVENT_NOTIFICATION'
-  VIRTUAL_CLUSTER = 'my_vc'
-  ALICLOUD_MNS_QUEUE = 'my-mns-queue-name'
-  COMMENT = 'OSS data pipeline - event notification mode'
-AS
-COPY INTO my_schema.target_table
-FROM VOLUME pipe_event_volume
-USING CSV
-OPTIONS (
-  'header' = 'true',
-  'delimiter' = ','
-);
-```
-
-> **参数说明**：
-> - `INGEST_MODE = 'EVENT_NOTIFICATION'`：通过消息通知触发加载
-> - `ALICLOUD_MNS_QUEUE`：阿里云 MNS 队列名称（AWS 使用 `AWS_SQS_QUEUE`）
-> - 此模式下不需要 `purge = true`，因为是事件驱动而非扫描
-
----
-
-### 模式 C：批量导入（一次性 Volume + COPY/INSERT）
-
-> 适用于一次性或定期批量加载对象存储中的文件，无需创建 PIPE。支持阿里云 OSS、腾讯云 COS 和 AWS S3。
-> 推荐使用 GENERAL PURPOSE 类型的虚拟集群执行批量加载。
-
-#### 使用限制
-
-- 不支持跨云导入（源存储与 Lakehouse 环境需在同一云平台）
-- 同地域建议使用内网 Endpoint（如 `oss-cn-shanghai-internal.aliyuncs.com`）以提升速度和稳定性
-
-#### 步骤 1：创建目标表
-
-```sql
--- 使用 LH_execute_query 执行
-CREATE TABLE IF NOT EXISTS my_schema.target_table (
-  id STRING,
-  name STRING,
-  amount DECIMAL(10,2),
-  created_date STRING
-);
-```
-
-#### 步骤 2：创建存储连接（access_id/access_key 语法）
-
-```sql
--- 使用 LH_execute_query 执行
--- 批量导入场景使用 access_id / access_key 语法
-CREATE STORAGE CONNECTION IF NOT EXISTS my_batch_conn
-  TYPE OSS
-  ENDPOINT = 'oss-cn-shanghai-internal.aliyuncs.com'
-  access_id = '<your_access_id>'
-  access_key = '<your_access_key>'
-  COMMENTS = 'OSS batch import connection';
-```
-
-> **注意**：批量导入场景中 Connection 参数使用 `access_id` / `access_key`（小写），与 PIPE 模式中的 `ACCESS_KEY` / `SECRET_KEY` 写法不同，两种写法均可使用。
-
-#### 步骤 3：创建外部 Volume（启用目录自动刷新）
-
-```sql
--- 使用 LH_execute_query 执行
-CREATE EXTERNAL VOLUME IF NOT EXISTS my_batch_volume
-  LOCATION 'oss://my-bucket/data-path/'
-  USING CONNECTION my_batch_conn
-  DIRECTORY = (enable=true, auto_refresh=true);
-```
-
-> **关键参数**：
-> - `LOCATION`：对象存储路径，格式为 `oss://bucket/path/`
-> - `USING CONNECTION`：引用已创建的存储连接
-> - `DIRECTORY = (enable=true, auto_refresh=true)`：启用目录元数据并自动刷新，便于查询 Volume 中的文件列表
->
-> **注意**：批量导入 Volume 使用 `LOCATION ... USING CONNECTION ...` 语法；PIPE 模式 Volume 使用 `STORAGE_CONNECTION = ... LOCATION = ...` 语法。两种语法均有效，适用于不同场景，不可混用。
-
-#### 步骤 4a：INSERT INTO 从 Volume 导入（支持过滤转换）
-
-```sql
--- 使用 LH_execute_query 执行
-INSERT INTO my_schema.target_table
-SELECT * FROM VOLUME my_batch_volume (
-  id STRING,
-  name STRING,
-  amount DECIMAL(10,2),
-  created_date STRING
-) USING CSV OPTIONS ('header'='true', 'sep'=',')
-FILES ('data_file_01.csv')
-WHERE amount > 0;
-```
-
-> **参数说明**：
-> - `VOLUME my_batch_volume (...)`：指定 Volume 及列定义（Schema-on-Read）
-> - `USING CSV OPTIONS (...)`：指定文件格式和解析选项
-> - `FILES ('file1.csv', 'file2.csv')`：指定要加载的文件名（可选，不指定则加载全部）
-> - `WHERE ...`：对数据进行过滤转换（可选）
-> - INSERT INTO 方式支持 `FILES` 和 `WHERE` 参数，适合需要精细控制的场景
-
-#### 步骤 4b：COPY INTO 从 Volume 导入（简洁语法）
-
-```sql
--- 使用 LH_execute_query 执行
-COPY INTO my_schema.target_table
-FROM VOLUME my_batch_volume (
-  id STRING,
-  name STRING,
-  amount DECIMAL(10,2),
-  created_date STRING
-) USING CSV OPTIONS ('header'='true', 'sep'=',');
-```
-
-> **INSERT INTO vs COPY INTO 选择**：
-> - `INSERT INTO`：支持 `FILES()` 指定文件、`WHERE` 过滤转换，适合精细控制
-> - `COPY INTO`：语法更简洁，适合全量加载
-> - 两者都支持 Schema-on-Read（在 FROM VOLUME 中定义列）
-
-#### 步骤 5：验证导入结果
-
-```sql
--- 使用 LH_execute_query 执行
-SELECT COUNT(*) AS total_rows FROM my_schema.target_table;
-SELECT * FROM my_schema.target_table LIMIT 10;
-```
-
----
-
-## 监控与运维
-
-### 查看 PIPE 详细状态
-
-```sql
--- 使用 LH_execute_query 执行
-DESC PIPE EXTENDED my_oss_pipe;
-```
-
-关键字段：
-- `pipe_execution_paused`：是否暂停
-- `ingest_mode`：导入模式
-- `virtual_cluster`：执行集群
-- `definition`：COPY 语句定义
-
-### 查看加载历史
-
-```sql
--- 使用 LH_execute_query 执行
-SELECT * FROM TABLE(load_history('my_schema.target_table'))
-ORDER BY last_load_time DESC
-LIMIT 20;
-```
-
-> `load_history` 去重记录保留 7 天。
-
-### 通过 query_tag 过滤 PIPE 作业
-
-PIPE 执行的作业会自动打上 `query_tag`，格式为：`pipe.<workspace_name>.<schema_name>.<pipe_name>`
-
-```sql
--- 使用 LH_execute_query 执行
--- 在 JOBS 列表中过滤 PIPE 相关作业
-SHOW JOBS WHERE query_tag = 'pipe.my_workspace.my_schema.my_oss_pipe';
-```
-
----
-
-## PIPE 管理操作
-
-### 暂停 / 恢复 PIPE
-
-```sql
--- 暂停 PIPE
-ALTER PIPE my_oss_pipe SET PIPE_EXECUTION_PAUSED = true;
-
--- 恢复 PIPE
-ALTER PIPE my_oss_pipe SET PIPE_EXECUTION_PAUSED = false;
-```
-
-### 修改 PIPE 属性
-
-```sql
--- 修改虚拟集群
-ALTER PIPE my_oss_pipe SET VIRTUAL_CLUSTER = 'new_vc';
-
--- 修改 COPY_JOB_HINT（注意：会覆盖所有已有 hints，需一次性设置全部参数）
--- 必须是合法 JSON 格式，键值都要用双引号
-ALTER PIPE my_oss_pipe SET COPY_JOB_HINT = '{"max_file_count":"100","force":"false"}';
-```
-
-> **限制**：每次 ALTER PIPE 只能修改一个属性。不支持修改 COPY 语句逻辑，需删除 PIPE 重新创建。
-
-### 删除 PIPE
-
-```sql
-DROP PIPE IF EXISTS my_oss_pipe;
-```
-
----
-
-## 故障排除
-
-| 问题 | 排查方向 |
-|------|---------|
-| PIPE 创建后无数据加载 | 1. `DESC PIPE EXTENDED` 检查是否暂停 2. 确认 Volume 路径下有新文件 3. 检查 COPY INTO 是否能独立运行 |
-| LIST_PURGE 模式文件未被删除 | 确认 `purge = true` 已设置；检查 Connection 的 AccessKey 是否有删除权限 |
-| EVENT_NOTIFICATION 模式无触发 | 1. 检查 MNS/SQS 队列是否收到消息 2. 确认 OSS 事件通知规则配置正确 3. 检查 Role ARN 授权 |
-| 重复加载数据 | `load_history` 去重记录仅保留 7 天，超过 7 天的同名文件会被重新加载 |
-| COPY_JOB_HINT 修改后部分参数丢失 | `SET COPY_JOB_HINT` 会覆盖所有已有 hints，需在一次 ALTER 中设置全部参数 |
-
-## 注意事项
-
-### PIPE 持续导入（模式 A / B）
-
-- 每个 PIPE 需对应独立的 Volume，不可多个 PIPE 共用同一 Volume
-- PIPE 中的 COPY 语句不支持 `files` / `regexp` / `subdirectory` 参数
-- 数据加载无法保证严格有序（多文件并行加载）
-- 推荐文件大小：gzip 压缩 ≈ 50MB，CSV/Parquet 未压缩 128MB ~ 256MB
-- `load_history` 去重记录保留 7 天，超期后同名文件可能被重复加载
-- 修改 COPY 逻辑需删除 PIPE 重新创建，ALTER PIPE 不支持修改 COPY 语句
-
-### 批量导入（模式 C）
-
-- Volume 支持阿里云 OSS、腾讯云 COS 和 AWS S3
-- 不支持跨云导入（源存储与 Lakehouse 环境需在同一云平台）
-- 同地域建议使用内网 Endpoint 以提升传输速度和稳定性
-- 推荐使用 GENERAL PURPOSE 类型虚拟集群执行批量加载任务
-- INSERT INTO 方式支持 `FILES()` 和 `WHERE` 参数，COPY INTO 不支持
-- Connection 参数 `access_id`/`access_key` 和 `ACCESS_KEY`/`SECRET_KEY` 两种写法均可使用

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

@@ -1,156 +0,0 @@
----
-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/references/explain.md

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

@@ -1,78 +0,0 @@
-# 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;
-```