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

package/bin/skills/clickzetta-sql-pipeline-manager/SKILL.md

@@ -24,12 +24,15 @@ description: >
 
 | 功能 | ❌ 错误写法（Snowflake/标准SQL） | ✅ ClickZetta 正确写法 |
 |---|---|---|
-| 动态表计算集群 | `WAREHOUSE = compute_wh` | `VCLUSTER default`（直接跟名称，不带等号） |
+| 动态表计算集群 | `WAREHOUSE = compute_wh` | `vcluster default`（直接跟名称，不带等号） |
 | 动态表刷新调度 | `TARGET_LAG = '1 minutes'` | `REFRESH INTERVAL 1 MINUTE vcluster default` |
-| Kafka 读取函数 | `KAFKA_SOURCE(...)` | `READ_KAFKA(KAFKA_BROKER => ..., KAFKA_DATA_FORMAT => 'json')` |
+| Kafka 读取函数 | `TABLE(READ_KAFKA(KAFKA_BROKER => ...))` | `read_kafka('broker', 'topic', '', 'group', '', '', '', '', 'raw', 'raw', 0, MAP(...))` — 位置参数 |
 | 物化视图定时刷新 | `REFRESH EVERY 1 HOUR` | `REFRESH INTERVAL 60 MINUTE vcluster default`（与动态表语法相同） |
 | 物化视图手动刷新 | `REFRESH MATERIALIZED VIEW` 放在 CREATE 里 | 单独执行 `REFRESH MATERIALIZED VIEW <name>;` |
 | 修改动态表 SQL | `ALTER DYNAMIC TABLE ... AS ...` | `CREATE OR REPLACE DYNAMIC TABLE ...`（ALTER 不支持修改 AS 子句） |
+| JSON 字段访问 | `$1:field::TYPE` 或 `data:key` | `parse_json(value::string)['field']::TYPE` 或 `data['key']` |
+| COPY INTO 导入格式 | `FILE_FORMAT = (TYPE = CSV)` | `USING CSV OPTIONS(...)` |
+| COPY INTO 导出格式 | `USING CSV` | `FILE_FORMAT = (TYPE = CSV)` |
 
 ---
 
@@ -91,14 +94,14 @@ CREATE SCHEMA IF NOT EXISTS ecommerce_gold;
 ```
 
 **来源 → 入口对象的选择规则：**
-- Kafka → `CREATE PIPE ... AS INSERT INTO ... FROM TABLE(READ_KAFKA(...))`
-- 对象存储（OSS/S3/COS）→ `CREATE PIPE ... VIRTUAL_CLUSTER = name INGEST_MODE = LIST_PURGE AS COPY INTO ... FROM VOLUME <volume_name> USING <format>`
+- Kafka → `CREATE PIPE ... AS COPY INTO ... FROM (SELECT ... FROM read_kafka('broker', 'topic', '', 'group', '', '', '', '', 'raw', 'raw', 0, MAP(...)))`
+- 对象存储（OSS/S3/COS）→ `CREATE PIPE ... VIRTUAL_CLUSTER = 'name' INGEST_MODE = 'LIST_PURGE' AS COPY INTO ... FROM VOLUME <volume_name> USING <format> PURGE=true`
 - 已有表 + 有 UPDATE/DELETE → `CREATE TABLE STREAM ... WITH PROPERTIES ('TABLE_STREAM_MODE' = 'STANDARD')`，中间层过滤 `__change_type IN ('INSERT', 'UPDATE_AFTER', 'DELETE')`
 - 已有表 + 仅 INSERT → Dynamic Table 直接 `FROM` 源表
 
 **刷新频率规则：**
-- 第一个转换层（Bronze→Silver 或 ODS→DWD）设置用户指定的刷新频率（如 `REFRESH interval 1 MINUTE VCLUSTER default`）
-- 下游层根据业务需求设置各自的刷新频率（如 `REFRESH interval 5 MINUTE VCLUSTER default`）
+- 第一个转换层（Bronze→Silver 或 ODS→DWD）设置用户指定的刷新频率（如 `REFRESH INTERVAL 1 MINUTE vcluster default`）
+- 下游层根据业务需求设置各自的刷新频率（如 `REFRESH INTERVAL 5 MINUTE vcluster default`）
 
 ---
 
@@ -146,12 +149,12 @@ CREATE SCHEMA IF NOT EXISTS ecommerce_gold;
 阅读对应参考文件后，根据用户提供的参数生成完整可运行 SQL。
 
 **必填参数检查：**
-- Dynamic Table：`REFRESH interval N MINUTE VCLUSTER name`、AS 查询
+- Dynamic Table：`REFRESH INTERVAL N MINUTE vcluster name`、AS 查询
 - Table Stream：源表名、MODE（STANDARD 或 APPEND_ONLY）
-- Pipe（Kafka）：`KAFKA_BROKER`、`KAFKA_TOPIC`、`KAFKA_GROUP_ID`、目标表
-- Pipe（对象存储）：Volume 路径、文件格式、目标表
+- Pipe（Kafka）：bootstrap_servers、topic、group_id、目标表（位置参数语法）
+- Pipe（对象存储）：Volume 路径、文件格式、目标表、`PURGE=true`（LIST_PURGE 模式）
 
-若用户未提供 VCLUSTER，默认使用 `default`。
+若用户未提供 VCLUSTER，默认使用 `default`（GP 型集群）。
 
 ## 步骤 3：验证
 
@@ -179,28 +182,35 @@ SHOW PIPES;
 
 ```sql
 -- Step 1: 创建 Pipe 持续摄入 Kafka 数据到 ODS 层
