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

package/bin/skills/clickzetta-kafka-ingest-pipeline/references/kafka-pipe-syntax.md

@@ -2,32 +2,43 @@
 
 > 来源：https://www.yunqi.tech/documents/pipe-kafka 和 https://www.yunqi.tech/documents/pipe-kafka-bestpractice-1
 
+> **⚠️ ClickZetta READ_KAFKA 使用位置参数（positional parameters）**
+> - ❌ 不支持 `=>` 命名参数语法（如 `KAFKA_BROKER => 'host:port'`）
+> - ❌ 不支持 `TABLE(READ_KAFKA(...))` 包装
+> - ✅ 正确：`FROM read_kafka('broker', 'topic', '', 'group', '', '', '', '', 'raw', 'raw', 0, MAP(...))`
+
 ## CREATE PIPE（READ_KAFKA 方式）
 
 ```sql
 CREATE [ OR REPLACE ] PIPE <pipe_name>
-  VIRTUAL_CLUSTER = <vcluster_name>
-  [ BATCH_INTERVAL_IN_SECONDS = <seconds> ]
-  [ BATCH_SIZE_PER_KAFKA_PARTITION = <count> ]
-  [ MAX_SKIP_BATCH_COUNT_ON_ERROR = <count> ]
-  [ INITIAL_DELAY_IN_SECONDS = <seconds> ]
+  VIRTUAL_CLUSTER = '<vcluster_name>'
+  [ BATCH_INTERVAL_IN_SECONDS = '<seconds>' ]
+  [ BATCH_SIZE_PER_KAFKA_PARTITION = '<count>' ]
+  [ MAX_SKIP_BATCH_COUNT_ON_ERROR = '<count>' ]
+  [ INITIAL_DELAY_IN_SECONDS = '<seconds>' ]
   [ RESET_KAFKA_GROUP_OFFSETS = '<offset_value>' ]
+  [ 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_DATA_FORMAT => '<json | csv | avro>',
-    [ KAFKA_SASL_USERNAME => '<username>', ]
-    [ KAFKA_SASL_PASSWORD => '<password>' ]
+COPY INTO <target_table> FROM (
+  SELECT <expr> [, ...]
+  FROM read_kafka(
+    '<bootstrap_servers>',   -- 位置 1：Kafka 集群地址（必填）
+    '<topic_name>',          -- 位置 2：Topic 名称（必填）
+    '',                      -- 位置 3：Topic pattern（保留，填空字符串）
+    '<group_id>',            -- 位置 4：消费者组 ID（必填）
+    '',                      -- 位置 5：starting_offsets（Pipe 中留空）
+    '',                      -- 位置 6：ending_offsets（Pipe 中留空）
+    '',                      -- 位置 7：starting_timestamp（Pipe 中留空）
+    '',                      -- 位置 8：ending_timestamp（Pipe 中留空）
+    'raw',                   -- 位置 9：key 格式（目前只支持 raw）
+    'raw',                   -- 位置 10：value 格式（目前只支持 raw）
+    0,                       -- 位置 11：max_errors
+    MAP(<kafka_config>)      -- 位置 12：Kafka 配置参数
   )
 );
 ```
 
-### 参数说明
+### Pipe 参数说明
 
 | 参数 | 必填 | 默认值 | 说明 |
 |------|------|--------|------|
