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

package/bin/skills/clickzetta-dynamic-table/dt-creator/references/refresh-history-guide.md

@@ -1,268 +0,0 @@
-# Dynamic Table 增量刷新历史查询指南
-
-查看 DT/MV 的增量刷新历史有三种方式，适用于不同场景。
-
----
-
-## 方式一：SHOW DYNAMIC TABLE REFRESH HISTORY
-
-查看 DT 的刷新作业级别信息，包括每次刷新的状态、耗时、触发方式、刷新模式等。
-
-### 语法
-
-```sql
--- 查看指定 DT 的刷新历史（使用 WHERE name = 过滤）
-SHOW DYNAMIC TABLE REFRESH HISTORY WHERE name = 'my_dt';
-
--- 限制返回行数
-SHOW DYNAMIC TABLE REFRESH HISTORY WHERE name = 'my_dt' LIMIT 10;
-
--- 组合 WHERE + LIMIT + 状态过滤
-SHOW DYNAMIC TABLE REFRESH HISTORY WHERE name = 'my_dt' AND state = 'SUCCEED' LIMIT 20;
-
--- MV 也支持同样的语法
-SHOW MATERIALIZED VIEW REFRESH HISTORY WHERE name = 'my_mv' LIMIT 10;
-```
-
-> ⚠️ 注意：`FOR <table_name>` 语法在当前版本中可能返回空结果，请使用 `WHERE name = '<table_name>'` 语法。
-
-### 输出列
-
-| 列名 | 类型 | 说明 |
-|------|------|------|
-| workspace_name | STRING | 所属 Workspace |
-| schema_name | STRING | 所属 Schema |
-| name | STRING | DT/MV 名称 |
-| virtual_cluster | STRING | 执行刷新的虚拟集群 |
-| start_time | TIMESTAMP | 刷新开始时间 |
-| end_time | TIMESTAMP | 刷新结束时间（运行中为 NULL） |
-| duration | INTERVAL | 刷新耗时（运行中显示已经过的时间） |
-| state | STRING | 刷新状态（SUCCEED / FAILED / RUNNING 等） |
-| refresh_trigger | STRING | 触发方式：`SYSTEM_SCHEDULED`（系统调度自动触发）或 `MANUAL`（用户手动 REFRESH） |
-| refresh_mode | STRING | 刷新模式，见下方详细说明 |
-| error_message | STRING | 失败时的错误信息（成功时为 NULL） |
-| source_tables | ARRAY<MAP<STRING,STRING>> | 源表列表，每个元素是一个 MAP，包含 `workspace`、`schema`、`table_name` 三个 key |
-| stats | MAP<STRING,STRING> | 刷新统计，包含 `rows_inserted`（插入行数）和 `rows_deleted`（删除行数） |
-| job_id | STRING | 对应的 Job ID，可用于关联 `information_schema.job_history` 查更多详情 |
-
-### refresh_mode 详解
-
-`refresh_mode` 是判断增量计算是否生效的关键字段：
-
-| 值 | 含义 | 说明 |
-|----|------|------|
-| `INCREMENTAL` | 增量刷新 | 增量引擎成功生成了增量计划，只处理了源表的变更数据 |
-| `FULL` | 全量刷新 | 回退到全量重算。可能原因：首次刷新、维度表变更、增量计划生成失败、用户强制全量等 |
-| `NO_DATA` | 无数据变更 | 源表在上次刷新后没有新的数据变更，本次刷新跳过计算 |
-
-### source_tables 详解
-
-`source_tables` 列返回该次刷新涉及的所有输入表信息，每个元素是一个 MAP：
-
-```
-[
-  {"workspace": "my_ws", "schema": "public", "table_name": "orders"},
-  {"workspace": "my_ws", "schema": "public", "table_name": "dim_product"}
-]
-```
-
-### stats 详解
-
-`stats` 列返回该次刷新对目标表的写入统计：
-
-```
-{"rows_inserted": "1000", "rows_deleted": "50"}
-```
-
-- `rows_inserted`：本次刷新向目标表插入的行数
-- `rows_deleted`：本次刷新从目标表删除的行数（增量模式下，更新操作会产生 delete + insert）
-
-### 典型用法
-
-```sql
--- 查看最近 5 次刷新是否成功
-SHOW DYNAMIC TABLE REFRESH HISTORY WHERE name = 'my_dt' LIMIT 5;
-
--- 查看失败的刷新记录
-SHOW DYNAMIC TABLE REFRESH HISTORY WHERE name = 'my_dt' AND state = 'FAILED';
-
--- 查看是否回退到了全量刷新（排查增量是否生效）
-SHOW DYNAMIC TABLE REFRESH HISTORY WHERE name = 'my_dt' AND refresh_mode = 'FULL';
-
--- 查看无数据变更的刷新（源表没有新数据时会出现）
-SHOW DYNAMIC TABLE REFRESH HISTORY WHERE name = 'my_dt' AND refresh_mode = 'NO_DATA';
-
--- 查看系统自动调度的刷新
-SHOW DYNAMIC TABLE REFRESH HISTORY WHERE name = 'my_dt' AND refresh_trigger = 'SYSTEM_SCHEDULED';
-```
-
----
-
-## 方式二：DESC HISTORY
-
-查看表的版本级别历史，包括每个版本的行数、字节数、操作类型等。适用于了解数据变更粒度。
-
-### 语法
-
-```sql
--- 查看 DT 的版本历史
-DESC HISTORY my_dt;
-
--- 查看源表的版本历史
-DESC HISTORY source_table;
-
--- 支持 WHERE 过滤
-DESC HISTORY my_dt WHERE version > 10;
-
--- 支持 LIMIT
-DESC HISTORY my_dt LIMIT 20;
-```
-
-### 输出列
-
-对于普通表（DESC_TABLE_HISTORY）：
-
-| 列名 | 类型 | 说明 |
-|------|------|------|
-| sequence | BIGINT | 序列号 |
-| version | BIGINT | 版本号 |
-| time | TIMESTAMP | 版本创建时间 |
-| total_rows | BIGINT | 该版本的总行数 |
-| total_bytes | BIGINT | 该版本的总字节数 |
-| user | STRING | 操作用户 |
-| operation | STRING | 操作类型（INSERT / COMPACTION / REFRESH 等） |
-| job_id | STRING | 对应的 Job ID |
-
-对于 DT/MV（DESC_MV_HISTORY），额外包含：
-
-| 列名 | 类型 | 说明 |
-|------|------|------|
-| source_tables | ARRAY<MAP<STRING,STRING>> | 源表及其对应的版本信息 |
-
-DESC HISTORY 对 DT/MV 的 `source_tables` 比 SHOW REFRESH HISTORY 更详细，包含每个源表在该版本对应的快照信息：
-
-```
-[
-  {"table_name": "orders", "workspace": "my_ws", "schema": "public", "version": "123", "sequence": "5", "commit_time": "2025-01-15 10:30:00"},
-  {"table_name": "dim_product", "workspace": "my_ws", "schema": "public", "version": "456", "sequence": "2", "commit_time": "2025-01-15 08:00:00"}
-]
-```
-
-- `version`：源表的 snapshot_id
-- `sequence`：源表的 sequence 号
-- `commit_time`：源表该版本的提交时间
-
-这些信息可以用来追溯某次刷新读取了源表的哪个版本数据。
-
-### 典型用法
-
-```sql
--- 查看 DT 最近的版本变化，确认 compaction 是否正常执行
-DESC HISTORY my_dt LIMIT 10;
-
--- 查看源表的版本历史，判断数据写入频率
-DESC HISTORY source_table LIMIT 20;
-
--- 查看 DT 的 compaction 记录
-DESC HISTORY my_dt WHERE operation = 'COMPACTION';
-```
-
----
-
-## 方式三：information_schema.materialized_view_refresh_history
-
-从 information_schema 查询刷新历史，适合跨表批量分析、与其他系统集成、或做长期趋势监控。数据按天分区（pt_date），保留天数由系统配置决定。
-
-### 语法
-
-```sql
--- 查看指定 DT 的刷新历史
-SELECT *
-FROM information_schema.materialized_view_refresh_history
-WHERE materialized_view_name = 'my_dt'
-ORDER BY start_time DESC
-LIMIT 10;
-
--- 查看某天所有 DT 的刷新情况
-SELECT materialized_view_name, status, start_time, end_time, error_message
-FROM information_schema.materialized_view_refresh_history
-WHERE pt_date = '2025-01-15'
-ORDER BY start_time DESC;
-
--- 查看失败的刷新
-SELECT materialized_view_name, error_code, error_message, start_time
-FROM information_schema.materialized_view_refresh_history
-WHERE status = 'FAILED' AND pt_date >= '2025-01-01'
-ORDER BY start_time DESC;
-```
-
-### 输出列
-
-| 列名 | 类型 | 说明 |
-|------|------|------|
-| workspace_name | STRING | 所属 Workspace |
-| schema_name | STRING | 所属 Schema |
-| materialized_view_name | STRING | DT/MV 名称 |
-| cru | DOUBLE | 消耗的计算资源单位 |
-| virtual_cluster_name | STRING | 执行刷新的虚拟集群 |
-| status | STRING | 刷新状态 |
-| scheduled_start_time | TIMESTAMP | 计划开始时间 |
-| start_time | TIMESTAMP | 实际开始时间 |
-| end_time | TIMESTAMP | 结束时间 |
-| error_code | STRING | 错误码 |
-| error_message | STRING | 错误信息 |
-| pt_date | STRING | 分区日期 |
-
-### 典型用法
-
-```sql
--- 统计某个 DT 最近 7 天的刷新成功率
-SELECT
-    pt_date,
-    COUNT(*) AS total,
-    SUM(CASE WHEN status = 'SUCCEED' THEN 1 ELSE 0 END) AS success,
-    SUM(CASE WHEN status = 'FAILED' THEN 1 ELSE 0 END) AS failed
-FROM information_schema.materialized_view_refresh_history
-WHERE materialized_view_name = 'my_dt'
-  AND pt_date >= DATE_FORMAT(DATEADD(DAY, -7, CURRENT_DATE()), '%Y-%m-%d')
-GROUP BY pt_date
-ORDER BY pt_date;
-
--- 查看消耗 CRU 最多的刷新
-SELECT materialized_view_name, cru, start_time, end_time
-FROM information_schema.materialized_view_refresh_history
-WHERE pt_date >= '2025-01-01'
-ORDER BY cru DESC
-LIMIT 10;
-```
-
-### 与 information_schema.job_history 的区别
-
-`information_schema.job_history` 记录所有类型的 Job（SQL 查询、DML、DDL 等），而 `materialized_view_refresh_history` 专门记录 DT/MV 的刷新历史，字段更有针对性。
-
-如果需要查看刷新 Job 的完整信息（如 job_text、input_bytes 等），可以通过 job_id 关联：
-
-```sql
--- 通过 SHOW DYNAMIC TABLE REFRESH HISTORY 获取 job_id，再到 job_history 查详情
-SELECT *
-FROM information_schema.job_history
-WHERE job_id = '<从 SHOW REFRESH HISTORY 获取的 job_id>'
-  AND pt_date = '2025-01-15';
-```
-
----
-
-## 三种方式对比
-
-| 特性 | SHOW REFRESH HISTORY | DESC HISTORY | information_schema |
-|------|---------------------|--------------|-------------------|
-| 粒度 | 刷新作业级别 | 表版本级别 | 刷新作业级别 |
-| 刷新模式（增量/全量/无数据） | ✅ refresh_mode | ❌ | ❌ |
-| 触发方式（调度/手动） | ✅ refresh_trigger | ❌ | ❌ |
-| 写入统计（inserted/deleted） | ✅ stats | ❌ | ❌ |
-| 源表列表 | ✅ 表名级别 | ✅ 含版本/sequence/commit_time | ❌ |
-| 版本号/总行数/总字节数 | ❌ | ✅ version/total_rows/total_bytes | ❌ |
-| CRU 消耗 | ❌ | ❌ | ✅ cru |
-| 跨表批量查询 | ❌（单表） | ❌（单表） | ✅（可批量） |
-| compaction 记录 | ❌ | ✅ | ❌ |
-| 适用场景 | 排查增量是否生效、刷新状态 | 查看数据版本变化、追溯源表版本 | 批量分析/监控/CRU 统计 |

