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

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

@@ -1,10 +1,10 @@
 # Pipe SQL 参考
 
 > **⚠️ ClickZetta 特有语法**
-> - Kafka 读取函数是 `READ_KAFKA(...)`，不是 `KAFKA_SOURCE(...)` 或其他写法
-> - 参数使用 `=>` 命名参数语法：`KAFKA_BROKER => 'host:port'`
-> - JSON 字段提取用 `$1:field_name::TYPE` 语法（`$1` 表示整行 JSON）
+> - Kafka 读取函数是 `read_kafka(...)`，使用**位置参数**（不是命名参数 `=>`）
+> - JSON 字段提取用 `parse_json(value::string)['field']::TYPE` 语法
 > - Pipe 创建后默认自动启动，无需手动 RESUME
+> - OSS Pipe 的 `PURGE=true` 紧跟在 `USING <format>` 之后（如 `USING CSV PURGE=true`）
 
 Pipe 是 ClickZetta Lakehouse 的持续数据导入对象，通过 SQL 定义从 Kafka 或对象存储（OSS/S3/COS）自动、持续地将数据导入目标表，无需外部调度。
 
@@ -12,21 +12,24 @@ Pipe 是 ClickZetta Lakehouse 的持续数据导入对象，通过 SQL 定义从
 
 ```sql
 CREATE [ OR REPLACE ] PIPE <pipe_name>
-  [ COMMENT = '<comment>' ]
-  [ AUTO_INGEST = { TRUE | FALSE } ]
+  VIRTUAL_CLUSTER = '<vcluster_name>'
+  [ BATCH_INTERVAL_IN_SECONDS = '<seconds>' ]
+  [ BATCH_SIZE_PER_KAFKA_PARTITION = '<count>' ]
+  [ RESET_KAFKA_GROUP_OFFSETS = '<none|valid|earliest|latest|timestamp_ms>' ]
+  [ COPY_JOB_HINT = '<json>' ]
 AS
-INSERT INTO <target_table> [ ( <col1>, <col2>, ... ) ]
-SELECT <expr> [, ...]
-FROM TABLE(
-  READ_KAFKA(
-    KAFKA_BROKER => '<broker_host>:<port>',
-    KAFKA_TOPIC  => '<topic_name>',
-    KAFKA_GROUP_ID => '<consumer_group>',
-    KAFKA_OFFSET => '<earliest | latest | <offset_value>>',
-    KAFKA_DATA_FORMAT => '<json | csv | avro>',
-    [ KAFKA_SASL_USERNAME => '<username>', ]
-    [ KAFKA_SASL_PASSWORD => '<password>', ]
-    [ KAFKA_SCHEMA_REGISTRY_URL => '<url>' ]
+COPY INTO <target_table> FROM (
+  SELECT <expr> [, ...]
+  FROM read_kafka(
+    '<bootstrap_servers>',   -- 必填：Kafka 集群地址
+    '<topic>',               -- 必填：Topic 名称
+    '',                      -- 保留（填空字符串）
+    '<group_id>',            -- 必填：持久消费者组 ID
+    '', '', '', '',          -- 位置参数留空，由 Pipe 自动管理
+    'raw',                   -- key 格式（目前只支持 raw）
+    'raw',                   -- value 格式（目前只支持 raw）
+    0,                       -- max_errors
+    MAP(<kafka_config>)      -- Kafka 配置参数
   )
 );
 ```
