@clickzetta/cz-cli-linux-x64 0.3.10 → 0.3.12

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

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

@@ -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：确认动态表存在并获取当前定义
+使用 `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-file-import-pipeline/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: clickzetta-file-import-pipeline
+description: |
+  从 URL、本地文件或 Volume 路径将数据导入到 ClickZetta 表中，覆盖文件下载、格式推断、
+  表创建、COPY INTO 导入、结果验证的完整流程。当用户说"导入数据"、"从 URL 加载"、
+  "上传 CSV 到表"、"文件导入"、"COPY INTO"时触发。包含 ClickZetta USER VOLUME 机制、
+  COPY INTO 语法、格式推断规则、写入模式语义等平台特有知识。
+  Keywords: file import, URL, CSV, JSON, Parquet, COPY INTO, Volume
+---
+
+# URL/文件数据导入工作流
+
+## 指令
+
+### 步骤 1：获取源文件并上传到 Volume
+根据数据来源选择对应方式：
+- **HTTP/HTTPS URL**：需要先用外部工具下载到本地，然后用 `PUT` 命令上传到 User Volume
+- **本地文件**：执行 SQL `PUT '/local/path/file.csv' TO USER VOLUME` 上传
+- **Volume 路径**：文件已在 Volume 上，跳过此步骤
+- **外部 Volume（OSS/S3/COS）**：文件已在外部 Volume，直接使用
+- 记录上传后的 Volume 名称和文件名，后续步骤需要
+
+> ⚠️ **注意**：文件上传操作参考 `clickzetta-volume-manager` skill。
+
+### 步骤 2：推断文件格式
+根据文件扩展名推断格式（ClickZetta COPY INTO 支持的格式）：
+- `.csv`, `.tsv`, `.txt` → CSV 格式
+- `.json`, `.jsonl`, `.ndjson` → JSON 格式
+- `.parquet`, `.pq` → PARQUET 格式
+- `.orc` → ORC 格式
+- `.bson` → BSON 格式
+如果扩展名不明确，执行 `SELECT FROM VOLUME ... USING format` 预览文件内容来确认格式和 schema。
+
+### 步骤 3：确认或创建目标表
+根据写入模式处理目标表：
+- **create 模式**：表必须不存在。执行 `SELECT FROM VOLUME ... LIMIT 5` 推断 schema，然后执行 `CREATE TABLE` 创建表
+- **append 模式**：表必须已存在。用 `DESC TABLE <table_name>` 确认表存在并检查列兼容性
+- **overwrite 模式**：表存在则先清空。执行 `TRUNCATE TABLE table_name`，再执行 COPY INTO（⚠️ 不支持 `COPY OVERWRITE INTO` 语法）
+
+### 步骤 4：执行 COPY INTO 导入数据
+执行 COPY INTO 语句。核心语法：
+
+```sql
+COPY INTO target_table
+FROM VOLUME volume_name
+USING format_type
+OPTIONS('option_name' = 'value')
+FILES('filename');
+```
+
+对于 USER VOLUME（通过 PUT 命令上传的文件）：
+```sql
+COPY INTO target_table
+FROM USER VOLUME
+USING CSV
+OPTIONS('header' = 'true')
+FILES('uploaded_filename');
+```
+
+CSV 格式可附加 OPTIONS：
+```sql
+COPY INTO target_table
+FROM VOLUME vol
+USING CSV
+OPTIONS('header' = 'true', 'sep' = ',', 'quote' = '"', 'nullValue' = '')
+FILES('data.csv');
+```
+
+⚠️ **语法顺序要求**：`OPTIONS` 必须在 `FILES` 之前，否则报错 `Syntax error - missing EQ at '('`
+
+overwrite 模式（⚠️ 不支持 `COPY OVERWRITE INTO`）：
+```sql
+-- 正确方式：先 TRUNCATE 再 COPY
+TRUNCATE TABLE target_table;
+COPY INTO target_table FROM VOLUME vol USING CSV FILES('data.csv');
+```
+
+### 步骤 5：验证导入结果
+执行验证查询：
+```sql
+SELECT COUNT(*) as row_count FROM target_table;
+SELECT * FROM target_table LIMIT 5;
+```
+确认行数符合预期，数据内容正确。
+
+## 示例
+
+### 示例 1：从 URL 导入 CSV 到新表
+```sql
+-- 1. 下载 URL 文件到本地，然后上传到 User Volume
+PUT '/tmp/data.csv' TO USER VOLUME;
+
+-- 2. 预览文件内容推断 schema
+SELECT * FROM USER VOLUME USING CSV OPTIONS('header' = 'true') FILES('data.csv') LIMIT 5;
+-- 推断出列：id INT, name STRING, value DOUBLE
+
+-- 3. 创建目标表
+CREATE TABLE imported_data (id INT, name STRING, value DOUBLE);
+
+-- 4. 执行 COPY INTO 导入（注意：OPTIONS 必须在 FILES 之前）
+COPY INTO imported_data FROM USER VOLUME USING CSV OPTIONS('header' = 'true') FILES('data.csv');
+
+-- 5. 验证导入结果
+SELECT COUNT(*) FROM imported_data;
+```
+
+### 示例 2：追加 Parquet 数据到已有表
+```sql
+-- 1. 上传本地文件到 User Volume
+PUT '/local/new_batch.parquet' TO USER VOLUME;
+
+-- 2. 确认目标表存在
+DESC TABLE existing_table;
+
+-- 3. 执行 COPY INTO 导入（Parquet 格式通常不需要 OPTIONS）
+COPY INTO existing_table FROM USER VOLUME USING PARQUET FILES('new_batch.parquet');
+
+-- 4. 验证导入结果
+SELECT COUNT(*) FROM existing_table;
+```
+
+### 示例 3：从外部 Volume（OSS）导入
+```sql
+-- 1. 查看 Volume 中的文件列表
+SHOW VOLUME DIRECTORY my_oss_volume;
+
+-- 2. 预览文件内容
+SELECT * FROM VOLUME my_oss_volume USING CSV OPTIONS('header' = 'true') FILES('data.csv') LIMIT 5;
+
+-- 3. 创建目标表并导入（注意：OPTIONS 必须在 FILES 之前）
+CREATE TABLE imported_data (col1 INT, col2 STRING);
+COPY INTO imported_data FROM VOLUME my_oss_volume USING CSV OPTIONS('header' = 'true') FILES('data.csv');
+```
+
+## 故障排除
+
+| 错误 | 原因 | 解决方案 |
+|------|------|----------|
+| COPY INTO 报 "table not found" | create 模式下表未创建，或 append 模式下表名拼写错误 | 先用 `SHOW TABLES` 确认表是否存在 |
+| COPY INTO 报 "file not found" | FILES 中的文件名与 Volume 上的实际文件名不匹配 | 执行 `SHOW VOLUME DIRECTORY vol_name` 或 `SHOW USER VOLUME DIRECTORY` 确认文件名，注意大小写敏感 |
+| COPY INTO 报语法错误 "missing EQ at '('" | OPTIONS 放在了 FILES 之后 | 调整顺序，确保 `OPTIONS` 在 `FILES` 之前：`USING CSV OPTIONS(...) FILES(...)` |
+| CSV 导入列数不匹配 | CSV 文件有 header 行但未指定 `OPTIONS('header'='true')`，导致 header 被当作数据行 | 添加 `OPTIONS('header' = 'true')`，或检查 CSV 分隔符是否正确（sep 参数） |
+| COPY INTO 报 "schema mismatch" | 文件中的数据类型与目标表列定义不兼容 | 执行 `SELECT FROM VOLUME ... USING format LIMIT 5` 预览实际数据，调整表定义或使用列映射 |
+| overwrite 模式数据未清空 | 使用了 `COPY OVERWRITE INTO` 语法（不支持） | overwrite 模式应先用 `TRUNCATE TABLE` 清空表，再执行 `COPY INTO` |
+| SELECT FROM VOLUME 报错 | 格式不匹配或多格式文件混合 | 确认 USING 后的格式与实际文件格式一致；使用 `FILES()` 指定文件或 `SUBDIRECTORY` 指定子目录 |
+| PUT 命令失败 | 本地文件路径不存在 | 确认本地文件路径正确，文件存在 |
+
+---
+
+## 依赖的 Skills
+
+| 操作 | 需要加载的 Skill |
+|------|-----------------|
+| 文件上传/下载/删除 | `clickzetta-volume-manager` |
+| 查询 Volume 文件内容 | `clickzetta-volume-manager` |
+| COPY INTO 导入 | 本 Skill |