-CREATE OR REPLACE PIPE kafka_orders_pipe AS
-INSERT INTO ods.orders (order_id, user_id, amount, status, created_at)
-SELECT
-  $1:order_id::STRING,
-  $1:user_id::STRING,
-  $1:amount::DECIMAL(10,2),
-  $1:status::STRING,
-  $1:created_at::TIMESTAMP
-FROM TABLE(
-  READ_KAFKA(
-    KAFKA_BROKER => 'kafka.example.com:9092',
-    KAFKA_TOPIC  => 'orders',
-    KAFKA_GROUP_ID => 'lakehouse_ingest',
-    KAFKA_OFFSET => 'latest',
-    KAFKA_DATA_FORMAT => 'json'
+-- ⚠️ 注意：ClickZetta 不支持 CREATE OR REPLACE PIPE，需用 CREATE PIPE 或先 DROP 再 CREATE
+CREATE PIPE kafka_orders_pipe
+  VIRTUAL_CLUSTER = 'default'
+  BATCH_INTERVAL_IN_SECONDS = '60'
+AS
+COPY INTO ods.orders FROM (
+  SELECT
+    j['order_id']::STRING,
+    j['user_id']::STRING,
+    j['amount']::DECIMAL(10,2),
+    j['status']::STRING,
+    j['created_at']::TIMESTAMP
+  FROM (
+    SELECT parse_json(value::string) AS j
+    FROM read_kafka(
+      'kafka.example.com:9092',  -- bootstrap_servers
+      'orders',                   -- topic
+      '',                         -- reserved
+      'lakehouse_ingest',         -- group_id
+      '', '', '', '',             -- 位置参数留空，由 Pipe 管理
+      'raw', 'raw', 0,
+      MAP('kafka.security.protocol', 'PLAINTEXT')
+    )
   )
 );
 
 -- Step 2: 动态表做 DWD 层清洗（每分钟增量刷新）
 CREATE OR REPLACE DYNAMIC TABLE dwd.orders_clean
-  REFRESH interval 1 MINUTE
-  VCLUSTER default
+  REFRESH INTERVAL 1 MINUTE vcluster default
 AS
 SELECT
   order_id,
@@ -214,8 +224,7 @@ WHERE amount > 0;
 
 -- Step 3: 动态表做 DWS 层聚合（每 5 分钟刷新）
 CREATE OR REPLACE DYNAMIC TABLE dws.order_hourly
-  REFRESH interval 5 MINUTE
-  VCLUSTER default
+  REFRESH INTERVAL 5 MINUTE vcluster default
 AS
 SELECT
   DATE_TRUNC('hour', created_at) AS hour,
@@ -236,19 +245,21 @@ CREATE TABLE STREAM ods.orders_stream
 
 -- Step 2: 动态表消费 Stream，过滤出最新状态
 CREATE OR REPLACE DYNAMIC TABLE dwd.orders_latest
-  REFRESH interval 2 MINUTE
-  VCLUSTER default
+  REFRESH INTERVAL 2 MINUTE vcluster default
 AS
 SELECT order_id, user_id, amount, status, created_at
 FROM ods.orders_stream
-WHERE __change_type IN ('INSERT', 'UPDATE_AFTER', 'DELETE');
+WHERE __change_type IN ('INSERT', 'UPDATE_AFTER');
 ```
 
 ### 场景 C：物化视图加速 BI 查询
 
 ```sql
 -- 创建每小时刷新的物化视图
-CREATE OR REPLACE MATERIALIZED VIEW dws.mv_daily_revenue
+-- ⚠️ 注意：ClickZetta 不支持 CREATE OR REPLACE MATERIALIZED VIEW
+-- 方法 1: 先 DROP 再 CREATE（推荐）
+DROP MATERIALIZED VIEW IF EXISTS dws.mv_daily_revenue;
+CREATE MATERIALIZED VIEW dws.mv_daily_revenue
   COMMENT '每日收入汇总，供 BI 工具查询'
   REFRESH INTERVAL 60 MINUTE vcluster default
 AS
@@ -260,8 +271,14 @@ SELECT
 FROM dwd.orders_clean
 GROUP BY 1, 2;
 
+-- 方法 2: 使用 BUILD DEFERRED + DISABLE QUERY REWRITE（复杂，不推荐）
+-- CREATE OR REPLACE MATERIALIZED VIEW ... BUILD DEFERRED DISABLE QUERY REWRITE AS ...
+
 -- 手动触发刷新
 REFRESH MATERIALIZED VIEW dws.mv_daily_revenue;
+
+-- 删除物化视图（⚠️ 注意：必须用 DROP MATERIALIZED VIEW，不能用 DROP TABLE）
+DROP MATERIALIZED VIEW dws.mv_daily_revenue;
 ```
 
 ### 场景 D：运维操作
@@ -290,8 +307,7 @@ ALTER PIPE kafka_orders_pipe SET PIPE_EXECUTION_PAUSED = false;
 ```sql
 -- 创建参数化动态表（使用 SESSION_CONFIGS 定义参数）
 CREATE OR REPLACE DYNAMIC TABLE dwd.orders_partitioned
-  REFRESH interval 30 MINUTE
-  VCLUSTER default
+  REFRESH INTERVAL 30 MINUTE vcluster default
 AS
 SELECT order_id, user_id, amount, status, created_at, DATE(created_at) AS dt
 FROM ods.orders
@@ -306,25 +322,32 @@ REFRESH DYNAMIC TABLE dwd.orders_partitioned
 
 ### 场景 F：动态表 DML 操作（手动修正数据）
 
-动态表默认不支持 DML，需先通过 SET 命令开启，**且每次执行 DML 前都需要重新 SET**：
+⚠️ **重要**：ClickZetta 动态表**不支持 DML 操作**（INSERT/UPDATE/DELETE）。如需修正数据，有以下方案：
 
+**方案 1：重建动态表（推荐）**
 ```sql
--- ⚠️ 必须在同一会话/批次中先执行 SET，再执行 DML
-SET cz.sql.dt.allow.dml = true;
-
--- 手动插入补数据
-INSERT INTO dwd.orders_clean VALUES (999, 'manual_user', 100.00, 'COMPLETED', DATE('2024-06-15'), '2024-06-15');
+-- 1. 在源表中修正数据
+-- 2. 等待动态表自动刷新（下一次 REFRESH INTERVAL 会全量刷新）
+```
 
--- 手动删除错误数据
-SET cz.sql.dt.allow.dml = true;
-DELETE FROM dwd.orders_clean WHERE order_id = 999;
+**方案 2：使用普通表替代动态表**
+```sql
+-- 对于需要频繁手动修正的场景，建议使用普通表 + 定时调度任务
+-- 而不是动态表
+CREATE TABLE dwd.orders_manual (
+  order_id STRING,
+  user_id STRING,
+  amount DECIMAL(10,2),
+  status STRING,
+  created_at TIMESTAMP,
+  dt DATE
+);
 ```
 
-> ⚠️ **注意**：
-> - `SET cz.sql.dt.allow.dml = true` 必须与 DML 语句在同一执行批次中，不能分开执行
-> - 对动态表执行 DML 后，下一次自动刷新会触发**全量刷新**（而非增量），可能耗时较长
-> - **UPDATE 操作有限制**：动态表 UPDATE 可能因内部隐藏列（`MV__KEY`）报错，建议改用 DELETE + INSERT 或 MERGE INTO 替代
-> - 仅在数据修正等特殊场景使用 DML
+> ⚠️ **动态表限制**：
+> - 动态表是只读的，不支持 INSERT/UPDATE/DELETE
+> - 数据修正应在源表进行，动态表会自动刷新
+> - 如需手动控制数据，使用普通表 + Studio 调度任务
 
 ---
 
@@ -333,12 +356,15 @@ DELETE FROM dwd.orders_clean WHERE order_id = 999;
 | 错误 | 原因 | 解决方案 |
 |---|---|---|
 | `VCluster not available` | 计算集群未启动或名称错误 | 确认 VCLUSTER 名称，检查集群状态 |
-| 动态表刷新失败 | SQL 查询报错或源表结构变更 | `SHOW DYNAMIC TABLE REFRESH HISTORY` 查看错误详情 |
+| 动态表刷新失败 | SQL 查询报错或源表结构变更 | `SHOW DYNAMIC TABLE REFRESH HISTORY WHERE name = 'xxx'` 查看错误详情 |
 | Stream 数据为空 | 已被消费或超出保留周期 | 检查源表 `data_retention_days`，确认是否已消费 |
-| Pipe 停止摄入 | Kafka offset 问题或连接断开 | `DESC PIPE` 查看状态，检查 Kafka 连接 |
+| Pipe 停止摄入 | Kafka offset 问题或连接断开 | `DESC PIPE EXTENDED` 查看状态，检查 Kafka 连接 |
 | `Cannot ALTER AS clause` | 尝试用 ALTER 修改动态表 SQL | 改用 `CREATE OR REPLACE DYNAMIC TABLE` |
-| 动态表 UPDATE 报错 `Not support hidden column :MV__KEY` | 动态表内部实现限制 | 改用 `DELETE + INSERT` 或 `MERGE INTO` 替代 UPDATE |
-| 动态表 DML 报错 `not allowed` | 未设置 DML 开关 | 在同一批次先执行 `SET cz.sql.dt.allow.dml = true;` |
+| `CREATE OR REPLACE PIPE` 语法报错 | ClickZetta 不支持该语法 | 用 `CREATE PIPE` 或先 `DROP PIPE` 再 `CREATE` |
+| `CREATE OR REPLACE MATERIALIZED VIEW` 语法报错 | 仅支持 `REWRITE DISABLED + BUILD DEFER` 模式 | 推荐用 `DROP MATERIALIZED VIEW` + `CREATE MATERIALIZED VIEW` |
+| `DROP TABLE` 删除物化视图报错 | 对象类型不匹配 | 用 `DROP MATERIALIZED VIEW`（不是 `DROP TABLE`） |
+| 动态表 DML 报错 `not allowed` | 动态表不支持 DML | 在源表修正数据，或使用普通表 + 调度任务 |
+| `SET cz.sql.dt.allow.dml` 报错 | 不支持 session statement | 动态表不支持 DML 操作，改用其他方案 |
 
 ---
 

package/bin/skills/clickzetta-sql-pipeline-manager/references/dynamic-table.md

@@ -1,9 +1,12 @@
 # Dynamic Table（动态表）SQL 参考
 
 > **⚠️ ClickZetta 特有语法**
-> - 刷新调度写法：`REFRESH interval 5 MINUTE VCLUSTER default`（不是 `TARGET_LAG`）
+> - 刷新调度写法：`REFRESH INTERVAL 5 MINUTE vcluster default`（不是 `TARGET_LAG`）
 > - 修改调度周期或计算集群必须用 `CREATE OR REPLACE`，`ALTER` 不支持
-> - `ALTER DYNAMIC TABLE` 只支持：SUSPEND / RESUME / SET COMMENT / RENAME COLUMN
+> - `ALTER DYNAMIC TABLE` 只支持：SUSPEND / RESUME / SET COMMENT / RENAME COLUMN / CHANGE COLUMN COMMENT / SET/UNSET PROPERTIES
+> - 删除用 `DROP DYNAMIC TABLE`（不是 `DROP TABLE`）
+> - 恢复用 `UNDROP TABLE`（不是 `UNDROP DYNAMIC TABLE`）
+> - DESC 用 `DESC TABLE name`（不支持 `DESC DYNAMIC TABLE name EXTENDED`）
 
 动态表是 ClickZetta Lakehouse 的核心增量计算对象。通过 SQL 查询定义，自动增量刷新，无需手动调度。
 
@@ -16,23 +19,23 @@ CREATE [ OR REPLACE ] DYNAMIC TABLE <name>
   [ CLUSTERED BY (<col_name>) ]
   [ COMMENT <comment> ]
   [ PROPERTIES ( data_lifecycle = <day_num> ) ]
-  REFRESH [ START WITH <timestamp_expr> ] interval <n> { SECOND | MINUTE | HOUR | DAY }
-  VCLUSTER <vcluster_name>
+  REFRESH [ START WITH TIMESTAMP '<timestamp>' ] INTERVAL <n> { SECOND | MINUTE | HOUR | DAY }
+  vcluster <vcluster_name>
 AS
   <query>;
 ```
 
 **关键参数：**
-- `REFRESH interval <n> MINUTE`：刷新间隔，最小 1 分钟
-- `VCLUSTER`：运行刷新任务的计算集群名称（直接跟名称，不带等号和引号）
+- `REFRESH INTERVAL <n> MINUTE`：刷新间隔，最小 1 分钟
+- `vcluster`：运行刷新任务的计算集群名称（直接跟名称，不带等号和引号）
 - `OR REPLACE`：若同名动态表已存在则替换（修改 SQL 逻辑或调度配置必须用此方式）
+- 建议使用 GP 型集群（如 `default`），AP 型集群不支持小文件合并
 
 **示例：**
 ```sql
 -- 基础示例：每 5 分钟刷新一次订单汇总
 CREATE OR REPLACE DYNAMIC TABLE dw.order_summary
-  REFRESH interval 5 MINUTE
-  VCLUSTER default
+  REFRESH INTERVAL 5 MINUTE vcluster default
 AS
 SELECT
   date_trunc('hour', created_at) AS hour,
@@ -44,8 +47,7 @@ GROUP BY 1, 2;
 
 -- 修改调度周期（必须用 CREATE OR REPLACE）
 CREATE OR REPLACE DYNAMIC TABLE dw.order_summary
-  REFRESH interval 10 MINUTE
-  VCLUSTER default
+  REFRESH INTERVAL 10 MINUTE vcluster default
 AS
 SELECT
   date_trunc('hour', created_at) AS hour,
@@ -66,17 +68,17 @@ ALTER DYNAMIC TABLE <name> SUSPEND;
 ALTER DYNAMIC TABLE <name> RESUME;
 
 -- 修改注释
-ALTER DYNAMIC TABLE <name> SET COMMENT <comment>;
+ALTER DYNAMIC TABLE <name> SET COMMENT '<comment>';
 
 -- 修改列名
 ALTER DYNAMIC TABLE <name> RENAME COLUMN <old_col> TO <new_col>;
 
--- 修改列注释
-ALTER DYNAMIC TABLE <name> CHANGE COLUMN <col_name> COMMENT <comment>;
+-- 修改列注释（注意用 CHANGE COLUMN）
+ALTER DYNAMIC TABLE <name> CHANGE COLUMN <col_name> COMMENT '<comment>';
 
 -- 修改属性
-ALTER DYNAMIC TABLE <name> SET PROPERTIES ( key = value );
-ALTER DYNAMIC TABLE <name> UNSET PROPERTIES ( key );
+ALTER DYNAMIC TABLE <name> SET PROPERTIES ('key' = 'value');
+ALTER DYNAMIC TABLE <name> UNSET PROPERTIES ('key');
 ```
 
 > 注意：修改调度周期、计算集群、SQL 查询逻辑，必须用 `CREATE OR REPLACE DYNAMIC TABLE`，ALTER 不支持这些操作。
@@ -91,7 +93,11 @@ REFRESH DYNAMIC TABLE <name>;
 ## DROP DYNAMIC TABLE
 
 ```sql
+-- ⚠️ 必须用 DROP DYNAMIC TABLE，不能用 DROP TABLE
 DROP DYNAMIC TABLE [ IF EXISTS ] <name>;
+
+-- 恢复已删除的动态表（⚠️ 用 UNDROP TABLE，不是 UNDROP DYNAMIC TABLE）
+UNDROP TABLE <name>;
 ```
 
 ## SHOW / DESC
@@ -103,25 +109,27 @@ SHOW TABLES WHERE is_dynamic = true;
 -- 列出指定 schema 下的动态表
 SHOW TABLES IN <schema_name> WHERE is_dynamic = true;
 
--- 查看动态表结构和调度配置
+-- 查看动态表结构
 DESC TABLE <name>;
-DESCRIBE DYNAMIC TABLE <name> EXTENDED;
 
 -- 查看完整建表语句
 SHOW CREATE TABLE <name>;
 
 -- 查看刷新历史（状态、耗时、触发方式、增量行数）
-SHOW DYNAMIC TABLE REFRESH HISTORY <name>;
-SHOW DYNAMIC TABLE REFRESH HISTORY <name> LIMIT 20;
+SHOW DYNAMIC TABLE REFRESH HISTORY WHERE name = '<dt_name>' LIMIT 20;
 ```
 
+> ⚠️ **DESC 注意**：动态表用 `DESC TABLE name`，不支持 `DESC DYNAMIC TABLE name EXTENDED`（EXTENDED 会报错）。
+
 ## 注意事项
 
 - 修改 SQL 逻辑、调度周期、计算集群 → 用 `CREATE OR REPLACE`，不能用 `ALTER`
 - 刷新间隔最小 1 分钟
-- 动态表支持 Time Travel（`TIMESTAMP AS OF`）和 UNDROP
+- 删除用 `DROP DYNAMIC TABLE`（不是 `DROP TABLE`）
+- 恢复用 `UNDROP TABLE`（不是 `UNDROP DYNAMIC TABLE`）
 - 刷新失败不影响表的可查询性（返回上次成功版本的数据）
 - 非简单加列/减列的 `CREATE OR REPLACE` 会触发一次全量刷新
+- 建议使用 GP 型集群（如 `default`），AP 型集群不支持小文件合并
 
 ## 参数化动态表（SESSION_CONFIGS）
 
@@ -130,8 +138,7 @@ SHOW DYNAMIC TABLE REFRESH HISTORY <name> LIMIT 20;
 ```sql
 -- 创建参数化动态表
 CREATE OR REPLACE DYNAMIC TABLE dwd.orders_partitioned
-  REFRESH interval 30 MINUTE
-  VCLUSTER default
+  REFRESH INTERVAL 30 MINUTE vcluster default
 AS
 SELECT order_id, user_id, amount, dt
 FROM ods.orders
@@ -146,18 +153,23 @@ REFRESH DYNAMIC TABLE dwd.orders_partitioned
 
 ## 动态表 DML 操作
 
-动态表默认不支持 DML，需先开启参数：
+动态表默认不支持 DML，需先开启参数（每次 DML 前都需要 SET）：
 
 ```sql
--- 开启 DML 支持
-ALTER DYNAMIC TABLE <name> SET PROPERTIES ('cz.dynamic.table.enable.dml' = 'true');
-
--- 支持的 DML 操作
+-- ⚠️ 必须在同一会话/批次中先执行 SET，再执行 DML
+SET cz.sql.dt.allow.dml = true;
 INSERT INTO <name> VALUES (...);
+
+-- 删除
+SET cz.sql.dt.allow.dml = true;
 DELETE FROM <name> WHERE ...;
 ```
 
-> ⚠️ 执行 DML 后，下一次自动刷新会触发**全量刷新**（而非增量），仅在数据修正等特殊场景使用。
+> ⚠️ **DML 注意事项**：
+> - `SET cz.sql.dt.allow.dml = true` 必须与 DML 语句在同一执行批次中
+> - 执行 DML 后，下一次自动刷新会触发**全量刷新**（而非增量），可能耗时较长
+> - UPDATE 可能因内部隐藏列（`MV__KEY`）报错，建议改用 DELETE + INSERT
+> - 仅在数据修正等特殊场景使用 DML
 
 ## 参考文档