@clickzetta/cz-cli-darwin-arm64 0.3.40 → 0.3.41

package/bin/skills/clickzetta-data-sharing/references/share-ddl.md

@@ -0,0 +1,134 @@
+# 数据分享 DDL 参考
+
+> 来源：https://www.yunqi.tech/documents/datasharing 等
+
+## 概念
+
+数据分享（Share）是 Lakehouse 提供的**无复制**跨账户/跨实例数据共享功能：
+- 数据提供方创建 Share 对象，将表或视图授权给指定服务实例
+- 数据消费方通过 `CREATE SCHEMA FROM SHARE` 在本地创建只读 Schema 访问共享数据
+- 数据实时更新，消费方无需同步，无需为存储付费
+
+**限制：**
+- 共享数据为**只读**，消费方不可修改
+- 一个 Share 只能包含同一工作空间下的数据
+- 一个 Share 最多包含 1000 个 table/view
+- 不支持二次分享
+- 需要 `instance_admin` 角色才能创建 Share
+
+---
+
+## 提供方操作（OUTBOUND）
+
+### 1. 创建 Share
+
+```sql
+CREATE SHARE share_demo;
+```
+
+### 2. 将表/视图加入 Share
+
+```sql
+-- 添加单张表
+GRANT SELECT, READ METADATA ON TABLE public.orders TO SHARE share_demo;
+
+-- 添加视图（推荐：用视图控制分享范围）
+GRANT SELECT, READ METADATA ON VIEW public.orders_summary TO SHARE share_demo;
+
+-- 添加多张表
+GRANT SELECT, READ METADATA ON TABLE public.orders, public.customers TO SHARE share_demo;
+
+-- 添加 Schema 下所有表（含未来新建的表，谨慎使用）
+GRANT SELECT, READ METADATA ON ALL TABLES IN SCHEMA public TO SHARE share_demo;
+```
+
+### 3. 指定接收实例
+
+```sql
+-- 添加接收方实例
+ALTER SHARE share_demo ADD INSTANCE consumer_instance_name;
+
+-- 移除接收方实例（立即撤销访问权限）
+ALTER SHARE share_demo REMOVE INSTANCE consumer_instance_name;
+```
+
+### 4. 从 Share 移除数据对象
+
+```sql
+-- 撤销表的分享权限
+REVOKE SELECT, READ METADATA ON TABLE public.orders FROM SHARE share_demo;
+
+-- 撤销视图的分享权限
+REVOKE SELECT ON VIEW public.orders_summary FROM SHARE share_demo;
+```
+
+### 5. 查看与管理
+
+```sql
+-- 查看所有 Share
+SHOW SHARES;
+
+-- 查看本实例分享出去的 Share
+SHOW SHARES WHERE kind = 'OUTBOUND';
+
+-- 查看 Share 包含的数据对象
+DESC SHARE share_demo;
+
+-- 删除 Share
+DROP SHARE IF EXISTS share_demo;
+```
+
+---
+
+## 消费方操作（INBOUND）
+
+### 1. 查看收到的 Share
+
+```sql
+-- 查看所有 Share（含 INBOUND）
+SHOW SHARES;
+
+-- 只看收到的 Share
+SHOW SHARES WHERE kind = 'INBOUND';
+```
+
+### 2. 查看 Share 内容
+
+```sql
+-- 格式：DESC SHARE <provider_instance>.<share_name>
+DESC SHARE provider_instance.share_demo;
+```
+
+返回字段：`kind`（schema/table/view）、`name`（对象名）、`shared_on`（共享时间）
+
+### 3. 创建本地只读 Schema（消费数据）
+
+```sql
+-- 格式：CREATE SCHEMA <local_schema> FROM SHARE SHARE <instance>.<share>.<schema>
+CREATE SCHEMA data_from_provider FROM SHARE SHARE provider_instance.share_demo.public;
+```
+
+创建后即可直接查询：
+
+```sql
+SELECT * FROM data_from_provider.orders LIMIT 10;
+
+-- 与本地表关联查询
+SELECT o.*, c.name
+FROM data_from_provider.orders o
+JOIN my_schema.customers c ON o.customer_id = c.id;
+```
+
+---
+
+## SHOW SHARES 返回字段说明
+
+| 字段 | 说明 |
+|---|---|
+| share_name | Share 名称 |
+| provider | 提供方租户名 |
+| provider_instance | 提供方服务实例名 |
+| provider_workspace | Share 所属工作空间 |
+| scope | 分享范围（当前仅 PRIVATE） |
+| to_instance | 接收方实例名（逗号分隔） |
+| kind | OUTBOUND（分享出）/ INBOUND（收到） |