@@ -35,61 +38,121 @@ FROM TABLE(
 ```sql
 -- 从 Kafka 持续导入 JSON 数据
 CREATE OR REPLACE PIPE kafka_orders_pipe
-  COMMENT '从 Kafka 持续导入订单数据'
+  VIRTUAL_CLUSTER = 'default'
+  BATCH_INTERVAL_IN_SECONDS = '60'
 AS
-INSERT INTO ods.orders (order_id, user_id, amount, created_at)
-SELECT
-  $1:order_id::STRING,
-  $1:user_id::STRING,
-  $1:amount::DECIMAL(10,2),
-  $1:created_at::TIMESTAMP
-FROM TABLE(
-  READ_KAFKA(
-    KAFKA_BROKER => 'kafka.example.com:9092',
-    KAFKA_TOPIC  => 'orders',
-    KAFKA_GROUP_ID => 'lakehouse_consumer',
-    KAFKA_OFFSET => 'latest',
-    KAFKA_DATA_FORMAT => 'json'
+COPY INTO ods.orders FROM (
+  SELECT
+    j['order_id']::STRING AS order_id,
+    j['user_id']::STRING AS user_id,
+    j['amount']::DECIMAL(10,2) AS amount,
+    j['created_at']::TIMESTAMP AS created_at,
+    CAST(`timestamp` AS TIMESTAMP) AS kafka_ts
+  FROM (
+    SELECT `timestamp`, parse_json(value::string) AS j
+    FROM read_kafka(
+      'kafka.example.com:9092',
+      'orders',
+      '',
+      'lakehouse_consumer',
+      '', '', '', '',
+      'raw', 'raw', 0,
+      MAP('kafka.security.protocol', 'PLAINTEXT')
+    )
+  )
+);
+
+-- SASL 认证
+CREATE PIPE kafka_secure_pipe
+  VIRTUAL_CLUSTER = 'pipe_vc'
+  BATCH_INTERVAL_IN_SECONDS = '60'
+AS
+COPY INTO ods.secure_events FROM (
+  SELECT parse_json(value::string)['id']::STRING AS id,
+         CAST(`timestamp` AS TIMESTAMP) AS kafka_ts
+  FROM read_kafka(
+    'kafka.example.com:9092', 'secure_events', '', 'cz_secure',
+    '', '', '', '', 'raw', 'raw', 0,
+    MAP(
+      'kafka.security.protocol', 'SASL_PLAINTEXT',
+      'kafka.sasl.mechanism', 'PLAIN',
+      'kafka.sasl.username', 'my_user',
+      'kafka.sasl.password', 'my_password'
+    )
   )
 );
 ```
 
+## 验证 Kafka 连接（创建 Pipe 前）
+
+独立使用 `read_kafka` 探查数据时，可以在 MAP 中设置 `kafka.auto.offset.reset`：
+
+```sql
+-- 验证连接和数据格式
+SELECT value::string
+FROM read_kafka(
+  'kafka.example.com:9092',
+  'orders',
+  '',
+  'test_explore',
+  '', '', '', '',
+  'raw', 'raw', 0,
+  MAP('kafka.security.protocol', 'PLAINTEXT', 'kafka.auto.offset.reset', 'earliest')
+)
+LIMIT 10;
+```
+
+> ⚠️ **独立探查 vs Pipe 中的区别**：
+> - 独立探查：可在 MAP 中设置 `kafka.auto.offset.reset` 为 `earliest` 读取历史数据
+> - Pipe 中：位置参数必须留空，消费位点由 Pipe 的 `RESET_KAFKA_GROUP_OFFSETS` 参数控制
+
 ## CREATE PIPE — 从对象存储导入
 
 ```sql
 CREATE [ OR REPLACE ] PIPE [ IF NOT EXISTS ] <pipe_name>
-  VIRTUAL_CLUSTER = <virtual_cluster_name>
-  INGEST_MODE = { LIST_PURGE | EVENT_NOTIFICATION }
+  VIRTUAL_CLUSTER = '<virtual_cluster_name>'
+  INGEST_MODE = 'LIST_PURGE' | 'EVENT_NOTIFICATION'
+  [ COMMENT '<comment>' ]
   [ COPY_JOB_HINT = '<hint>' ]
 AS
 COPY INTO <target_table>
 FROM VOLUME <volume_name>
-USING <csv | parquet | orc | json>
-[ OPTIONS ('<key>' = '<value>', ...) ];
+USING <csv | parquet | orc | json> [OPTIONS ('<key>' = '<value>', ...)] PURGE=true;
 ```
 
 **关键参数：**
 - `VIRTUAL_CLUSTER`：指定虚拟集群名称（OSS Pipe 必填）
-- `INGEST_MODE = LIST_PURGE`：通用模式，定期扫描文件列表
-- `INGEST_MODE = EVENT_NOTIFICATION`：事件通知模式，低延迟（仅阿里云 OSS + AWS S3）
-- `FROM VOLUME <volume_name>`：引用已创建的 External Volume（不是 `FROM '@path/'`）
+- `INGEST_MODE = 'LIST_PURGE'`：通用模式，定期扫描文件列表，必须设置 `PURGE=true`
+- `INGEST_MODE = 'EVENT_NOTIFICATION'`：事件通知模式，低延迟（仅阿里云 OSS + AWS S3），不需要 `PURGE=true`
+- `COMMENT 'text'`：不带等号（`COMMENT = 'text'` 会报错）
+- `PURGE=true`：放在最后，OPTIONS 在其之前：`USING CSV OPTIONS (...) PURGE=true`
 - PIPE 中的 COPY 语句不支持 `files`、`regexp`、`subdirectory` 参数
 
 **示例：**
 ```sql
--- 从 OSS Volume 持续导入 Parquet 文件（LIST_PURGE 模式）
+-- LIST_PURGE 模式（带 OPTIONS）
 CREATE OR REPLACE PIPE oss_events_pipe
-  VIRTUAL_CLUSTER = default
-  INGEST_MODE = LIST_PURGE
+  VIRTUAL_CLUSTER = 'default'
+  INGEST_MODE = 'LIST_PURGE'
+  COMMENT 'OSS events pipeline'
 AS
 COPY INTO ods.events
 FROM VOLUME my_oss_volume
-USING PARQUET;
+USING PARQUET PURGE=true;
 
--- EVENT_NOTIFICATION 模式（仅阿里云 OSS + AWS S3）
-CREATE OR REPLACE PIPE oss_events_event_pipe
-  VIRTUAL_CLUSTER = default
-  INGEST_MODE = EVENT_NOTIFICATION
+-- CSV 格式带 OPTIONS（OPTIONS 在 PURGE 之前）
+CREATE PIPE oss_csv_pipe
+  VIRTUAL_CLUSTER = 'default'
+  INGEST_MODE = 'LIST_PURGE'
+AS
+COPY INTO ods.csv_data
+FROM VOLUME my_csv_volume
+USING CSV OPTIONS ('header' = 'true', 'sep' = ',') PURGE=true;
+
+-- EVENT_NOTIFICATION 模式（不需要 PURGE）
+CREATE PIPE oss_event_pipe
+  VIRTUAL_CLUSTER = 'default'
+  INGEST_MODE = 'EVENT_NOTIFICATION'
   ALICLOUD_MNS_QUEUE = 'my-mns-queue-name'
 AS
 COPY INTO ods.events
@@ -107,6 +170,24 @@ ALTER PIPE <pipe_name> SET PIPE_EXECUTION_PAUSED = true;
 ALTER PIPE <pipe_name> SET PIPE_EXECUTION_PAUSED = false;
 ```
 
+## 修改 Pipe 属性
+
+```sql
+-- 每次只能修改一个属性
+ALTER PIPE <pipe_name> SET VIRTUAL_CLUSTER = 'new_vc';
+ALTER PIPE <pipe_name> SET COPY_JOB_HINT = '{"cz.sql.split.kafka.strategy":"size","cz.mapper.kafka.message.size":"200000"}';
+```
+
+> ⚠️ **ALTER PIPE 支持的属性**：
+> - ✅ `PIPE_EXECUTION_PAUSED`
+> - ✅ `VIRTUAL_CLUSTER`
+> - ✅ `COPY_JOB_HINT`
+> - ❌ `BATCH_INTERVAL_IN_SECONDS`（不支持修改，需删除重建）
+> - ❌ `BATCH_SIZE_PER_KAFKA_PARTITION`（不支持修改，需删除重建）
+>
+> 不支持修改 COPY/INSERT 语句逻辑，需删除 Pipe 后重建。
+> `COPY_JOB_HINT` 修改会覆盖所有已有 hints，需一次性设置全部参数。
+
 ## DROP PIPE
 
 ```sql
@@ -119,40 +200,21 @@ DROP PIPE [ IF EXISTS ] <pipe_name>;
 -- 列出当前 schema 下所有 Pipe
 SHOW PIPES;
 
--- 按名称过滤
-SHOW PIPES LIKE 'kafka%';
-
--- 查看 Pipe 详情
+-- 查看 Pipe 详情（状态、延迟、定义）
 DESC PIPE <pipe_name>;
-```
-
-## 验证 Kafka 连接（创建 Pipe 前）
-
-```sql
--- 先用 READ_KAFKA 函数验证连接和数据格式
-SELECT *
-FROM TABLE(
-  READ_KAFKA(
-    KAFKA_BROKER => 'kafka.example.com:9092',
-    KAFKA_TOPIC  => 'orders',
-    KAFKA_GROUP_ID => 'test_group',
-    KAFKA_OFFSET => 'earliest',
-    KAFKA_DATA_FORMAT => 'json'
-  )
-)
-LIMIT 10;
+DESC PIPE EXTENDED <pipe_name>;
 ```
 
 ## 注意事项
 
 - Pipe 创建后默认自动启动，无需手动 RESUME
-- Kafka Pipe 使用 consumer group 管理 offset，重建 Pipe 时注意 group_id 和 offset 设置
-- 对象存储 Pipe 通过文件列表或事件通知（EVENT_NOTIFICATION）检测新文件，避免重复导入
-- Pipe 不支持修改 AS 子句，需要 `CREATE OR REPLACE`
+- Kafka Pipe 使用 consumer group 管理 offset，重建 Pipe 时保持相同 group_id 可从上次位点继续
+- 对象存储 Pipe 通过文件列表或事件通知检测新文件，`load_history` 去重记录保留 7 天
+- Pipe 不支持修改 AS 子句，需要删除后重建（不是 `CREATE OR REPLACE`）
+- Kafka Pipe 仅支持 PLAINTEXT 和 SASL_PLAINTEXT 安全协议，不支持 SSL
 
 ## 参考文档
 
-- [PIPE 导入语法](https://www.yunqi.tech/documents/pipe-syntax)
 - [Pipe 简介](https://www.yunqi.tech/documents/pipe-summary)
 - [借助 read_kafka 函数持续导入](https://www.yunqi.tech/documents/pipe-kafka)
 - [借助 Kafka 外表 Table Stream 持续导入](https://www.yunqi.tech/documents/pipe-kafka-table-stream)

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

@@ -51,10 +51,10 @@ CREATE TABLE STREAM orders_stream_from_ts
 
 ## 消费 Table Stream
 
-Table Stream 是一次性消费的：**每次 SELECT 后，已读取的数据会被标记为已消费**，下次 SELECT 只返回新增变更。
+Table Stream 的 offset 通过 DML 操作移动。**仅 SELECT 不会移动 offset**，可以反复查询预览。执行 DML（INSERT INTO / MERGE INTO / UPDATE / DELETE）消费数据后，offset 前进。
 
 ```sql
--- 查看当前未消费的变更数据
+-- 查看当前未消费的变更数据（不移动 offset）
 SELECT * FROM orders_stream;
 
 -- 变更数据包含的系统字段
@@ -62,21 +62,20 @@ SELECT * FROM orders_stream;
 -- __commit_version: 变更版本号
 -- __commit_timestamp: 变更发生时间
 
--- 典型用法：将变更数据 MERGE 到目标表（忽略 UPDATE_BEFORE）
+-- 典型用法：将变更数据 MERGE 到目标表（过滤掉 UPDATE_BEFORE）
 MERGE INTO dw.orders_dim AS target
 USING (
   SELECT * FROM orders_stream
-  WHERE __change_type IN ('INSERT', 'UPDATE_AFTER', 'DELETE')
+  WHERE __change_type != 'UPDATE_BEFORE'
 ) AS src
 ON target.order_id = src.order_id
 WHEN MATCHED AND src.__change_type = 'UPDATE_AFTER' THEN UPDATE SET target.status = src.status, target.amount = src.amount
 WHEN MATCHED AND src.__change_type = 'DELETE' THEN DELETE
-WHEN NOT MATCHED AND src.__change_type = 'INSERT' THEN INSERT (order_id, status, amount) VALUES (src.order_id, src.status, src.amount);
+WHEN NOT MATCHED AND src.__change_type IN ('INSERT', 'UPDATE_AFTER') THEN INSERT (order_id, status, amount) VALUES (src.order_id, src.status, src.amount);
 
 -- 配合 Dynamic Table 自动消费（推荐）
 CREATE OR REPLACE DYNAMIC TABLE dw.orders_processed
-  REFRESH interval 1 MINUTE
-  VCLUSTER default
+  REFRESH INTERVAL 1 MINUTE vcluster default
 AS
 SELECT order_id, status, amount, __change_type, __commit_timestamp
 FROM orders_stream
@@ -107,10 +106,13 @@ DESC TABLE STREAM <stream_name>;
 
 ## 注意事项
 
-- Stream 数据**只能消费一次**，SELECT 后即标记为已读
+- 仅 SELECT 不会移动 offset，可反复查询预览
+- DML 操作（INSERT INTO / MERGE INTO / UPDATE / DELETE）会移动 offset
+- ⚠️ 即使 DML 带 WHERE 条件过滤了部分行，**所有行的 offset 都会移动**
 - 若长时间不消费，超出源表的 `data_retention_days` 后数据会丢失
 - `STANDARD` 模式下 UPDATE 会产生两条记录：`UPDATE_BEFORE`（更新前）和 `UPDATE_AFTER`（更新后）
-- 消费时通常过滤 `__change_type IN ('INSERT', 'UPDATE_AFTER', 'DELETE')`，忽略 `UPDATE_BEFORE`
+- 消费时通常过滤 `__change_type != 'UPDATE_BEFORE'`，忽略旧值
+- 源表需先开启 `change_tracking`：`ALTER TABLE name SET PROPERTIES ('change_tracking' = 'true')`
 
 ## 参考文档
 

package/bin/skills/clickzetta-table-stream-pipeline/SKILL.md

@@ -13,18 +13,22 @@ description: |
 ## 指令
 
 ### 步骤 1：开启源表变更跟踪（必需前置）
-使用 `write_query` 开启源表的 change_tracking：
+执行 SQL 开启源表的 change_tracking：
 ```sql
 ALTER TABLE <source_table> SET PROPERTIES ('change_tracking' = 'true');
 ```
 - 这是强制性前置步骤，不执行则 Stream 无法正确捕获变更
-- 使用 `read_query` 验证属性是否生效：
+- 验证属性是否生效（两种方法）：
 ```sql
-SHOW CREATE TABLE <source_table>;
+-- 方法 1：DESC EXTENDED 查看 properties
+DESC EXTENDED <source_table>;
+
+-- 方法 2：查询 information_schema
+SELECT table_name, properties FROM information_schema.tables WHERE table_name = '<source_table>';
 ```
 
 ### 步骤 2：创建 Table Stream
-使用 `write_query` 创建 Stream：
+执行 SQL 创建 Stream：
 ```sql
 CREATE [ OR REPLACE ] TABLE STREAM <stream_name>
   ON TABLE <source_table>
@@ -36,37 +40,42 @@ CREATE [ OR REPLACE ] TABLE STREAM <stream_name>
   );
 ```
 关键参数选择：
-- **STANDARD 模式**：捕获 INSERT/UPDATE/DELETE，反映表当前状态 → 适用于数据同步、增量 ETL
+- **STANDARD 模式**：捕获 INSERT/UPDATE/DELETE，反映表当前状态（delta 变化） → 适用于数据同步、增量 ETL
+  - delta 变化指两个事务时间点之间的净变化。例如：先 INSERT 再 DELETE 同一行 → delta 为空；先 INSERT 再 UPDATE → delta 为一条新行（最终状态）
 - **APPEND_ONLY 模式**：仅捕获 INSERT，保留所有历史插入记录 → 适用于审计、历史记录保留
+  - 即使后续 DELETE 了某行，APPEND_ONLY 模式仍保留该行的 INSERT 记录
 - **SHOW_INITIAL_ROWS = TRUE**：首次消费返回建 Stream 时表中已有行
 - **SHOW_INITIAL_ROWS = FALSE**（默认）：首次消费仅返回建 Stream 后的新变更
 - 可选：指定起始时间点
 ```sql
--- ⚠️ TIMESTAMP AS OF 功能在 ClickZetta 中不稳定，建议仅在必要时使用
--- 如需使用，时间戳必须用 CAST() 形式
+-- TIMESTAMP AS OF 用于指定 Stream 的起始读取位点
+-- 注意：此功能在某些场景下可能不稳定，建议优先使用默认行为（从创建时刻开始）
 CREATE TABLE STREAM <stream_name>
   ON TABLE <source_table>
-  TIMESTAMP AS OF CAST('<timestamp>' AS TIMESTAMP)
+  TIMESTAMP AS OF '<timestamp>'
   WITH PROPERTIES ('TABLE_STREAM_MODE' = 'STANDARD');
 ```
 
 ### 步骤 3：准备目标表
-使用 `write_query` 或 `create_table` 创建与源表结构兼容的目标表：
+创建与源表结构兼容的目标表：
 - 目标表列定义需包含源表的业务列
 - 建议额外添加元数据列（如 sync_version、sync_timestamp）用于追踪
 
 ### 步骤 4：查询 Stream 数据（预览，不移动 offset）
-使用 `read_query` 预览 Stream 中的变更数据：
+执行 SELECT 预览 Stream 中的变更数据：
 ```sql
 SELECT *, __change_type, __commit_version, __commit_timestamp
 FROM <stream_name>;
 ```
 - 仅 SELECT 不会移动 offset
 - 元数据字段：`__change_type`（值：`INSERT` / `UPDATE_BEFORE` / `UPDATE_AFTER` / `DELETE`）、`__commit_version`、`__commit_timestamp`
-- UPDATE 产生两条记录：`UPDATE_BEFORE`（更新前旧值）和 `UPDATE_AFTER`（更新后新值），消费时通常忽略 `UPDATE_BEFORE`
+- **UPDATE 处理要点**：UPDATE 操作产生两条记录：
+  - `UPDATE_BEFORE`：更新前的旧值（通常在消费时忽略）
+  - `UPDATE_AFTER`：更新后的新值（用于写入目标表）
+  - 消费时务必过滤 `__change_type`，避免将 `UPDATE_BEFORE` 旧值误写入目标表
 
 ### 步骤 5：消费 Stream 数据（移动 offset）
-使用 `write_query` 执行 DML 操作消费数据：
+执行 DML 操作消费数据：
 
 #### 方式 A：全量消费（INSERT INTO）
 ```sql
@@ -77,24 +86,39 @@ SELECT <columns> FROM <stream_name>;
 #### 方式 B：幂等消费（MERGE，推荐）
 ```sql
 MERGE INTO <target_table> t
-USING <stream_name> s
+USING (SELECT * FROM <stream_name> WHERE __change_type != 'UPDATE_BEFORE') s
 ON t.<pk_column> = s.<pk_column>
-WHEN MATCHED AND s.__change_type = 'UPDATE_AFTER' THEN UPDATE SET t.col1 = s.col1, t.col2 = s.col2
+WHEN MATCHED AND s.__change_type IN ('INSERT', 'UPDATE_AFTER') THEN UPDATE SET t.col1 = s.col1, t.col2 = s.col2
 WHEN MATCHED AND s.__change_type = 'DELETE' THEN DELETE
 WHEN NOT MATCHED AND s.__change_type = 'INSERT' THEN INSERT (<columns>) VALUES (s.<columns>);
 ```
 - DML 操作（INSERT/UPDATE/MERGE）会移动 offset
-- 即使使用 WHERE 条件过滤，所有数据的 offset 仍会移动
+- ⚠️ 即使使用 WHERE 条件过滤，**所有数据的 offset 仍会移动**（不仅是匹配的行）
 - 推荐使用 MERGE 实现幂等性，避免重复消费导致数据重复
+- 在 USING 子查询中过滤掉 `UPDATE_BEFORE`，避免旧值干扰 MERGE 逻辑
+- ⚠️ **MERGE 语法顺序要求**：多个 `WHEN MATCHED` 子句时，**UPDATE 必须在 DELETE 之前**，否则报错（错误信息：`update statement must be before delete statement`）
 
 ### 步骤 6：验证消费状态
-使用 `read_query` 确认消费完成：
+执行查询确认消费完成：
 ```sql
 SELECT COUNT(*) FROM <stream_name>;
 ```
 - 消费成功后 COUNT 应为 0 或仅包含新变更
 - 记录最后消费的 `__commit_version` 用于故障恢复
 
+## Offset 移动规则
+
+| 操作 | 是否移动 offset | 说明 |
+|------|----------------|------|
+| `SELECT * FROM stream` | ❌ 不移动 | 仅预览，可反复查询 |
+| `INSERT INTO target SELECT ... FROM stream` | ✅ 移动 | 消费数据 |
+| `MERGE INTO target USING stream ...` | ✅ 移动 | 消费数据（推荐） |
+| `UPDATE target SET ... FROM stream` | ✅ 移动 | 消费数据 |
+| `DELETE FROM target USING stream` | ✅ 移动 | 消费数据 |
+| 带 WHERE 的 DML | ✅ 全部移动 | 即使 WHERE 过滤了部分行，所有行的 offset 都会移动 |
+
+> ⚠️ **关键注意**：offset 移动是全量的。一旦执行 DML 消费 Stream，所有变更记录的 offset 都会前进，无法部分消费。如果 DML 执行失败（如目标表不存在），offset 不会移动。
+
 ## 模式选择速查
 
 | 需求 | 推荐模式 |
@@ -115,21 +139,48 @@ SELECT COUNT(*) FROM <stream_name>;
 ## 示例
 
 ### 示例 1：订单表实时同步
-```
-1. write_query("ALTER TABLE orders SET PROPERTIES ('change_tracking' = 'true')")
-2. write_query("CREATE TABLE STREAM orders_stream ON TABLE orders WITH PROPERTIES ('TABLE_STREAM_MODE' = 'STANDARD', 'SHOW_INITIAL_ROWS' = 'FALSE')")
-3. write_query("CREATE TABLE orders_sync LIKE orders")  -- 或手动建表
-4. read_query("SELECT *, __commit_version, __commit_timestamp FROM orders_stream")  -- 预览
-5. write_query("MERGE INTO orders_sync t USING orders_stream s ON t.order_id = s.order_id WHEN MATCHED THEN UPDATE SET t.status = s.status, t.amount = s.amount WHEN NOT MATCHED THEN INSERT (order_id, status, amount) VALUES (s.order_id, s.status, s.amount)")
-6. read_query("SELECT COUNT(*) FROM orders_stream")  -- 验证 offset 已移动
+```sql
+-- 1. 开启源表变更跟踪
+ALTER TABLE orders SET PROPERTIES ('change_tracking' = 'true');
+
+-- 2. 创建 Table Stream
+CREATE TABLE STREAM orders_stream ON TABLE orders 
+WITH PROPERTIES ('TABLE_STREAM_MODE' = 'STANDARD', 'SHOW_INITIAL_ROWS' = 'FALSE');
+
+-- 3. 创建目标表（与源表结构兼容）
+CREATE TABLE orders_sync (order_id INT, status STRING, amount DOUBLE);
+
+-- 4. 预览 Stream 数据（不移动 offset）
+SELECT *, __commit_version, __commit_timestamp FROM orders_stream;
+
+-- 5. 消费 Stream 数据（移动 offset）
+MERGE INTO orders_sync t 
+USING (SELECT * FROM orders_stream WHERE __change_type != 'UPDATE_BEFORE') s 
+ON t.order_id = s.order_id 
+WHEN MATCHED AND s.__change_type IN ('INSERT', 'UPDATE_AFTER') THEN UPDATE SET t.status = s.status, t.amount = s.amount 
+WHEN MATCHED AND s.__change_type = 'DELETE' THEN DELETE 
+WHEN NOT MATCHED AND s.__change_type = 'INSERT' THEN INSERT (order_id, status, amount) VALUES (s.order_id, s.status, s.amount);
+
+-- 6. 验证消费完成
+SELECT COUNT(*) FROM orders_stream;
 ```
 
 ### 示例 2：用户行为审计（保留全部插入历史）
-```
-1. write_query("ALTER TABLE user_actions SET PROPERTIES ('change_tracking' = 'true')")
-2. write_query("CREATE TABLE STREAM user_actions_audit_stream ON TABLE user_actions WITH PROPERTIES ('TABLE_STREAM_MODE' = 'APPEND_ONLY', 'SHOW_INITIAL_ROWS' = 'TRUE')")
-3. read_query("SELECT *, __commit_version, __commit_timestamp FROM user_actions_audit_stream")
-4. write_query("INSERT INTO user_actions_audit SELECT *, __commit_version AS audit_version, __commit_timestamp AS audit_time FROM user_actions_audit_stream")
+```sql
+-- 1. 开启源表变更跟踪
+ALTER TABLE user_actions SET PROPERTIES ('change_tracking' = 'true');
+
+-- 2. 创建 Table Stream（APPEND_ONLY 模式）
+CREATE TABLE STREAM user_actions_audit_stream ON TABLE user_actions 
+WITH PROPERTIES ('TABLE_STREAM_MODE' = 'APPEND_ONLY', 'SHOW_INITIAL_ROWS' = 'TRUE');
+
+-- 3. 预览 Stream 数据
+SELECT *, __commit_version, __commit_timestamp FROM user_actions_audit_stream;
+
+-- 4. 消费 Stream 数据（INSERT INTO 移动 offset）
+INSERT INTO user_actions_audit 
+SELECT *, __commit_version AS audit_version, __commit_timestamp AS audit_time 
+FROM user_actions_audit_stream;
 ```
 
 ## 故障排除

package/bin/skills/clickzetta-volume-manager/SKILL.md

@@ -33,14 +33,17 @@ description: |
 
 > ⚠️ **跨云限制**：Storage Connection 必须与 Lakehouse 实例在同一云厂商。阿里云实例不能创建 COS/S3 Connection，腾讯云实例不能创建 OSS Connection。
 
-> ⚠️ **阿里云 OSS 参数名易混淆**：`ACCESS_ID` 对应阿里云控制台的 **AccessKey ID**；`ACCESS_KEY` 对应 **AccessKey Secret**（不是 secret_key）。
+> ⚠️ **阿里云 OSS 参数名**：
+> - 小写形式：`access_id` / `access_key`（推荐）
+> - 大写形式：`ACCESS_KEY_ID` / `ACCESS_KEY_SECRET`（也可以）
+> - ⚠️ `ACCESS_KEY` / `SECRET_KEY` 会报错（缺少 `_ID` / `_SECRET` 后缀）
 
 ```sql
 -- 阿里云 OSS
 CREATE STORAGE CONNECTION IF NOT EXISTS my_oss_conn
   TYPE OSS
-  ACCESS_ID = 'LTAIxxxxxxxxxxxx'       -- 对应 AccessKey ID
-  ACCESS_KEY = 'T8Gexxxxxxmtxxxxxx'    -- 对应 AccessKey Secret（注意：不是 secret_key）
+  access_id = 'LTAIxxxxxxxxxxxx'
+  access_key = 'T8Gexxxxxxmtxxxxxx'
   ENDPOINT = 'oss-cn-hangzhou-internal.aliyuncs.com';
 
 -- 腾讯云 COS
@@ -101,15 +104,22 @@ DESC VOLUME my_oss_volume;
 -- 查看目录下的文件
 SHOW VOLUME DIRECTORY my_oss_volume;
 
--- 刷新目录元数据后查询
+-- 刷新目录元数据后查询（上传新文件后可能需要手动刷新）
 ALTER VOLUME my_oss_volume REFRESH;
 SELECT * FROM DIRECTORY(VOLUME my_oss_volume);
 ```
 
+> ⚠️ **目录刷新注意**：上传文件到对象存储后，`SHOW VOLUME DIRECTORY` 可能不会立即显示新文件。
+> 如果启用了 `AUTO_REFRESH = TRUE`，系统会定期自动刷新；否则需要手动执行 `ALTER VOLUME name REFRESH`。
+
 ---
 
 ## 直接查询 Volume 中的文件
 
+> ⚠️ **语法限制**：ClickZetta 不支持 `@volume_name` 简写（Snowflake Stage 语法），必须使用 `FROM VOLUME name USING format` 完整语法。
+> ⚠️ **多格式文件处理**：如果 Volume 中包含多种格式的文件（如 .csv 和 .json 混合），不指定 `FILES()` 或 `SUBDIRECTORY` 时会尝试读取所有文件，可能因格式不匹配而报错。建议使用 `FILES('xxx.csv')` 指定文件或 `SUBDIRECTORY 'csv_data/'` 指定子目录。
+> ⚠️ **JSON 嵌套字段访问**：使用 `data['key']` 语法（不是 Snowflake 的 `data:key` 语法）。
+
 ```sql
 -- 查询 CSV 文件（自动推断 schema）
 SELECT * FROM VOLUME my_oss_volume
@@ -123,6 +133,19 @@ SELECT * FROM VOLUME my_oss_volume
 USING PARQUET
 REGEXP '.*2024-0[1-6].parquet';
 
+-- 查询指定文件（推荐，避免多格式冲突）
+SELECT * FROM VOLUME my_oss_volume
+USING JSON
+FILES('user_events.json');
+
+-- 查询 JSON 嵌套字段
+SELECT
+  data['event_id'] AS event_id,
+  data['properties']['device'] AS device
+FROM VOLUME my_oss_volume
+USING JSON
+FILES('events.json');
+
 -- 查询 User Volume 文件
 SELECT * FROM USER VOLUME
 USING CSV
@@ -244,6 +267,26 @@ DROP VOLUME IF EXISTS my_oss_volume;
 | 问题 | 原因 | 解决方案 |
 |---|---|---|
 | SHOW VOLUME DIRECTORY 无文件 | 目录未刷新 | 执行 `ALTER VOLUME name REFRESH` |
-| SELECT FROM VOLUME 报错 | 格式不匹配 | 确认 USING 后的格式与实际文件格式一致 |
+| SELECT FROM VOLUME 报错 | 格式不匹配 | 确认 USING 后的格式与实际文件格式一致；使用 `FILES()` 指定文件 |
+| COPY INTO 读取多格式文件失败 | Volume 中有混合格式文件 | 使用 `FILES('xxx.csv')` 指定文件或 `SUBDIRECTORY` 指定子目录 |
 | PUT 命令失败 | 本地路径不存在 | 确认本地文件路径正确 |
 | COPY INTO 报错 | 权限不足 | 检查 STORAGE CONNECTION 的访问密钥权限 |
+| `@volume` 语法报错 | ClickZetta 不支持 | 使用 `FROM VOLUME name USING format` 完整语法 |
+| `data:key` 语法报错 | Snowflake JSON 语法不适用 | 使用 `data['key']` 语法访问 JSON 嵌套字段 |
+| `METADATA$FILENAME` 报错 | ClickZetta 不支持此元数据字段 | 使用字符串字面量或在 INSERT 时手动添加文件路径列 |
+
+---
+
+## Snowflake 迁移对照
+
+| Snowflake 语法 | ClickZetta 等价语法 | 说明 |
+|---|---|---|
+| `@my_stage` | `VOLUME my_volume` | Stage → Volume |
+| `SELECT * FROM @stage/path` | `SELECT * FROM VOLUME vol USING CSV SUBDIRECTORY 'path/'` | 必须指定 USING 格式 |
+| `data:key::STRING` | `data['key']` | JSON 字段访问 |
+| `data:nested.key` | `data['nested']['key']` | 嵌套 JSON 访问 |
+| `METADATA$FILENAME` | 不支持 | 需手动添加文件路径列 |
+| `METADATA$FILE_ROW_NUMBER` | 不支持 | 无等价功能 |
+| `FILE_FORMAT = (TYPE = CSV)` | `USING CSV OPTIONS(...)` | 导入时用 USING，导出时用 FILE_FORMAT |
+| `COPY INTO table FROM @stage` | `COPY INTO table FROM VOLUME vol USING format` | 导入语法 |
+| `COPY INTO @stage FROM table` | `COPY INTO VOLUME vol SUBDIRECTORY '/' FROM TABLE t FILE_FORMAT=(...)` | 导出语法 |

package/bin/skills/clickzetta-volume-manager/references/volume-ddl.md

@@ -14,7 +14,7 @@
 ## CREATE EXTERNAL VOLUME
 
 ```sql
--- OSS
+-- OSS（Connection 必须使用小写 access_id/access_key）
 CREATE EXTERNAL VOLUME my_oss_volume
   LOCATION 'oss://<bucket>/<path>'
   USING CONNECTION my_oss_conn
@@ -42,6 +42,8 @@ CREATE EXTERNAL VOLUME my_s3_volume
 - `DIRECTORY`：目录功能配置，`ENABLE=TRUE` 开启目录索引，`AUTO_REFRESH=TRUE` 自动刷新
 - `RECURSIVE`：是否递归扫描子目录
 
+> ⚠️ 上传新文件后如果 `SHOW VOLUME DIRECTORY` 未显示，执行 `ALTER VOLUME name REFRESH` 手动刷新。
+
 ---
 
 ## ALTER VOLUME
@@ -191,4 +193,7 @@ FROM TABLE my_table
 FILE_FORMAT = (TYPE = CSV);
 ```
 
-> ⚠️ 导出用 `FILE_FORMAT = (TYPE = ...)` 指定格式，不是 `USING`。`USING` 仅用于 `SELECT FROM VOLUME`。
+> ⚠️ **关键区分**：
+> - **导入**（COPY INTO TABLE / SELECT FROM VOLUME）：用 `USING CSV/PARQUET/JSON` + `OPTIONS(...)`
+> - **导出**（COPY INTO VOLUME）：用 `FILE_FORMAT = (TYPE = CSV/PARQUET/JSON)`
+> - 两者语法不可混用！

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clickzetta/cz-cli-linux-x64",
-  "version": "0.3.1",
+  "version": "0.3.4",
   "description": "cz-cli binary for Linux x64",
   "os": ["linux"],
   "cpu": ["x64"],