package/bin/skills/clickzetta-dynamic-table/dt-creator/references/sql-limitations.md

@@ -1,80 +0,0 @@
-# Dynamic Table SQL 限制与支持矩阵
-
-本文档列出 Dynamic Table 增量计算支持和不支持的 SQL 模式。
-
-## JOIN 类型支持
-
-| JOIN 类型 | 增量支持 | 说明 |
-|-----------|---------|------|
-| INNER JOIN | ✅ | 完全支持 |
-| LEFT JOIN (LEFT OUTER) | ✅ | 完全支持 |
-| RIGHT JOIN (RIGHT OUTER) | ✅ | 完全支持 |
-| FULL OUTER JOIN | ✅ | 完全支持 |
-| LEFT SEMI JOIN | ✅ | 完全支持 |
-| LEFT ANTI JOIN | ✅ | 完全支持 |
-
-## 聚合函数支持
-
-### 支持增量计算的聚合函数
-
-- `SUM`, `SUM0`, `COUNT`, `COUNT_IF`, `MIN`, `MAX`, `MIN_BY`, `MAX_BY`
-- `AVG`, `STDDEV_SAMP`, `STDDEV_POP`, `VAR_SAMP`, `VAR_POP`
-- `Percentile`, `Median`, `COUNT_DISTINCT`
-- `BIT_OR`, `BIT_AND`, `BIT_XOR`, `BOOL_OR`, `BOOL_AND`
-- `GROUP_BITMAP` 系列
-- `COLLECT_SET`, `COLLECT_LIST`, `COLLECT_SET_ON_ARRAY`, `COLLECT_LIST_ON_ARRAY`
-- `MAP_AGG`, `WM_CONCAT`
-
-### 结果不稳定的聚合函数（增量结果可能与全量不一致）
-
-- `ANY_VALUE`, `FIRST_VALUE`, `LAST_VALUE`
-- `APPROX_COUNT_DISTINCT`, `APPROX_HISTOGRAM`, `APPROX_TOP_K`, `APPROX_PERCENTILE`
-- `JSON_MERGE_AGG`
-
-## 窗口函数支持
-
-### 支持的窗口函数
-
-- `ROW_NUMBER`, `RANK`, `DENSE_RANK`, `PERCENT_RANK`
-- `FIRST_VALUE`, `LAST_VALUE`, `NTH_VALUE`
-- `COUNT`, `SUM`, `SUM0`, `MIN`, `MAX`, `AVG`
-- `LEAD`, `LAG`, `CUME_DIST`, `NTILE`
-- `COLLECT_LIST`, `COLLECT_SET`, `COLLECT_SET_ON_ARRAY`, `COLLECT_LIST_ON_ARRAY`
-
-## ORDER BY / LIMIT / OFFSET
-
-支持 `ORDER BY`、`LIMIT`、`OFFSET` 语法。
-
-⚠️ 不建议在 DT 中使用全局 `ORDER BY`。全局排序在每次增量刷新时开销非常大，推荐将排序逻辑放在下游查询数据时执行，而非 ETL 建模阶段。
-
-## 非确定性函数
-
-非确定性函数（如 `NOW()`、`CURRENT_TIMESTAMP`、`CURRENT_DATE`、`random()` 等）在不参与计算逻辑时默认支持。具体来说，只要这些函数不出现在以下位置，就可以正常使用：
-- 窗口函数的 `PARTITION BY` key
-- `JOIN` key
-- `GROUP BY` key
-- 其他函数的入参
-
-典型场景：在 SELECT 中直接输出数据处理时间，记录每条数据被 DT 刷新处理的时刻：
-
-```sql
-CREATE DYNAMIC TABLE order_with_process_time AS
-SELECT
-    id,
-    amount,
-    status,
-    CURRENT_TIMESTAMP AS process_time  -- 记录刷新时的处理时间，直接输出到目标表
-FROM orders
-WHERE status = 'completed';
-```
-
-时间函数会在每次 REFRESH 时被常量折叠为当次刷新的时间戳。
-
-## UDF / UDAF / UDTF
-
-自定义函数需要在创建时声明为确定性函数（deterministic），才能在 DT 中使用增量计算。未声明确定性的自定义函数会导致增量计算被禁用。
-
-## 源表类型限制
-
-- **虚拟视图（VIEW）**：不能作为 DT 的输入表，会禁用增量计算
-- **外部表（External Table）**：不支持增量计算

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