package/bin/skills/clickzetta-dw-modeling/SKILL.md

@@ -108,6 +108,16 @@ B. 大奖牌架构（Medallion）
 - 实时看板（分钟级延迟）→ 告诉我，方案会有调整
 ```
 
+### 4. 方案确认时主动提示成本注意事项
+
+给出方案选项时，提醒用户以下成本相关决策点，让用户做知情选择：
+
+- **Dynamic Table 刷新频率**：按业务时效性选择，不要默认最高频率。T+1 用 `1 DAY`，小时级用 `1 HOUR`，分钟级用 `10~30 MINUTE`
+- **分层数量**：评估 DWS 和 ADS 是否都必要，每多一层 DT 就多一份刷新成本
+- **VCluster 规格**：建议从小规格开始，按需扩容
+
+> 具体 CRU 消耗无法在方案设计阶段精确预估，上线后加载 `clickzetta-cost-management` skill 监控实际消耗，按需调整刷新频率和集群规格。
+
 ---
 
 ## 第三阶段：方案确认后的完整输出
@@ -173,35 +183,113 @@ CLUSTERED BY (user_id) INTO 32 BUCKETS
 
 ```
 ODS/Bronze → DWD/Silver：SQL 任务（Studio 调度，清洗逻辑需手动控制）
-DWD/Silver → DWS/Gold：Dynamic Table（TARGET_LAG 控制延迟，自动增量）
+DWD/Silver → DWS/Gold：Dynamic Table（REFRESH INTERVAL 控制延迟，自动增量）
 DWS → ADS：Dynamic Table 或直接查询
 ```
 
 加载 `clickzetta-sql-pipeline-manager` 获取 Dynamic Table 详细语法。
 
+### 建管分离原则（重要）
+
+Studio 任务按类型严格区分，**不同类型任务的调度策略完全不同**：
+
+| 任务类型 | 示例 | 调度配置 | 说明 |
+|---|---|---|---|
+| DDL 建表任务 | CREATE TABLE、CREATE SCHEMA | **DRAFT，禁止配 Cron，禁止配依赖** | 一次性执行，手动触发，不参与调度链 |
+| ETL 转换任务 | ODS→DWD 清洗 SQL | 配置 Cron + 依赖上游同步任务 | 周期性执行，构成调度 DAG |
+| 数据同步任务 | MySQL→ODS 整库同步 | 配置 Cron，作为 ETL 任务的上游 | 周期性执行，ETL 任务的触发前提 |
+| DWS/ADS 聚合层 | 指标汇总、报表宽表 | **使用 Dynamic Table，不建调度任务** | 系统自动刷新，额外建任务是冗余计算 |
+
+> ⚠️ **常见错误**：为 DDL 任务配置了 Cron，导致建表语句被重复执行，引发 `SCHEDULE_TASK_HAD_CHILDREN_NODES_EXCEPTION` 等调度冲突。DDL 任务完成后应立即降级为 DRAFT 状态。
+
+### Studio 任务目录组织规范
+
+每个数仓项目在 Studio 中创建独立任务目录，统一管理所有任务资产：
+
+```
+<业务域>_dw/                          ← 项目任务目录（如 shenyu_gateway_dw）
+├── 00_sync_<source>_to_ods           ← 数据同步（Cron，最早执行）
+├── 01_ddl_ods                        ← ODS 建表（DRAFT，不调度）
+├── 02_ddl_dwd                        ← DWD 建表（DRAFT，不调度）
+├── 03_ddl_dws_ads                    ← DWS/ADS 动态表建表（DRAFT，不调度）
+├── 04_transform_ods_to_dwd           ← ODS→DWD 清洗（Cron，依赖 00）
+└── 05_dqc_check                      ← 数据质量检查（Cron，依赖 04，可选）
+    （DWS/ADS 层由 Dynamic Table 自动刷新，无需任务）
+```
+
+> 任务编号规范：`00~` 同步层，`01~03` DDL 层（DRAFT），`04~` ETL 层（调度），DWS/ADS 无任务。
+
 ### 数据质量卡点
 
 | 层次 | 检查重点 | 时机 |
 |---|---|---|
-| ODS/Bronze | NULL 比例、CDC _op 分布 | 入库后 |
-| DWD/Silver | 唯一性、关联完整性（LEFT JOIN 验证匹配率） | ETL 后 |
-| DWS/Gold/ADS | 指标环比异常、汇总一致性 | Dynamic Table 刷新后 |
+| ODS/Bronze | NULL 比例、CDC _op 分布、行数与源端一致 | 入库后 |
+| DWD/Silver | 唯一性、LEFT JOIN 匹配率（结果行数 ≥ 左表行数）、关键字段非空率 | ETL 后 |
+| DWS/Gold/ADS | 指标环比异常、汇总一致性、Dynamic Table 刷新历史为 SUCCESS | Dynamic Table 刷新后 |
+
+> ⚠️ **LEFT JOIN 陷阱**：`LEFT JOIN ... WHERE 右表字段 = 值` 会退化为 INNER JOIN，导致数据丢失。过滤右表字段必须放在 `ON` 子句：`LEFT JOIN ... ON ... AND 右表字段 = 值`。
+
+### 交付验证 Checklist
+
+方案上线前必须逐项确认：
+
+- [ ] 各层行数与预期一致（ODS 行数 ≈ 源端，DWD 行数 ≤ ODS，DWS/ADS 行数符合聚合逻辑）
+- [ ] Dynamic Table 刷新历史显示 `SUCCESS`（`SHOW DYNAMIC TABLE REFRESH HISTORY`）
+- [ ] 关键字段 NULL 率在可接受范围内
+- [ ] LEFT JOIN 结果行数 ≥ 左表行数（否则检查过滤条件是否误放在 WHERE）
+- [ ] DWS/ADS 层无冗余调度任务（Dynamic Table 不需要额外 Cron）
+- [ ] 所有 DDL 任务已降级为 DRAFT 状态
+
+验证通过后，如需对整个管道做全面健康检查（调度依赖、DT 反模式、分层跳层等），加载 `clickzetta-pipeline-review` skill。
 
 ### 调度 DAG
 
 ```
 日批场景：
