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

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

@@ -0,0 +1,260 @@
+# Dynamic Table 增量刷新历史查询指南
+
+查看 DT/MV 的增量刷新历史有三种方式，适用于不同场景。
+
+---
+
+## 方式一：SHOW DYNAMIC TABLE REFRESH HISTORY
+
+查看 DT 的刷新作业级别信息，包括每次刷新的状态、耗时、触发方式、刷新模式等。
+
+### 语法
+
+```sql
+-- 通过 WHERE 过滤（name 列匹配表名）
+SHOW DYNAMIC TABLE REFRESH HISTORY WHERE name = 'my_dt';
+
+-- 组合 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;
+```
+
+### 输出列
+
+| 列名 | 类型 | 说明 |
+|------|------|------|
+| 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
+-- 查看失败的刷新记录
+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

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

@@ -0,0 +1,190 @@
+---
+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：确认动态表存在并获取当前定义
+执行 `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. 执行 `SHOW CREATE TABLE schema_name.table_name` 获取原始 DDL
+   > ⚠️ `SHOW CREATE TABLE` 不支持 LIMIT/WHERE 子句，直接执行即可
+2. 解析出：列定义、REFRESH 子句、AS SELECT 子句、COMMENT 等
+3. 根据操作修改对应部分
+4. 执行重建 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 子句引用的源表或列不正确 | 先验证 SELECT 子句是否返回数据 |
+| CREATE OR REPLACE 后全量刷新 | 新增列参与了计算逻辑（JOIN key、GROUP key 等） | 预期行为，等待全量刷新完成 |

package/bin/skills/clickzetta-dynamic-table/eval_cases.jsonl

@@ -0,0 +1,5 @@
+{"case_id":"001","type":"should_call","user_input":"帮我创建一个 Dynamic Table，从 public.dim_studio_user_dmin_f 聚合按租户+日期统计用户数，每 60 分钟自动刷新","expected_skill":"clickzetta-dynamic-table","expected_output_contains":["DYNAMIC TABLE","REFRESH"]}
+{"case_id":"002","type":"should_call","user_input":"怎么查看动态表的刷新历史和状态","expected_skill":"clickzetta-dynamic-table","expected_output_contains":["REFRESH HISTORY"]}
+{"case_id":"003","type":"should_call","user_input":"动态表的增量刷新怎么配置？SESSION_CONFIGS 怎么用？","expected_skill":"clickzetta-dynamic-table","expected_output_contains":["SESSION_CONFIGS","增量"]}
+{"case_id":"004","type":"should_call","user_input":"静态分区 DT 和动态分区 DT 有什么区别？该怎么选？","expected_skill":"clickzetta-dynamic-table","expected_output_contains":["静态分区","动态分区"]}
+{"case_id":"005","type":"should_call","user_input":"动态表怎么修改刷新间隔和 vcluster？","expected_skill":"clickzetta-dynamic-table","expected_output_contains":["ALTER","DYNAMIC TABLE"]}

package/bin/skills/clickzetta-dynamic-table/sql-to-dt/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: sql-to-dt
+description: 将 Hive/Spark 等任意批处理系统的 CREATE TABLE DDL + INSERT OVERWRITE SQL 自动转换为 Dynamic Table DDL 及配套文件（refresh、prev_refresh、backfill）。当用户提供 DDL 和 INSERT OVERWRITE 要求转换为 DT 时触发，或用户说"创建动态表"时主动引导提供输入。Triggers on: "转换DT", "sql to dt", "convert to dynamic table", "INSERT OVERWRITE 转 DT", "DDL 转换", "创建动态表"
+---
+
+# SQL → Dynamic Table 自动转换
+
+将 Hive/Spark 等任意批处理系统的 ETL SQL（CREATE TABLE + INSERT OVERWRITE）转换为 Dynamic Table DDL 及配套运维文件。
+
+## 使用方式
+
+提供以下输入：
+1. CREATE TABLE DDL（表结构定义）
+2. INSERT OVERWRITE SQL（ETL 查询逻辑）
+
+转换工具会自动完成：占位符替换、自引用检测、核心转换、列校验、配套文件生成、转换后改进建议。
+
+详细工作流参见 #[[file:references/sql2dt-workflow.md]]
+
+## references/
+
+- **sql2dt-workflow.md** — 完整转换工作流（6 步：预处理、占位符替换、自引用检测、核心转换、列校验、配套文件生成）
+- **sql2dt-conversion-rules.md** — 核心 DDL 转换规则（解析 DDL、解析 INSERT、组装 DT DDL、静态分区注入）
+- **sql2dt-placeholder-rules.md** — 占位符替换规则（${var} → SESSION_CONFIGS()）
+- **sql2dt-self-reference-rules.md** — 自引用表转换规则
+- **sql2dt-column-validation-rules.md** — 列校验规则（schema 列数 = SELECT 列数）
+- **sql2dt-refresh-rules.md** — Refresh 与调度文件生成规则

package/bin/skills/clickzetta-dynamic-table/sql-to-dt/references/sql2dt-column-validation-rules.md

@@ -0,0 +1,118 @@
+# Dynamic Table 列校验与一致性规则
+
+你是一个 SQL 转换专家。在生成 Dynamic Table DDL 后，需要校验 schema 定义的列与 SELECT 查询产出的列是否一致。
+
+## 列数校验（必须通过）
+
+### 规则
+
+生成的 DDL 中，括号内定义的列数必须等于 AS 后面 SELECT 查询产出的列数。
+
+```sql
+CREATE OR REPLACE DYNAMIC TABLE t (
+    col1 BIGINT,    -- 1
+    col2 STRING,    -- 2
+    dt STRING       -- 3  → schema 列数 = 3
+)
+AS
+SELECT col1, col2, '2024-01-01' AS dt  -- → SELECT 列数 = 3 ✓
+FROM source;
+```
+
+### SELECT 列数计算
+
+1. 找到 AS 后面的 SELECT 子句
+2. 找到顶层 FROM（不在子查询/括号内的 FROM）
+3. 计算 SELECT 和 FROM 之间的顶层逗号数 + 1 = 列数
+4. 顶层逗号：不在括号 `()`、方括号 `[]`、引号 `''`/`""` 内的逗号
+
+### UNION ALL 的列数
+
+取第一个分支的列数（所有分支列数应一致）。
+
+### 校验失败
+
+如果 schema 列数 ≠ SELECT 列数，转换失败，报错：
+```
+Schema列数(N) != SELECT列数(M)
+```
+
+## 列名校验（可选）
+
+### 规则
+
+逐位对比 schema 中的列名与 SELECT 中推断出的别名。建议在列数校验通过后，如果 SELECT 中大部分列都有明确别名（AS 或裸标识符），开启列名校验做二次确认。
+
+### SELECT 列别名推断
+
+按优先级从高到低：
+
+1. **AS 别名**：`expression AS alias` → 别名为 `alias`
+2. **末尾标识符**：`table.column` → 别名为 `column`
+3. **裸标识符**：`column_name` → 别名为 `column_name`
+4. **无法推断**：`func(a, b)` 没有 AS → 标记为 `<expr>`，跳过校验
+
+### 对比规则
+
+- 逐位对比（第1列对第1列，第2列对第2列...）
+- 如果某位是 `<expr>`（无法推断），跳过该位
+- 对比不区分大小写
+- 不匹配时报错并列出具体不对齐的列
+
+## 静态分区注入后的列数
+
+注入静态分区列后，SELECT 列数会增加。校验应在注入后进行。
+
+### 避免重复注入
+
+在注入前检查 SELECT 中是否已包含该分区列：
+
+1. 解析 SELECT 中每个表达式的最终别名
+2. 如果别名（不区分大小写）与分区列名匹配 → 该列已存在，跳过注入
+3. 只注入 SELECT 中不存在的分区列
+
+## UNION ALL 一致性
+
+### 分支列数一致性
+
+所有 UNION ALL 分支的列数必须相同。如果不一致，记录警告：
+```
+UNION分支列数不一致: [12, 13, 12]
+```
+
+### 注入后复核
+
+静态分区注入后，再次检查各分支列数是否一致：
+```
+注入后UNION各分支列数: [13, 13, 13]
+```
+
+## 重复别名检测
+
+如果 SELECT 中有重复的列别名，记录警告：
+```
+检测到重复列别名: ['dt']
+```
+
+重复别名可能导致：
+- 列数看起来正确但实际语义错误
+- 下游查询引用歧义
+
+## 缺失分区列检测
+
+如果 SELECT 中缺少某些分区列（注入前），记录信息：
+```
+检测到缺失分区列: ['dt', 'ds']
+```
+
+这些列会在注入步骤中被自动添加。
+
+## 完整校验流程
+
+```
+1. 生成 DDL（含静态分区注入）
+2. 提取 schema 列数
+3. 提取 SELECT 列数
+4. 比较列数 → 不等则失败
+5. （可选）逐位对比列名 → 不匹配则失败
+```