@@ -1,190 +0,0 @@
----
-name: dynamic-table-alter
-description: |
-  修改 ClickZetta 动态表（Dynamic Table）的结构和属性。支持直接 ALTER 操作（suspend、resume、
-  rename_column、set_comment、set_column_comment、set/unset properties）以及 CREATE OR REPLACE
-  重建操作（修改调度周期、计算集群、加列、减列、改列类型、改 SQL 定义）。当用户说"修改动态表"、
-  "动态表加列"、"改刷新间隔"、"暂停动态表"时触发。
----
-
-# 动态表修改工作流
-
-## 指令
-
-### 步骤 1：确认动态表存在并获取当前定义
-使用 `read_query` 执行 `SHOW CREATE TABLE schema_name.table_name` 获取动态表当前定义。
-如果不确定是否为动态表，先用 `SHOW TABLES WHERE is_dynamic` 查看列表。
-
-### 步骤 2：判断操作类型并选择执行方式
-
-ClickZetta 动态表的修改操作分为两类：
-
-**A. 直接 ALTER 操作**（6种，可直接执行）：
-
-1. **suspend** — 暂停调度任务：
-```sql
-ALTER DYNAMIC TABLE dt_name SUSPEND;
-```
-
-2. **resume** — 启动调度任务：
-```sql
-ALTER DYNAMIC TABLE dt_name RESUME;
-```
-
-3. **set_comment** — 修改表注释：
-```sql
-ALTER DYNAMIC TABLE dt_name SET COMMENT 'comment';
-```
-
-4. **rename_column** — 修改列名：
-```sql
-ALTER DYNAMIC TABLE dt_name RENAME COLUMN old_name TO new_name;
-```
-
-5. **set_column_comment** — 修改列注释（注意用 CHANGE COLUMN）：
-```sql
-ALTER DYNAMIC TABLE dt_name CHANGE COLUMN column_name COMMENT 'comment';
-```
-
-6. **set/unset properties** — 修改表属性（目前为保留参数）：
-```sql
--- 设置属性
-ALTER DYNAMIC TABLE dt_name SET PROPERTIES('key' = 'value');
--- 删除属性
-ALTER DYNAMIC TABLE dt_name UNSET PROPERTIES('key');
-```
-
-**B. CREATE OR REPLACE 操作**（6种，需要重建动态表）：
-
-> ⚠️ **以下操作不支持 ALTER 语法**。`ALTER DYNAMIC TABLE ... SET REFRESH INTERVAL` 等语法不存在，会报语法错误。必须使用 `CREATE OR REPLACE DYNAMIC TABLE` 重建。
-
-这些操作涉及 SQL 查询逻辑变化，无法通过 ALTER 直接完成：
-
-7. **修改调度周期** — ❌ 不支持 `ALTER ... SET REFRESH INTERVAL`
-8. **修改计算集群** — ❌ 不支持 `ALTER ... SET VCLUSTER`
-9. **增加列**
-10. **减列**
-11. **修改列类型**
-12. **修改 SQL 定义**
-
-### 步骤 3：执行 CREATE OR REPLACE 重建（仅 B 类操作）
-
-1. 用 `read_query` 执行 `SHOW CREATE TABLE schema_name.table_name` 获取原始 DDL
-   > ⚠️ `SHOW CREATE TABLE` 不支持 LIMIT/WHERE 子句，直接执行即可
-2. 解析出：列定义、REFRESH 子句、AS SELECT 子句、COMMENT 等
-3. 根据操作修改对应部分
-4. 用 `write_query` 执行重建 SQL
-
-**关于全量刷新的触发**：
-- 简单的删除列 / 添加列（添加的列只是从源表 SELECT 透传，不参与 JOIN key、GROUP key 等计算）→ **增量刷新**
-- 涉及计算逻辑变化（修改 WHERE 条件、修改聚合逻辑、新增列参与计算等）→ **全量刷新**
-- 兼容类型变更（如 INT → BIGINT）→ **增量刷新**
-
-### 步骤 4：验证修改结果
-使用 `DESC TABLE dt_name` 确认修改生效。
-
----
-
-## 示例
-
-### 示例 1：修改调度周期
-
-```sql
--- 原表
-CREATE DYNAMIC TABLE dt_name
-REFRESH INTERVAL 10 MINUTE vcluster DEFAULT
-AS SELECT * FROM student02;
-
--- 修改后（改为 20 分钟）
-CREATE OR REPLACE DYNAMIC TABLE dt_name
-REFRESH INTERVAL 20 MINUTE vcluster DEFAULT
-AS SELECT * FROM student02;
-```
-
-### 示例 2：修改计算集群
-
-```sql
--- 原表
-CREATE DYNAMIC TABLE dt_name
-REFRESH INTERVAL 10 MINUTE vcluster DEFAULT
-AS SELECT * FROM student02;
-
--- 修改后（改为 alter_vc 集群）
-CREATE OR REPLACE DYNAMIC TABLE dt_name
-REFRESH INTERVAL 10 MINUTE vcluster alter_vc
-AS SELECT * FROM student02;
-```
-
-### 示例 3：增加列
-
-```sql
--- 原表
-CREATE DYNAMIC TABLE change_table (i, j)
-AS SELECT * FROM dy_base_a;
-
--- 添加一列 col（涉及计算逻辑，下次刷新会全量刷新）
-CREATE OR REPLACE DYNAMIC TABLE change_table (i, j, col)
-AS SELECT i, j, j * 1 FROM dy_base_a;
-
-REFRESH DYNAMIC TABLE change_table;
-```
-
-### 示例 4：减列
-
-```sql
--- 原表有 i, j 两列
-CREATE DYNAMIC TABLE change_table (i, j)
-AS SELECT * FROM dy_base_a;
-
--- 减列（简单透传，增量刷新）
-CREATE OR REPLACE DYNAMIC TABLE change_table (i)
-AS SELECT i FROM dy_base_a;
-```
-
-### 示例 5：修改 SQL 定义
-
-```sql
--- 修改 WHERE 过滤条件（全量刷新）
-CREATE OR REPLACE DYNAMIC TABLE change_table (i, j)
-AS SELECT * FROM dy_base_a WHERE i > 3;
-
-REFRESH DYNAMIC TABLE change_table;
-```
-
-### 示例 6：修改列类型
-
-```sql
--- INT → BIGINT（兼容类型，增量刷新）
-CREATE OR REPLACE DYNAMIC TABLE change_table (i, j)
-AS SELECT CAST(i AS BIGINT), j FROM dy_base_a;
-
-REFRESH DYNAMIC TABLE change_table;
-```
-
----
-
-## 平台特有知识
-
-- **CHANGE COLUMN 语法**：设置列注释用 `CHANGE COLUMN col COMMENT 'xxx'`，不是 `ALTER COLUMN`
-- **RENAME COLUMN 语法**：`RENAME COLUMN old TO new`
-- **DML 限制**：动态表默认不支持 UPDATE/DELETE/MERGE（因隐藏列 MV__KEY），如需 DML 须先执行 `SET cz.sql.dt.allow.dml = true;`
-- **REFRESH 格式**：`REFRESH INTERVAL <N> MINUTE vcluster <name>`，支持 SECOND/MINUTE/HOUR/DAY
-- **CREATE OR REPLACE 风险**：涉及计算逻辑变化时会触发全量刷新，大表可能耗时较长
-- **schema 前缀**：所有 ALTER/CREATE 语句中表名应包含 schema 前缀
-- **列定义可省略类型**：`CREATE DYNAMIC TABLE dt (i, j) AS SELECT ...` 类型由 SELECT 推断
-- **DROP 语法**：必须用 `DROP DYNAMIC TABLE dt_name`，不能用 `DROP TABLE dt_name`（会报错）
-- **UNDROP 语法**：必须用 `UNDROP TABLE dt_name`，不能用 `UNDROP DYNAMIC TABLE dt_name`
-- **DESC 语法**：动态表用 `DESC TABLE dt_name`，不要写 `DESC DYNAMIC TABLE dt_name EXTENDED`（EXTENDED 不支持）
-
-## 故障排除
-
-| 错误 | 原因 | 解决方案 |
-|---|---|---|
-| ALTER 报 "Syntax error at or near 'REFRESH'" | `ALTER ... SET REFRESH INTERVAL` 语法不存在 | 使用 `CREATE OR REPLACE DYNAMIC TABLE ... REFRESH INTERVAL ...` 重建 |
-| ALTER 报 "unsupported operation" | 尝试对动态表执行 B 类操作的 ALTER 语法 | 使用 CREATE OR REPLACE 重建 |
-| `DROP TABLE dt_name` 报错 | 动态表必须用 `DROP DYNAMIC TABLE` | 改为 `DROP DYNAMIC TABLE dt_name` |
-| `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 后全量刷新 | 新增列参与了计算逻辑（JOIN key、GROUP key 等） | 预期行为，等待全量刷新完成 |

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

@@ -1,120 +0,0 @@
----
-name: clickzetta-external-catalog
-description: |
-  配置和使用 ClickZetta Lakehouse External Catalog，实现对 Hive、Iceberg、Databricks 等
-  外部数据源的联邦查询（只读）。覆盖完整创建流程：存储连接 → Catalog Connection →
-  External Catalog，以及 SHOW/DESC/查询外部表等操作。
-  当用户说"外部数据目录"、"External Catalog"、"联邦查询"、"Hive 联邦"、
-  "访问 Hive 数据"、"Databricks 联邦"、"Iceberg 联邦"、"跨数据源查询"、
-  "不迁移数据直接查询"、"Catalog Connection"时触发。
-  Keywords: external catalog, Hive, Iceberg, Databricks, 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 在同一云平台 |