-数据同步（ODS 接入）→ DWD 清洗任务 → 数据质量检查
-                                          ↓
-                              DWS/Gold（Dynamic Table 自动刷新，无需调度）
+00_sync（Cron 02:00）→ 04_transform（Cron 02:30，依赖 00）→ 05_dqc（可选）
+                                                                ↓
+                                            DWS/ADS（Dynamic Table 自动刷新，无需调度）
 
 实时场景：
-CDC/Kafka 持续写入 Bronze → Silver（TARGET_LAG='10min'）→ Gold（TARGET_LAG='1h'）
+CDC/Kafka 持续写入 Bronze → Silver（REFRESH INTERVAL 10 MINUTE）→ Gold（REFRESH INTERVAL 1 HOUR）
 ```
 
 ### DDL 模板
 
-加载 `clickzetta-sql-syntax-guide` 确认语法，生成各层 DDL：
+加载 `clickzetta-sql-syntax-guide` 确认语法，生成各层 DDL。
+
+**数仓开发代码资产化原则：每段 SQL 都应保存为 Studio 任务，作为可管理的代码资产。**
+
+生成 DDL 后，按以下规范保存为 Studio 任务（先创建任务目录，再逐层保存）：
+
+```bash
+# 创建项目任务目录
+cz-cli task folder create <业务域>_dw
+
+# 各层 DDL 保存为独立 DRAFT 任务（不配 Cron，不配依赖）
+cz-cli task save-content 01_ddl_ods --content "<ods_ddl_sql>"
+cz-cli task save-content 02_ddl_dwd --content "<dwd_ddl_sql>"
+cz-cli task save-content 03_ddl_dws_ads --content "<dws_ads_ddl_sql>"
+
+# ETL 转换 SQL 保存为调度任务（配 Cron + 依赖上游同步任务）
+cz-cli task save-content 04_transform_ods_to_dwd --content "<etl_sql>"
+cz-cli task save-cron 04_transform_ods_to_dwd --cron '0 30 2 * * ? *'
+```
+
+> 任务是代码的载体，不只是调度配置。即使是一次性执行的 DDL，也应保存为 DRAFT 任务，方便后续查阅、复用和多环境迁移。
+
+**生成 Dynamic Table DDL 前，先确认可用的 GP 型 VCluster：**
+
+```sql
+-- 查看所有 VCluster 及状态，找到 type=GENERAL 且 status=RUNNING 的集群
+SHOW VCLUSTERS;
+```
+
+- `type = GENERAL`（GP 型）且 `status = RUNNING` → 直接使用该集群名
+- `status = STOPPED` → 先执行 `ALTER VCLUSTER <name> RESUME;` 再建表
+- 无 GP 型集群 → 参考 `clickzetta-vcluster-manager` 创建
+
+将查到的集群名替换下方 DDL 中的 `<gp_vcluster_name>`。
 
 ```sql
 -- ODS/Bronze（以 CDC 接入为例）