@@ -37,6 +48,7 @@ FROM TABLE(
 | `MAX_SKIP_BATCH_COUNT_ON_ERROR` | 否 | 30 | 出错时跳过批次的最大重试次数 |
 | `INITIAL_DELAY_IN_SECONDS` | 否 | 0 | 首个作业调度延迟 |
 | `RESET_KAFKA_GROUP_OFFSETS` | 否 | — | 启动时消费位点（仅创建时生效） |
+| `COPY_JOB_HINT` | 否 | — | JSON 格式的作业参数 |
 
 ### RESET_KAFKA_GROUP_OFFSETS 可选值
 
@@ -50,20 +62,138 @@ FROM TABLE(
 
 ### READ_KAFKA 参数（在 Pipe 中 vs 独立使用）
 
-| 特性 | 独立使用 READ_KAFKA | 在 Pipe 中使用 |
+| 特性 | 独立使用 read_kafka | 在 Pipe 中使用 |
 |------|-------------------|---------------|
 | 消费者组 | 临时，执行完即销毁 | 持久，保持消费位置 |
-| 位置管理 | 手动指定 `KAFKA_OFFSET` | Pipe 自动管理，**不要设置** `KAFKA_OFFSET` |
+| 位置管理 | 在 MAP 中设置 `kafka.auto.offset.reset` | Pipe 自动管理，位置参数**必须留空** |
 | 执行方式 | 一次性查询 | 持续调度执行 |
-| 默认起始位置 | earliest（探查历史数据） | latest（处理新数据） |
+| 默认起始位置 | latest（可在 MAP 中改为 earliest） | latest（由 RESET_KAFKA_GROUP_OFFSETS 控制） |
+
+### MAP 配置参数
+
+| 参数 | 说明 |
+|------|------|
+| `kafka.security.protocol` | 安全协议：`PLAINTEXT` 或 `SASL_PLAINTEXT` |
+| `kafka.sasl.mechanism` | SASL 机制：`PLAIN` |
+| `kafka.sasl.username` | SASL 用户名 |
+| `kafka.sasl.password` | SASL 密码 |
+| `kafka.auto.offset.reset` | 独立探查时的起始位点（`earliest` / `latest`） |
+| `cz.kafka.fetch.retry.enable` | 启用 fetch 重试（`true`/`false`） |
+| `cz.kafka.fetch.retry.times` | 重试次数 |
+| `cz.kafka.fetch.retry.intervalMs` | 重试间隔（毫秒） |
 
 ### JSON 字段提取语法
 
 ```sql
--- $1 表示整行 JSON
-$1:field_name::TYPE              -- 提取顶层字段
-$1:nested.field::TYPE            -- 提取嵌套字段（点号访问）
-PARSE_JSON($1:field::STRING)     -- 将字符串字段解析为 JSON 对象
+-- key 和 value 都是 binary 类型，需要先转换
+value::string                                    -- 转为字符串
+parse_json(value::string)                        -- 解析为 JSON 对象
+parse_json(value::string)['field']::TYPE         -- 提取顶层字段
+parse_json(value::string)['nested']['key']::TYPE -- 提取嵌套字段
+
+-- 推荐模式：在子查询中先 parse_json，外层直接用 j['field']
+SELECT j['order_id']::STRING, j['amount']::DECIMAL(10,2)
+FROM (
+  SELECT parse_json(value::string) AS j
+  FROM read_kafka(...)
+)
+```
+
+### 完整示例
+
+```sql
+-- 无认证 Kafka Pipe
+CREATE PIPE kafka_orders_pipe
+  VIRTUAL_CLUSTER = 'default'
+  BATCH_INTERVAL_IN_SECONDS = '60'
+AS
+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,
+    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_orders',
+      '', '', '', '',
+      'raw', 'raw', 0,
+      MAP('kafka.security.protocol', 'PLAINTEXT')
+    )
+  )
+);
+
+-- SASL 认证 + 指定时间点消费
+CREATE PIPE kafka_secure_pipe
+  VIRTUAL_CLUSTER = 'pipe_vc'
+  BATCH_INTERVAL_IN_SECONDS = '60'
+  RESET_KAFKA_GROUP_OFFSETS = '1737789688000'
+AS
+COPY INTO ods.secure_events FROM (
+  SELECT
+    j['id']::STRING AS event_id,
+    j['payload']::STRING AS payload,
+    CAST(`timestamp` AS TIMESTAMP) AS kafka_ts
+  FROM (
+    SELECT `timestamp`, parse_json(value::string) AS j
+    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'
+      )
+    )
+  )
+);
+```
+
+---
+
+## 独立探查（验证连接和数据格式）
+
+```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;
+
+-- SASL 认证
+SELECT value::string
+FROM read_kafka(
+  'kafka.example.com:9092',
+  'orders',
+  '',
+  'test_explore',
+  '', '', '', '',
+  'raw', 'raw', 0,
+  MAP(
+    'kafka.security.protocol', 'SASL_PLAINTEXT',
+    'kafka.sasl.mechanism', 'PLAIN',
+    'kafka.sasl.username', 'my_user',
+    'kafka.sasl.password', 'my_password',
+    'kafka.auto.offset.reset', 'earliest'
+  )
+)
+LIMIT 10;
 ```
 
 ---
@@ -76,34 +206,37 @@ PARSE_JSON($1:field::STRING)     -- 将字符串字段解析为 JSON 对象
 CREATE STORAGE CONNECTION IF NOT EXISTS <conn_name>
   TYPE KAFKA
   BOOTSTRAP_SERVERS = ['<host1>:<port1>', '<host2>:<port2>']
-  SECURITY_PROTOCOL = '<PLAINTEXT | SASL_PLAINTEXT>';
+  SECURITY_PROTOCOL = 'PLAINTEXT';
 ```
 
 ### 步骤 2：创建 Kafka 外部表
 
 ```sql
-CREATE EXTERNAL TABLE <ext_table_name>
-  USING KAFKA
-  OPTIONS (
-    'group_id' = '<consumer_group>',
-    'topics' = '<topic_name>',
-    'starting_offset' = '<earliest | latest>'
-  )
-  CONNECTION <conn_name>;
+-- ⚠️ 必须显式指定列定义（不能省略）
+-- ⚠️ offset 是保留字，必须用反引号转义
+CREATE EXTERNAL TABLE <ext_table_name> (
+  topic STRING,
+  partition INT,
+  `offset` BIGINT,
+  `timestamp` TIMESTAMP,
+  timestamp_type STRING,
+  headers STRING,
+  key BINARY,
+  value BINARY
+)
+USING KAFKA
+OPTIONS (
+  'group_id' = '<consumer_group>',
+  'topics' = '<topic_name>',
+  'starting_offset' = '<earliest | latest>'
+)
+CONNECTION <conn_name>;
 ```
 
-固定字段：
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| topic | STRING | Kafka 主题名称 |
-| partition | INT | 分区 ID |
-| offset | BIGINT | 分区内偏移量 |
-| timestamp | TIMESTAMP_LTZ | 消息时间戳 |
-| timestamp_type | STRING | 时间戳类型 |
-| headers | MAP<STRING, BINARY> | 消息头 |
-| key | BINARY | 消息键 |
-| value | BINARY | 消息体 |
+> **注意**：
+> - 列定义是**必须的**，省略会报错 `failed to detect columns`
+> - `offset` 和 `timestamp` 是保留字，需要反引号转义
+> - 删除外部表用 `DROP TABLE`（不是 `DROP EXTERNAL TABLE`）
 
 ### 步骤 3：创建 Table Stream
 
@@ -117,8 +250,8 @@ CREATE TABLE STREAM <stream_name>
 
 ```sql
 CREATE PIPE <pipe_name>
-  VIRTUAL_CLUSTER = <vcluster_name>
-  [ BATCH_INTERVAL_IN_SECONDS = <seconds> ]
+  VIRTUAL_CLUSTER = '<vcluster_name>'
+  BATCH_INTERVAL_IN_SECONDS = '60'
 AS
 COPY INTO <target_table>
 SELECT <expr> [, ...]
@@ -136,13 +269,20 @@ ALTER PIPE <pipe_name> SET PIPE_EXECUTION_PAUSED = true;
 -- 恢复
 ALTER PIPE <pipe_name> SET PIPE_EXECUTION_PAUSED = false;
 
--- 修改属性（每次只能改一个）
-ALTER PIPE <pipe_name> SET BATCH_INTERVAL_IN_SECONDS = 120;
-ALTER PIPE <pipe_name> SET BATCH_SIZE_PER_KAFKA_PARTITION = 1000000;
+-- 修改 VCluster
 ALTER PIPE <pipe_name> SET VIRTUAL_CLUSTER = 'new_vc';
+
+-- 修改 COPY_JOB_HINT
 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，需一次性设置全部参数。
 
@@ -151,15 +291,14 @@ ALTER PIPE <pipe_name> SET COPY_JOB_HINT = '{"cz.sql.split.kafka.strategy":"size
 ## 监控
 
 ```sql
--- 查看 Pipe 详情（含延迟信息）
-DESC PIPE <pipe_name>;
+-- 查看 Pipe 详情（含延迟信息 pipe_latency）
 DESC PIPE EXTENDED <pipe_name>;
 
 -- 查看所有 Pipe
 SHOW PIPES;
 
 -- 查看加载历史
-SELECT * FROM TABLE(load_history('<schema>.<table>'))
+SELECT * FROM load_history('<schema>.<table>')
 ORDER BY last_load_time DESC LIMIT 20;
 
 -- 通过 query_tag 查看 Pipe 作业
@@ -181,6 +320,5 @@ DROP PIPE [ IF EXISTS ] <pipe_name>;
 - [借助 read_kafka 函数持续导入](https://www.yunqi.tech/documents/pipe-kafka)
 - [借助 Kafka 外表 Table Stream 持续导入](https://www.yunqi.tech/documents/pipe-kafka-table-stream)
 - [最佳实践：使用 Pipe 高效接入 Kafka 数据](https://www.yunqi.tech/documents/pipe-kafka-bestpractice-1)
-- [read_kafka 函数](https://www.yunqi.tech/documents/read_kafka)
 - [Kafka 外部表](https://www.yunqi.tech/documents/kafka-external-table)
-- [PIPE 导入语法](https://www.yunqi.tech/documents/pipe-syntax)
+- [Kafka Storage Connection](https://www.yunqi.tech/documents/Kafka_connection)

package/bin/skills/clickzetta-lakehouse-connect/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: clickzetta-lakehouse-connect
 description: |
-  Guide for connecting to ClickZetta Lakehouse via SDK/JDBC. Covers Python SDK (clickzetta.connect), ZettaPark Session (DataFrame API), SQLAlchemy (ORM/BI tools), and JDBC (Java). Use this skill when user needs to configure a connection from external tools or code — NOT for querying data inside czcode (use execute_sql/list_objects tools instead). Trigger for: "Python SDK 连接", "JDBC 连接", "SQLAlchemy 配置", "ZettaPark 怎么用", "连接报错", "clickzetta-connector-python", "clickzetta-sqlalchemy".
+  Guide for connecting to ClickZetta Lakehouse via SDK/JDBC. Covers Python SDK (clickzetta.connect), ZettaPark Session (DataFrame API), SQLAlchemy (ORM/BI tools), and JDBC (Java). Use this skill when user needs to configure a connection from external tools or code. Trigger for: "Python SDK 连接", "JDBC 连接", "SQLAlchemy 配置", "ZettaPark 怎么用", "连接报错", "clickzetta-connector-python", "clickzetta-sqlalchemy".
   Keywords: connection, Python SDK, JDBC, SQLAlchemy, ZettaPark, driver, connect
 ---
 

package/bin/skills/clickzetta-oss-ingest-pipeline/SKILL.md

@@ -64,12 +64,17 @@ description: |
 -- 密钥方式（LIST_PURGE 模式支持）
 CREATE STORAGE CONNECTION IF NOT EXISTS my_oss_connection
   TYPE OSS
-  ENDPOINT = 'oss-cn-hangzhou.aliyuncs.com'
-  ACCESS_KEY = '<your_access_key>'
-  SECRET_KEY = '<your_secret_key>'
-  COMMENT = 'OSS connection for data pipeline';
+  access_id = '<your_access_key_id>'
+  access_key = '<your_access_key_secret>'
+  ENDPOINT = 'oss-cn-hangzhou.aliyuncs.com';
 ```
 
+> **参数说明**：
+> - `access_id`：对应阿里云控制台的 **AccessKey ID**
+> - `access_key`：对应阿里云控制台的 **AccessKey Secret**
+> - 也可使用大写形式 `ACCESS_KEY_ID` / `ACCESS_KEY_SECRET`
+> - ⚠️ `ACCESS_KEY` / `SECRET_KEY` 会报错（缺少 `_ID` / `_SECRET` 后缀）
+>
 > **提示**：如果使用 Role ARN 方式（EVENT_NOTIFICATION 模式必须），参见下方"模式 B"中的 Connection 创建语法。
 
 #### 步骤 2：创建外部 Volume
@@ -77,14 +82,17 @@ CREATE STORAGE CONNECTION IF NOT EXISTS my_oss_connection
 ```sql
 -- 使用 LH_execute_query 执行
 CREATE EXTERNAL VOLUME IF NOT EXISTS pipe_volume
-  STORAGE_CONNECTION = my_oss_connection
-  LOCATION = 'oss://my-bucket/data-path/'
-  COMMENT = 'Volume for OSS PIPE ingestion';
+  LOCATION 'oss://my-bucket/data-path/'
+  USING CONNECTION my_oss_connection
+  DIRECTORY = (enable = true, auto_refresh = true)
+  RECURSIVE = true
+  COMMENT 'Volume for OSS PIPE ingestion';
 ```
 
 > **关键参数**：
-> - 如需递归扫描子目录：添加 `recursive = true`
-> - 如需自动刷新目录元数据：添加 `directory = (enable = true, auto_refresh = true)`
+> - `RECURSIVE = true`：递归扫描子目录
+> - `DIRECTORY = (enable = true, auto_refresh = true)`：自动刷新目录元数据
+> - ⚠️ COMMENT 不带等号：`COMMENT 'text'`（不是 `COMMENT = 'text'`）
 
 #### 步骤 3：验证 COPY INTO 可独立运行
 
@@ -94,14 +102,12 @@ CREATE EXTERNAL VOLUME IF NOT EXISTS pipe_volume
 -- 使用 LH_execute_query 执行
 COPY INTO my_schema.target_table
 FROM VOLUME pipe_volume
-USING CSV
-OPTIONS (
-  'header' = 'true',
-  'delimiter' = ','
-);
+USING CSV OPTIONS ('header' = 'true', 'delimiter' = ',') PURGE=true;
 ```
 
-> **重要**：PIPE 中的 COPY 语句不支持 `files`、`regexp`、`subdirectory` 参数。确保此处验证时也不使用这些参数。
+> **重要**：
+> - PIPE 中的 COPY 语句不支持 `files`、`regexp`、`subdirectory` 参数。确保此处验证时也不使用这些参数。
+> - OPTIONS 放在 PURGE=true **之前**：`USING CSV OPTIONS (...) PURGE=true`
 
 #### 步骤 4：创建 PIPE（LIST_PURGE 模式）
 
@@ -110,22 +116,32 @@ OPTIONS (
 CREATE PIPE IF NOT EXISTS my_oss_pipe
   INGEST_MODE = 'LIST_PURGE'
   VIRTUAL_CLUSTER = 'my_vc'
-  COMMENT = 'OSS data pipeline - scan mode'
+  COMMENT 'OSS data pipeline - scan mode'
 AS
 COPY INTO my_schema.target_table
 FROM VOLUME pipe_volume
-USING CSV
-OPTIONS (
-  'header' = 'true',
-  'delimiter' = ',',
-  'purge' = 'true'
-);
+USING CSV OPTIONS ('header' = 'true') PURGE=true;
 ```
 
-> **参数说明**：
-> - `INGEST_MODE = 'LIST_PURGE'`：定期扫描 Volume 目录，发现新文件即加载
-> - `purge = true`：**LIST_PURGE 模式必须设置**，加载成功后删除源文件（避免重复导入）。即使不想删除源文件，LIST_PURGE 模式也需要此参数，否则会重复导入同一文件
+> **⚠️ 语法关键点**：
+> - `PURGE=true` 放在最后：`USING <format> [OPTIONS (...)] PURGE=true`
+> - OPTIONS 在 PURGE=true **之前**（如果需要的话）
+> - 也可以不带 OPTIONS：`USING CSV PURGE=true`（推荐简洁写法）
+> - COMMENT 不带等号：`COMMENT 'text'`
+> - 大写 `PURGE`，小写 `true`，中间用 `=` 连接，无空格
+> - **LIST_PURGE 模式必须设置** `PURGE=true`，加载成功后删除源文件（避免重复导入）
+> - 即使不想删除源文件，LIST_PURGE 模式也需要此参数，否则会重复导入同一文件
 > - `VIRTUAL_CLUSTER`：指定执行 PIPE 任务的虚拟集群
+>
+> **错误写法**（会报语法错误）：
+> ```sql
+> -- ❌ 不要把 purge 放在 OPTIONS 里
+> OPTIONS ('header' = 'true', 'purge' = 'true')
+> -- ❌ OPTIONS 不能在 PURGE 之后
+> USING CSV PURGE=true OPTIONS ('header' = 'true')
+> -- ❌ 不要用小写或加引号
+> 'purge'='true'
+> ```
 
 #### 步骤 5：验证 PIPE 状态
 
@@ -157,8 +173,7 @@ CREATE STORAGE CONNECTION IF NOT EXISTS my_oss_role_connection
   TYPE OSS
   ENDPOINT = 'oss-cn-hangzhou.aliyuncs.com'
   ROLE_ARN = 'acs:ram::1234567890:role/clickzetta-oss-role'
-  REGION = 'cn-hangzhou'
-  COMMENT = 'OSS connection via Role ARN for event notification mode';
+  REGION = 'cn-hangzhou';
 ```
 
 #### 步骤 2：创建外部 Volume
@@ -166,8 +181,10 @@ CREATE STORAGE CONNECTION IF NOT EXISTS my_oss_role_connection
 ```sql
 -- 使用 LH_execute_query 执行
 CREATE EXTERNAL VOLUME IF NOT EXISTS pipe_event_volume
-  STORAGE_CONNECTION = my_oss_role_connection
-  LOCATION = 'oss://my-bucket/data-path/';
+  LOCATION 'oss://my-bucket/data-path/'
+  USING CONNECTION my_oss_role_connection
+  DIRECTORY = (enable = true, auto_refresh = true)
+  RECURSIVE = true;
 ```
 
 #### 步骤 3：创建 PIPE（EVENT_NOTIFICATION 模式）
@@ -178,21 +195,18 @@ CREATE PIPE IF NOT EXISTS my_oss_event_pipe
   INGEST_MODE = 'EVENT_NOTIFICATION'
   VIRTUAL_CLUSTER = 'my_vc'
   ALICLOUD_MNS_QUEUE = 'my-mns-queue-name'
-  COMMENT = 'OSS data pipeline - event notification mode'
+  COMMENT 'OSS data pipeline - event notification mode'
 AS
 COPY INTO my_schema.target_table
 FROM VOLUME pipe_event_volume
-USING CSV
-OPTIONS (
-  'header' = 'true',
-  'delimiter' = ','
-);
+USING CSV;
 ```
 
 > **参数说明**：
 > - `INGEST_MODE = 'EVENT_NOTIFICATION'`：通过消息通知触发加载
 > - `ALICLOUD_MNS_QUEUE`：阿里云 MNS 队列名称（AWS 使用 `AWS_SQS_QUEUE`）
-> - 此模式下不需要 `purge = true`，因为是事件驱动而非扫描
+> - 此模式下不需要 `PURGE=true`，因为是事件驱动而非扫描
+> - COMMENT 不带等号：`COMMENT 'text'`
 
 ---
 
@@ -222,16 +236,17 @@ CREATE TABLE IF NOT EXISTS my_schema.target_table (
 
 ```sql
 -- 使用 LH_execute_query 执行
--- 批量导入场景使用 access_id / access_key 语法
 CREATE STORAGE CONNECTION IF NOT EXISTS my_batch_conn
   TYPE OSS
   ENDPOINT = 'oss-cn-shanghai-internal.aliyuncs.com'
-  access_id = '<your_access_id>'
-  access_key = '<your_access_key>'
-  COMMENTS = 'OSS batch import connection';
+  access_id = '<your_access_key_id>'
+  access_key = '<your_access_key_secret>';
 ```
 
-> **注意**：批量导入场景中 Connection 参数使用 `access_id` / `access_key`（小写），与 PIPE 模式中的 `ACCESS_KEY` / `SECRET_KEY` 写法不同，两种写法均可使用。
+> **Connection 参数命名**：
+> - 小写形式：`access_id` / `access_key`（推荐）
+> - 大写形式：`ACCESS_KEY_ID` / `ACCESS_KEY_SECRET`（也可以）
+> - ⚠️ `ACCESS_KEY` / `SECRET_KEY` 会报错（缺少后缀）
 
 #### 步骤 3：创建外部 Volume（启用目录自动刷新）
 
@@ -248,7 +263,10 @@ CREATE EXTERNAL VOLUME IF NOT EXISTS my_batch_volume
 > - `USING CONNECTION`：引用已创建的存储连接
 > - `DIRECTORY = (enable=true, auto_refresh=true)`：启用目录元数据并自动刷新，便于查询 Volume 中的文件列表
 >
-> **注意**：批量导入 Volume 使用 `LOCATION ... USING CONNECTION ...` 语法；PIPE 模式 Volume 使用 `STORAGE_CONNECTION = ... LOCATION = ...` 语法。两种语法均有效，适用于不同场景，不可混用。
+> **Volume 创建语法统一说明**：
+> - ✅ 推荐语法：`LOCATION '...' USING CONNECTION conn_name`（官方文档标准写法）
+> - ⚠️ 旧语法：`STORAGE_CONNECTION = conn_name LOCATION = '...'`（部分旧文档中出现，仍可使用）
+> - 两种语法功能等价，建议统一使用 `LOCATION ... USING CONNECTION` 形式
 
 #### 步骤 4a：INSERT INTO 从 Volume 导入（支持过滤转换）
 
@@ -289,6 +307,7 @@ FROM VOLUME my_batch_volume (
 > - `INSERT INTO`：支持 `FILES()` 指定文件、`WHERE` 过滤转换，适合精细控制
 > - `COPY INTO`：语法更简洁，适合全量加载
 > - 两者都支持 Schema-on-Read（在 FROM VOLUME 中定义列）
+> - ⚠️ **load_history 差异**：只有 `COPY INTO` 会记录到 `load_history`，`INSERT INTO ... FROM VOLUME` 不会记录。如需去重保护，请使用 `COPY INTO`
 
 #### 步骤 5：验证导入结果
 
@@ -319,7 +338,7 @@ DESC PIPE EXTENDED my_oss_pipe;
 
 ```sql
 -- 使用 LH_execute_query 执行
-SELECT * FROM TABLE(load_history('my_schema.target_table'))
+SELECT * FROM load_history('my_schema.target_table')
 ORDER BY last_load_time DESC
 LIMIT 20;
 ```
@@ -376,10 +395,13 @@ DROP PIPE IF EXISTS my_oss_pipe;
 | 问题 | 排查方向 |
 |------|---------|
 | PIPE 创建后无数据加载 | 1. `DESC PIPE EXTENDED` 检查是否暂停 2. 确认 Volume 路径下有新文件 3. 检查 COPY INTO 是否能独立运行 |
-| LIST_PURGE 模式文件未被删除 | 确认 `purge = true` 已设置；检查 Connection 的 AccessKey 是否有删除权限 |
+| LIST_PURGE 模式文件未被删除 | 确认 `PURGE=true` 已设置（紧跟 `USING <format>` 之后）；检查 Connection 的 AccessKey 是否有删除权限 |
+| `PURGE=true` 语法错误 | OPTIONS 必须在 PURGE 之前：`USING CSV OPTIONS (...) PURGE=true`。不要写成 `USING CSV PURGE=true OPTIONS(...)` |
 | EVENT_NOTIFICATION 模式无触发 | 1. 检查 MNS/SQS 队列是否收到消息 2. 确认 OSS 事件通知规则配置正确 3. 检查 Role ARN 授权 |
 | 重复加载数据 | `load_history` 去重记录仅保留 7 天，超过 7 天的同名文件会被重新加载 |
 | COPY_JOB_HINT 修改后部分参数丢失 | `SET COPY_JOB_HINT` 会覆盖所有已有 hints，需在一次 ALTER 中设置全部参数 |
+| INSERT INTO FROM VOLUME 后 load_history 无记录 | 正常行为：只有 `COPY INTO` 会记录到 load_history，`INSERT INTO` 不会 |
+| COPY INTO 报格式错误 | Volume 中有多种格式文件，使用 `FILES('xxx.json')` 指定文件 |
 
 ## 注意事项
 
@@ -399,4 +421,7 @@ DROP PIPE IF EXISTS my_oss_pipe;
 - 同地域建议使用内网 Endpoint 以提升传输速度和稳定性
 - 推荐使用 GENERAL PURPOSE 类型虚拟集群执行批量加载任务
 - INSERT INTO 方式支持 `FILES()` 和 `WHERE` 参数，COPY INTO 不支持
-- Connection 参数 `access_id`/`access_key` 和 `ACCESS_KEY`/`SECRET_KEY` 两种写法均可使用
+- Connection 参数使用 `access_id`/`access_key`（小写）或 `ACCESS_KEY_ID`/`ACCESS_KEY_SECRET`（大写），不要用 `ACCESS_KEY`/`SECRET_KEY`
+- ⚠️ `INSERT INTO ... FROM VOLUME` 不会记录到 `load_history`，只有 `COPY INTO` 会记录
+- ⚠️ Volume 中有多种格式文件时，不指定 `FILES()` 的 COPY INTO 会尝试读取所有文件，可能因格式不匹配而失败。建议使用 `FILES('xxx.json')` 指定文件或 `SUBDIRECTORY` 指定子目录
+- 上传文件到 OSS 后，`SHOW VOLUME DIRECTORY` 可能需要先执行 `ALTER VOLUME name REFRESH` 刷新目录元数据