@clickzetta/cz-cli-darwin-x64 0.3.1

package/bin/skills/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/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/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/lakehouse-doc/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: lakehouse-doc
+description: "云器 Lakehouse 官方文档知识库。编写 SQL、查询语法/函数/数据类型、DDL/DML、动态表、权限、计算组、数据湖、AI 函数等 Lakehouse 相关问题时，必须查阅本 skill 的 references/ 目录。"
+---
+
+# lakehouse-doc
+
+云器 Lakehouse 官方文档。根据用户问题在 `references/` 下按文件名定位对应文档。
+
+## references/ 目录结构
+
+```
+references/
+├── *.md                          # 778 篇主文档（按主题命名，见下方索引）
+├── eco_integration/              # 生态工具集成 (12 篇)
+│   ├── dbt.md, superset.md, datagrip-lakehouse.md, trino.md ...
+├── java_reference/               # Java SDK (5 篇)
+│   ├── java-sdk-summary.md, jdbc.md, realtime-upload.md, client.md ...
+├── python_reference/             # Python SDK (3 篇)
+│   ├── connector.md, sqlalchemy.md, python-sdk-summary.md
+├── opensource/                   # 开源工具 (1 篇)
+│   └── travel.md
+└── sql_functions/                # SQL 函数参考 (339 篇)
+    ├── aggregate_functions/      # 聚合函数 (52): count.md, sum.md, avg.md ...
+    ├── window_functions/         # 窗口函数 (19): row_number.md, rank.md, lag.md ...
+    ├── table_functions/          # 表函数 (9): table_changes.md ...
+    ├── context_functions/        # 上下文函数 (8): current_user.md ...
+    └── scalar_functions/         # 标量函数 (339)
+        ├── datetime_functions/   # 日期时间 (66)
+        ├── string_functions/     # 字符串 (70)
+        ├── math_functions/       # 数学 (55)
+        ├── nested_functions/     # 嵌套类型 (45)
+        ├── bitmap_functions/     # Bitmap (29)
+        ├── json_functions/       # JSON (14)
+        ├── conditional_functions/# 条件 (14)
+        ├── high_order_functions/ # 高阶 (12)
+        ├── vector_functions/     # 向量 (11)
+        ├── ip_functions/         # IP (6)
+        ├── search_functions/     # 搜索 (6)
+        ├── hash_functions/       # 哈希 (5)
+        ├── geo_functions/        # 地理 (3)
+        ├── bitwise_functions/    # 位运算 (2)
+        └── partition/            # 分区 (1)
+```
+
+## 文档索引（llms.txt）
+
+# 云器 Lakehouse 文档（LLM 导航）
+
+> 云器 Lakehouse 是全托管的湖仓一体架构平台，基于云原生设计理念从零打造。通过**存算分离**、**Serverless弹性架构**、**开放存储格式**和**AI优化工具**，为企业提供数据仓库、数据湖、实时处理与BI报表的统一平台。
+
+## 快速入门
+
+- [概览](https://www.yunqi.tech/documents/Overview): 介绍云器Lakehouse的存算分离架构、Serverless计算、开放数据格式及主要应用场景。
+- [产品概念](https://www.yunqi.tech/documents/Concepts): 介绍云器Lakehouse的存算分离架构、Serverless计算、开放数据格式及主要应用场景。
+- [入门指导](https://www.yunqi.tech/documents/Tutorials): 通过数据导入、SQL查询、数据可视化等步骤，快速完成从数据接入到分析展示的完整流程。
+
+## 使用指南
+
+- [Studio](https://www.yunqi.tech/documents/studio_manual): 通过Web界面进行数据开发与管理，支持连接数据源、SQL查询、作业编排、结果可视化和资产目录浏览。
+- [对象模型](https://www.yunqi.tech/documents/object_model_design): 介绍云器Lakehouse的对象模型核心概念，包括目录、数据库、表、视图、物化视图、函数和共享的定义与层级关系。
+- [数据采集](https://www.yunqi.tech/documents/Ingestion): 通过本地文件、数据库、Kafka等多种数据源导入数据，涵盖核心概念、配置步骤与操作示例。
+- [数据加工](https://www.yunqi.tech/documents/Transformation): 围绕"数据加工"说明核心概念、关键配置与典型操作步骤，并提供示例与注意事项。
+- [数据分析](https://www.yunqi.tech/documents/Analysis): 提供从数据导入、SQL查询到可视化分析的全流程操作指南，涵盖数据源连接、SQL语法、函数使用及结果导出。
+- [安全](https://www.yunqi.tech/documents/data_security): 提供用户管理、权限控制、审计日志等安全功能。
+- [数据分享](https://www.yunqi.tech/documents/data_share): 围绕"数据分享"说明核心概念、关键配置与典型操作步骤。
+- [私网连接](https://www.yunqi.tech/documents/connect_to_Lakehouse): 通过配置终端节点实现跨VPC或本地IDC与云上服务的私网安全访问。
+- [性能测试](https://www.yunqi.tech/documents/benchmark): 性能测试核心概念、关键配置与典型操作步骤。
+- [生态工具](https://www.yunqi.tech/documents/tools): 生态工具核心概念、关键配置与典型操作步骤。
+- [Insight](https://www.yunqi.tech/documents/Lakehouse_Insight): 通过连接云器Lakehouse数据源，创建数据集并拖拽生成BI报表与看板。
+
+## SQL手册
+
+- [SQL命令](https://www.yunqi.tech/documents/sql-reference): DDL、DML、DQL等SQL命令的完整语法参考。
+- [数据类型](https://www.yunqi.tech/documents/data-type): 精确数值、浮点数、字符串、日期时间、布尔值等数据类型定义。
+- [SQL函数](https://www.yunqi.tech/documents/functions): SQL函数核心概念与使用示例。
+- [SQL使用指南](https://www.yunqi.tech/documents/considerations-for-using-sql): SQL使用注意事项与最佳实践。
+
+## 开发手册
+
+- [Java SDK 参考](https://www.yunqi.tech/documents/java-sdk-refer): Java SDK 核心概念、关键配置与典型操作步骤。
+- [Python SDK 参考](https://www.yunqi.tech/documents/python-sdk-refer): Python SDK 核心概念、关键配置与典型操作步骤。
+
+## 实践教程
+
+- [高效管理对象和组织数据](https://www.yunqi.tech/documents/data_org): 数据对象创建管理，目录组织、权限、生命周期策略。
+- [数据导入导出实践](https://www.yunqi.tech/documents/practice_data_import_and_export): 多数据源导入导出操作步骤与示例。
+- [数据查询分析实践](https://www.yunqi.tech/documents/practice_data_analysis): 从数据导入到可视化分析的全流程操作指南。
+- [构建和运维ELT流程实践](https://www.yunqi.tech/documents/ELT_practice): 企业级ELT流水线构建，涵盖开发、测试、部署及故障恢复。
+- [优化计算资源](https://www.yunqi.tech/documents/OptimizingComputingResources): 计算组配置、弹性伸缩策略和资源监控。
+- [性能体验](https://www.yunqi.tech/documents/performence_test): 性能测试方法、优化建议与监控指标。
+- [构建 Modern Data Stack](https://www.yunqi.tech/documents/ModernDataStackWithEcosystemTools): 现代数据栈核心组件与架构模式。
+- [AI应用开发](https://www.yunqi.tech/documents/REMOTEFUNCTION): 从数据准备、模型训练到服务部署的AI应用开发流程。
+- [安全与合规审计](https://www.yunqi.tech/documents/security_compliance_audit_guide): 权限管理、SQL审计日志、数据脱敏策略及合规性配置。
+- [用量和费用管理](https://www.yunqi.tech/documents/cost_management): 用量明细、费用构成、计费模式与预算管理。
+
+## Lakehouse AI
+
+- [Lakehouse AI 概述](https://www.yunqi.tech/documents/LakehouseAI_overview): 非结构化数据管理、AI外部函数、多模态检索、Python开发框架及对话式分析。
+- [AI 的数据准备](https://www.yunqi.tech/documents/Server_data_for_AI): 向量检索、全文搜索与结构化数据分析的无缝结合。
+- [AI 函数](https://www.yunqi.tech/documents/AI_function_in_SQL): 创建和使用AI函数，支持Python/Java调用外部AI服务。
+- [Zettapark](https://www.yunqi.tech/documents/LakehousePythonZettapark): Python开发框架API参考。
+- [AI + BI 统一工作流](https://www.yunqi.tech/documents/unifiedWorkflow): 自然语言交互生成SQL查询与可视化。
+- [AI Gateway](https://www.yunqi.tech/documents/AIGateway): 统一接入、路由分发、负载均衡、限流熔断。
+- [DataGPT](https://www.yunqi.tech/documents/datagpt_intro): 自然语言提问直接生成SQL并获取可视化图表。
+- [Lakehouse MCP Server](https://www.yunqi.tech/documents/LakehouseMCPServer): 通过MCP将数据湖仓能力暴露给AI助手。
+- [AI 生态](https://www.yunqi.tech/documents/AI_eco): 与PyTorch、TensorFlow、MLflow、LangChain等集成。

package/bin/skills/lakehouse-doc/references/.gitattributes

@@ -0,0 +1 @@
+.topwrite/assets/** filter=lfs diff=lfs merge=lfs -text

package/bin/skills/lakehouse-doc/references/.gitlab-ci.yml

@@ -0,0 +1,11 @@
+pages:
+  stage: deploy
+  script:
+    - mkdir .public
+    - cp -r * .public
+    - mv .public public
+  artifacts:
+    paths:
+      - public
+  only:
+    - gh-pages