@@ -233,8 +321,7 @@ COMMENT 'DWD 订单事实表，清洗标准化';
 
 -- DWS/Gold（Dynamic Table，不用物化视图）
 CREATE DYNAMIC TABLE IF NOT EXISTS dws.user_order_daily
-  REFRESH interval 1 HOUR
-  VCLUSTER default_ap
+  REFRESH INTERVAL 1 HOUR vcluster <gp_vcluster_name>
 AS
 SELECT
     user_id,
@@ -245,6 +332,9 @@ SELECT
 FROM dwd.fact_orders
 WHERE status_code = 1
 GROUP BY user_id, order_date;
+
+-- 创建后立即执行首次刷新，重置刷新基准时间
+REFRESH DYNAMIC TABLE dws.user_order_daily;
 ```
 
 ---
@@ -257,3 +347,5 @@ GROUP BY user_id, order_date;
 4. **建模和管道一体**——DDL 和管道配置同步输出
 5. **分区用转换函数**：`days(col)` 不是 `col`
 6. **ODS/Bronze 零转换**，保留原始数据方便回溯
+7. **建管分离**——DDL 任务 DRAFT 不调度，DWS/ADS 层不建调度任务
+8. **创建 Dynamic Table 后立即 REFRESH**——重置刷新基准，实现开箱即用

package/bin/skills/clickzetta-dynamic-table/SKILL.md

@@ -14,6 +14,25 @@ description: |
 
 # Dynamic Table 使用指南 — 目录索引
 
+## 前置检查：确认可用的 GP 型 VCluster
+
+**创建动态表前必须先确认 VCluster 存在且运行正常。** 动态表的 `vcluster` 参数必须填写实际存在的 GP 型集群名称，写死 `default` 可能导致刷新失败。
+
+```sql
+-- 查看所有 VCluster 及其状态
+SHOW VCLUSTERS;
+-- 关注列：name, type, status
+-- type = GENERAL（GP 型，推荐用于动态表）
+-- status = RUNNING（正常）或 STOPPED（已停止，需先启动）
+```
+
+根据查询结果：
+- 找到 `type = GENERAL` 且 `status = RUNNING` 的集群名称，用于 `vcluster <name>`
+- 如果目标集群 `status = STOPPED`，先执行：`ALTER VCLUSTER <name> RESUME;`
+- 如果没有 GP 型集群，需先创建：参考 `clickzetta-vcluster-manager` skill
+
+> ⚠️ 不要用 `type = ANALYSIS`（AP 型）的集群创建动态表，AP 型不支持小文件合并，长期运行会导致查询性能下降。
+
 ## 快速入门
 
 ```sql
@@ -51,8 +70,44 @@ SHOW TABLES IN silver WHERE table_name = 'orders_daily';
 
 INTERVAL 支持的单位：`SECOND`、`MINUTE`、`HOUR`、`DAY`，最小值为 1 分钟。
 
-> 建议使用 GP 型集群刷新动态表。动态表刷新过程中会自动执行小文件合并，AP 型集群不支持此功能。
-> ⚠️ **VCluster 类型限制**：创建动态表时如果指定了 AP 型集群（如 `default_ap`），刷新仍可执行但不会进行小文件合并，长期运行可能导致查询性能下降。建议始终使用 GP 型集群（如 `default`）。
+> ⚠️ **VCluster 类型**：始终使用 GP 型集群（`vcluster default`），不要用 AP 型（`default_ap`）。AP 型集群不支持小文件合并，长期运行会导致查询性能下降。
+
+### ⚠️ 刷新周期的时间基准
+
+**`REFRESH INTERVAL N DAY/HOUR` 以动态表的创建时间（或上次刷新时间）为基准计算下次触发时间，不是从零点或整点开始对齐。**
+
+例如：动态表在 23:17 创建，设置 `REFRESH INTERVAL 1 DAY`，则后续每次刷新约在 23:17 触发，而不是次日 00:00 或业务期望的 03:00。`START WITH TIMESTAMP` 仅影响首次刷新时间，不改变后续周期的基准。
+
+**如需控制刷新时间窗口，有三种方案：**
+
+1. **在目标时间点附近创建动态表**（最简单）
+2. **创建后立即执行 `REFRESH` 重置基准**（推荐，见下方最佳实践）
+3. **改用短间隔**（如 `4 HOUR`）减少偏差，业务容忍度允许时可接受
+
+### 创建动态表的最佳实践：创建后立即执行首次刷新
+
+```sql
+-- ✅ 推荐写法：创建后立即 REFRESH，重置刷新基准时间，实现"开箱即用"
+CREATE DYNAMIC TABLE IF NOT EXISTS dws.user_order_daily
+REFRESH INTERVAL 1 DAY vcluster default
+AS
+SELECT user_id, DATE(created_at) AS dt, COUNT(*) AS order_cnt
+FROM dwd.fact_orders
+GROUP BY 1, 2;
+
+REFRESH DYNAMIC TABLE dws.user_order_daily;
+-- 立即触发首次计算，同时将刷新基准时间重置为当前时刻
+```
+
+### 手动刷新命令
+
+```sql
+-- ✅ 推荐：手动触发刷新
+REFRESH DYNAMIC TABLE schema.table_name;
+
+-- ⚠️ 不推荐：ALTER DYNAMIC TABLE ... REFRESH 语法不标准，建议使用上面的 REFRESH 命令
+-- ALTER DYNAMIC TABLE schema.table_name REFRESH;
+```
 
 ### 开启增量刷新的前提
 
@@ -110,3 +165,4 @@ Dynamic Table 最佳实践与避坑指南（维度表 JOIN 场景、性能优化
 | 状态表损坏 | 系统异常 | `SET cz.optimizer.incremental.rebuild.rule.based.state.table = true` |
 | 手动 REFRESH 后历史未显示 | 刷新历史有短暂延迟 | 等待几秒后重新查询 `SHOW DYNAMIC TABLE REFRESH HISTORY` |
 | AP 集群刷新后查询变慢 | AP 集群不支持小文件合并 | 改用 GP 型集群（`CREATE OR REPLACE` 重建） |
+| 刷新时间与预期不符（如期望 03:00 实际 23:00） | REFRESH INTERVAL 以创建时间为基准，不对齐整点 | 在目标时间点附近创建 DT，或创建后立即执行 `REFRESH DYNAMIC TABLE` 重置基准 |

package/bin/skills/clickzetta-dynamic-table/dynamic-table-alter/SKILL.md

@@ -12,7 +12,7 @@ description: |
 ## 指令
 
 ### 步骤 1：确认动态表存在并获取当前定义
-使用 `read_query` 执行 `SHOW CREATE TABLE schema_name.table_name` 获取动态表当前定义。
+执行 `SHOW CREATE TABLE schema_name.table_name` 获取动态表当前定义。
 如果不确定是否为动态表，先用 `SHOW TABLES WHERE is_dynamic` 查看列表。
 
 ### 步骤 2：判断操作类型并选择执行方式
@@ -69,11 +69,11 @@ ALTER DYNAMIC TABLE dt_name UNSET PROPERTIES('key');
 
 ### 步骤 3：执行 CREATE OR REPLACE 重建（仅 B 类操作）
 
-1. 用 `read_query` 执行 `SHOW CREATE TABLE schema_name.table_name` 获取原始 DDL
+1. 执行 `SHOW CREATE TABLE schema_name.table_name` 获取原始 DDL
    > ⚠️ `SHOW CREATE TABLE` 不支持 LIMIT/WHERE 子句，直接执行即可
 2. 解析出：列定义、REFRESH 子句、AS SELECT 子句、COMMENT 等
 3. 根据操作修改对应部分
-4. 用 `write_query` 执行重建 SQL
+4. 执行重建 SQL
 
 **关于全量刷新的触发**：
 - 简单的删除列 / 添加列（添加的列只是从源表 SELECT 透传，不参与 JOIN key、GROUP key 等计算）→ **增量刷新**
@@ -186,5 +186,5 @@ REFRESH DYNAMIC TABLE change_table;
 | `UNDROP DYNAMIC TABLE` 报错 | UNDROP 不支持 DYNAMIC TABLE 关键字 | 改为 `UNDROP TABLE dt_name` |
 | `DESC DYNAMIC TABLE ... EXTENDED` 报错 | 不支持 EXTENDED 参数 | 改为 `DESC TABLE dt_name`（不加 EXTENDED） |
 | UPDATE/DELETE 报 "MV__KEY" 相关错误 | 动态表有隐藏列 MV__KEY，默认禁止 DML | 先执行 `SET cz.sql.dt.allow.dml = true;` |
-| CREATE OR REPLACE 后数据为空 | AS SELECT 子句引用的源表或列不正确 | 先用 `read_query` 验证 SELECT 子句 |
+| CREATE OR REPLACE 后数据为空 | AS SELECT 子句引用的源表或列不正确 | 先验证 SELECT 子句是否返回数据 |
 | CREATE OR REPLACE 后全量刷新 | 新增列参与了计算逻辑（JOIN key、GROUP key 等） | 预期行为，等待全量刷新完成 |

package/bin/skills/clickzetta-external-catalog/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: clickzetta-external-catalog
+description: |
+  配置和使用 ClickZetta Lakehouse External Catalog，实现对 Hive、Iceberg、Databricks、
+  Snowflake Open Catalog 等外部数据源的联邦查询（只读）。覆盖完整创建流程：存储连接 →
+  Catalog Connection → External Catalog，以及 SHOW/DESC/查询外部表等操作。
+  支持数据源：Hive（OSS/COS/S3/HDFS）、Databricks Unity Catalog、
+  Snowflake Open Catalog（通过 Iceberg，OAuth 认证）。
+  当用户说"外部数据目录"、"External Catalog"、"联邦查询"、"Hive 联邦"、
+  "访问 Hive 数据"、"Databricks 联邦"、"Iceberg 联邦"、"跨数据源查询"、
+  "不迁移数据直接查询"、"Catalog Connection"、"Snowflake 联邦"、
+  "访问 Snowflake 数据"时触发。
+  Keywords: external catalog, Hive, Iceberg, Databricks, Snowflake, federation, read-only
+---
+
+# ClickZetta External Catalog
+
+> ⚠️ 创建 External Catalog 需要 `instance_admin` 角色。查询权限可通过 GRANT 授予其他用户。
+
+阅读 [references/external-catalog-ddl.md](references/external-catalog-ddl.md) 了解完整语法。
+
+## 概述
+
+External Catalog 让 Lakehouse 可以**不迁移数据**，直接对外部数据系统（Hive、Iceberg、Databricks）执行只读联邦查询。
+
+**支持数据源**：Apache Hive · Iceberg REST Catalog · Databricks Unity Catalog
+
+---
+
+## 创建流程（三步）
+
+### 步骤 1：创建存储连接
+
+```sql
+-- 阿里云 OSS
+CREATE STORAGE CONNECTION IF NOT EXISTS catalog_storage_oss
+  TYPE OSS
+  ACCESS_ID = 'LTAIxxxxxxxxxxxx'
+  ACCESS_KEY = 'T8Gexxxxxxmtxxxxxx'
+  ENDPOINT = 'oss-cn-hangzhou-internal.aliyuncs.com';
+```
+
+### 步骤 2：创建 Catalog Connection
+
+```sql
+CREATE CATALOG CONNECTION IF NOT EXISTS hive_catalog_conn
+  TYPE hms
+  hive_metastore_uris = 'hms-host:9083'
+  storage_connection = 'catalog_storage_oss';
+```
+
+### 步骤 3：创建 External Catalog
+
+```sql
+-- ⚠️ CREATE EXTERNAL CATALOG 不支持 COMMENT 子句，加了会报错
+-- ❌ 错误：CREATE EXTERNAL CATALOG my_hive_catalog CONNECTION hive_catalog_conn COMMENT '...';
+-- ✅ 正确：
+CREATE EXTERNAL CATALOG my_hive_catalog
+  CONNECTION hive_catalog_conn;
+
+-- 如需带选项（如 Iceberg REST）：
+CREATE EXTERNAL CATALOG my_iceberg_catalog
+  CONNECTION iceberg_conn
+  OPTIONS ('key1' = 'value1', 'key2' = 'value2');
+```
+
+---
+
+## 验证连通性
+
+```sql
+-- 查看 Schema 列表（验证连通）
+SHOW SCHEMAS IN my_hive_catalog;
+
+-- 查看表列表
+SHOW TABLES IN my_hive_catalog.my_schema;
+
+-- 查询数据
+SELECT * FROM my_hive_catalog.my_schema.my_table LIMIT 10;
+```
+
+---
+
+## 查看与管理
+
+```sql
+-- 列出所有 Catalog
+SHOW CATALOGS;
+
+-- 查看 Catalog 详情
+DESC CATALOG my_hive_catalog;
+
+-- 查看表结构
+DESC TABLE my_hive_catalog.my_schema.my_table;
+
+-- 删除 Catalog
+DROP CATALOG IF EXISTS my_hive_catalog;
+```
+
+---
+
+## 联邦查询示例
+
+```sql
+-- 外部 Hive 表 JOIN 内部 Lakehouse 表
+SELECT h.order_id, h.amount, d.region_name
+FROM my_hive_catalog.sales.orders h
+JOIN public.dim_region d ON h.region_id = d.id
+WHERE h.order_date >= '2024-01-01';
+```
+
+⚠️ 必须使用三层命名空间语法：`catalog.schema.table`
+
+---
+
+## 常见问题
+
+| 问题 | 原因 | 解决方案 |
+|---|---|---|
+| 无法连接 HMS | 网络未打通 | 通过 PrivateLink 打通 Lakehouse 与 HMS 服务器网络 |
+| 权限不足 | 非 instance_admin | 联系管理员授予 instance_admin 角色 |
+| 查询报错找不到表 | 未使用三层语法 | 使用 `catalog.schema.table` 格式 |
+| Databricks 连接失败 | 不在同一云平台 | 确保 Databricks 存储与 Lakehouse 在同一云平台 |

package/bin/skills/clickzetta-external-catalog/eval_cases.jsonl

@@ -0,0 +1,5 @@
+{"case_id":"001","type":"should_call","user_input":"怎么在 ClickZetta 里直接查询 Hive 的数据？","expected_skill":"clickzetta-external-catalog","expected_output_contains":["External Catalog","CREATE CATALOG CONNECTION"]}
+{"case_id":"002","type":"should_call","user_input":"怎么创建 External Catalog 连接 Iceberg REST Catalog？","expected_skill":"clickzetta-external-catalog","expected_output_contains":["CREATE EXTERNAL CATALOG","iceberg"]}
+{"case_id":"003","type":"should_call","user_input":"联邦查询外部表的三层命名空间怎么写？","expected_skill":"clickzetta-external-catalog","expected_output_contains":["catalog.schema.table"]}
+{"case_id":"004","type":"should_call","user_input":"怎么不迁移数据直接查询 Databricks 的表？","expected_skill":"clickzetta-external-catalog","expected_output_contains":["Databricks","External Catalog"]}
+{"case_id":"005","type":"should_call","user_input":"创建 External Catalog 需要什么权限？","expected_skill":"clickzetta-external-catalog","expected_output_contains":["instance_admin"]}

package/bin/skills/clickzetta-external-catalog/references/external-catalog-ddl.md

@@ -0,0 +1,130 @@
+# External Catalog 参考
+
+> 来源：https://www.yunqi.tech/documents/external-catalog-summary 等
+
+> ⚠️ External Catalog 当前处于公开预览阶段。目前只有 instance admin 角色可以查询 Catalog。
+
+## 概述
+
+External Catalog 映射外部数据系统（Hive、Iceberg、Databricks）的数据库，使 Lakehouse 可对其执行**只读**联邦查询。
+
+**支持的数据源**：
+- Apache Hive（通过 Hive Metastore）
+- Iceberg REST Catalog（如 Snowflake OpenCatalog）
+- Databricks Unity Catalog
+
+---
+
+## 创建流程（以 Hive 为例）
+
+### 步骤 1：创建存储连接
+
+```sql
+-- OSS
+CREATE STORAGE CONNECTION IF NOT EXISTS catalog_storage_oss
+  TYPE OSS
+  ACCESS_ID = 'LTAIxxxxxxxxxxxx'
+  ACCESS_KEY = 'T8Gexxxxxxmtxxxxxx'
+  ENDPOINT = 'oss-cn-hangzhou-internal.aliyuncs.com';
+
+-- COS
+CREATE STORAGE CONNECTION IF NOT EXISTS catalog_storage_cos
+  TYPE COS
+  ACCESS_KEY = '<access_key>'
+  SECRET_KEY = '<secret_key>'
+  REGION = 'ap-shanghai'
+  APP_ID = '1310000503';
+
+-- S3
+CREATE STORAGE CONNECTION IF NOT EXISTS catalog_storage_s3
+  TYPE S3
+  ACCESS_KEY = '<access_key>'
+  SECRET_KEY = '<secret_key>'
+  REGION = 'us-east-1';
+```
+
+### 步骤 2：创建 Catalog Connection
+
+```sql
+-- Hive Metastore
+CREATE CATALOG CONNECTION IF NOT EXISTS catalog_api_connection
+  TYPE hms
+  hive_metastore_uris = 'host:9083'
+  storage_connection = 'catalog_storage_oss';
+```
+
+参数说明：
+- `type`：连接类型，目前支持 `hms`（Hive Metastore Service）
+- `hive_metastore_uris`：HMS 服务地址，格式 `host:port`，端口通常为 9083
+- `storage_connection`：已创建的存储连接名称
+
+### 步骤 3：创建 External Catalog
+
+```sql
+CREATE EXTERNAL CATALOG my_external_catalog
+  CONNECTION catalog_api_connection;
+```
+
+---
+
+## 查看 Catalog
+
+```sql
+-- 列出所有 Catalog
+SHOW CATALOGS;
+
+-- 查看 Catalog 详情
+DESC CATALOG my_external_catalog;
+DESC CATALOG EXTENDED my_external_catalog;
+```
+
+---
+
+## 查看 Catalog 下的对象
+
+```sql
+-- 查看 Schema 列表
+SHOW SCHEMAS IN my_external_catalog;
+
+-- 查看 Schema 列表（含类型：managed/external）
+SHOW SCHEMAS EXTENDED IN my_external_catalog;
+
+-- 查看表列表
+SHOW TABLES IN my_external_catalog.my_schema;
+
+-- 查看表结构
+DESC TABLE my_external_catalog.my_schema.my_table;
+```
+
+---
+
+## 查询外部数据
+
+```sql
+-- 三层命名空间语法（必须）
+SELECT * FROM my_external_catalog.my_schema.my_table;
+
+-- 联邦查询（外部表 JOIN 内部表）
+SELECT e.*, i.region
+FROM my_external_catalog.hive_schema.orders e
+JOIN public.dim_region i ON e.region_id = i.id;
+```
+
+⚠️ 查询 External Catalog 下的表**必须**使用三层结构语法（catalog.schema.table），不支持 `USE` 切换 catalog。
+
+---
+
+## 删除 Catalog
+
+```sql
+DROP CATALOG IF EXISTS my_external_catalog;
+```
+
+---
+
+## 注意事项
+
+- External Catalog 为**只读**，不支持写入操作
+- HMS 所在服务器网络需与 Lakehouse 打通（可通过 PrivateLink 实现）
+- 目前只有 `instance_admin` 角色可以创建和查询 External Catalog
+- Databricks Unity Catalog 要求与 Lakehouse 在同一云平台（如同在 AWS 上）