@clickzetta/cz-cli-darwin-x64 0.3.1

package/bin/skills/lakehouse-doc/references/pipe-kafka-table-stream.md

@@ -0,0 +1,180 @@
+# 使用 Table Stream 和 Pipe 将 Kafka 数据导入 Lakehouse
+
+## 一、背景介绍
+
+在大数据处理领域，将 Kafka 中的流数据高效地导入 Lakehouse（数据湖仓）是一个常见的需求。云器科技提供了强大的 Table Stream 和 Pipe 功能，使得这一过程变得更加简便和高效。本文将详细介绍如何使用 Table Stream 和 Pipe 将 Kafka 数据导入 Lakehouse，包括创建 Kafka 外部表和 Kafka Table Stream 的完整过程。
+
+## 二、操作步骤
+
+### 创建 Kafka 外部表
+
+在使用 Table Stream 和 Pipe 之前，我们需要先创建一个与[ Kafka 集成的外部表](create-kafka-external.md)，用于访问 Kafka 中的数据。
+
+```sql
+CREATE STORAGE CONNECTION pipe_kafka
+ TYPE kafka 
+BOOTSTRAP_SERVERS = ['47.00.08.62:9092'] 
+SECURITY_PROTOCOL = 'PLAINTEXT';
+
+CREATE EXTERNAL TABLE external_table_kafka (   
+ key_column binary,   
+ value_column binary NOT NULL)
+USING kafka
+OPTIONS (   'group_id' = 'external_table_lh',    'topics' = 'my_topic')
+CONNECTION pipe_kafka;
+```
+
+
+
+### 创建 Table Stream
+
+在 Kafka 外部表上[创建一个 Table Stream](create-table-stream.md)，以便能够实时地捕获 Kafka 中的数据变化。
+
+```sql
+CREATE TABLE STREAM kafka_table_stream_pipe1 
+ON TABLE external_table_kafka
+WITH PROPERTIES (
+    'table_stream_mode' = 'append_only'
+
+);
+```
+
+* `kafka_table_stream_pipe1`：Table Stream 的名称。
+* `ON TABLE external_table_kafka`：指定基于之前创建的 Kafka 外部表创建 Table Stream。
+* `table_stream_mode='append_only'`：指定 Table Stream 的模式为仅追加，意味着只会捕获新增的数据行。
+
+
+
+创建完成后，可以通过以下查询来验证 Table Stream 中的数据：
+
+```sql
+SELECT CAST(value AS STRING) FROM kafka_table_stream_pipe1;
+```
+
+此查询将 Table Stream 中的 `value` 字段转换为字符串类型并返回，方便后续处理。
+
+### 创建目标表
+
+接下来，我们需要创建一个目标表，用于存储从 Kafka 导入的数据。
+
+```sql
+CREATE TABLE kafka_sink_table_1 (
+    a TIMESTAMP,
+    b STRING
+);
+```
+
+* `kafka_sink_table_1`：目标表的名称。
+* `a TIMESTAMP`：第一个字段，用于存储时间戳类型的数据。
+* `b STRING`：第二个字段，用于存储字符串类型的数据。
+
+### 创建 Pipe
+
+最后，使用 Pipe 将 Table Stream 中的数据持续导入到目标表中。
+
+```sql
+CREATE PIPE kafka_pipe_stream
+VIRTUAL_CLUSTER = 'test_alter'
+AS
+COPY INTO kafka_sink_table_1
+FROM (
+    SELECT CURRENT_TIMESTAMP(), CAST(value AS STRING) FROM kafka_table_stream_pipe1
+);
+```
+
+* `kafka_pipe_stream`：Pipe 的名称。
+* `VIRTUAL_CLUSTER = 'test_alter'`：指定使用的虚拟集群为 名称，
+* `COPY INTO kafka_sink_table_1`：将数据复制到目标表 `kafka_sink_table_1` 中。
+* `SELECT CURRENT_TIMESTAMP(), CAST(value AS STRING) FROM kafka_table_stream_pipe1`：从 Table Stream 中选择数据，将当前时间戳和转换为字符串的 `value` 字段作为目标表的两列数据。
+
+其他可设置的属性
+- `INITIAL_DELAY_IN_SECONDS`:首个作业调度延迟，选填项（默认 0 秒）
+- `BATCH_INTERVAL_IN_SECONDS`：（可选）设置批处理间隔时间，默认值为60秒。
+- `BATCH_SIZE_PER_KAFKA_PARTITION`：（可选）设置每个Kafka分区的批处理大小，默认值为500,000条。
+- `MAX_SKIP_BATCH_COUNT_ON_ERROR`：（可选）设置在出错时跳过的批次的最大重试次数，默认值为30。
+- `RESET_KAFKA_GROUP_OFFSETS`：（可选）设置启动pipe时Kafka的初始点位,不支持修改。可选值为`latest`、`earliest`、`none`、`valid`、`${TIMESTAMP\_MILLISECONDS}`
+    - 'none' 默认无操作
+    - 'valid' 检查 group 中的当前点位是否过期，将过期的 partition 点位重置到当前的 earliest 
+    - 'earliest' 重置到当前 earliest
+    - 'latest' 重置到当前 latest    
+    - '${TIMESTAMP\_MILLISECONDS}' 重置到毫秒时间戳对应点位，如 '1737789688000'（2025-01-25 15:21:28）
+
+## 三、验证结果
+
+可以通过查询目标表来验证数据是否成功导入：
+
+```sql
+SELECT * FROM kafka_sink_table_1;
+```
+
+同时，可以查看 Pipe 的运行状态，确保其正常工作：
+
+```sql
+SHOW PIPES;
+```
+
+此命令将列出所有已创建的 Pipe 及其状态信息，包括是否在运行、上次运行时间等。
+## 四、状态监控与管理
+### 查看Kafka消费延迟
+通过 DESC PIPE 命令。如下面的pipe_latency中的json字符串。
+    - lastConsumeTimestamp：上一次消费的点位
+    - offsetLag：Kafka数据得堆积量
+    - timeLag：消费延迟，计算为当前时间减去上一次消费的点位。当Kafka消费异常时值为-1
+
+
+````
+DESC PIPE EXTENDED kafka_pipe_stream
++--------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+|     info_name      |                                                                                                               info_value                                                            |
++--------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| name               | kafka_pipe_stream                                                                                                                                                                   |
+| creator            | UAT_TEST                                                                                                                                                                            |
+| created_time       | 2025-03-05 10:40:55.405                                                                                                                                                             |
+| last_modified_time | 2025-03-05 10:40:55.405                                                                                                                                                             |
+| comment            |                                                                                                                                                                                     |
+| properties         | ((virtual_cluster,test_alter))                                                                                                                                                      |
+| copy_statement     | COPY INTO TABLE qingyun.pipe_schema.kafka_sink_table_1 FROM (SELECT `current_timestamp`() AS ```current_timestamp``()`, CAST(kafka_table_stream_pipe1.`value` AS string) AS `value` |
+| pipe_status        | RUNNING                                                                                                                                                                             |
+| output_name        | xxxxxxx.pipe_schema.kafka_sink_table_1                                                                                                                                              |
+| input_name         | kafka_table_stream:xxxxxxx.pipe_schema.kafka_table_stream_pipe1                                                                                                                     |
+| invalid_reason     |                                                                                                                                                                                     |
+| pipe_latency       | {"kafka":{"lags":{"0":0,"1":0,"2":0,"3":0},"lastConsumeTimestamp":-1,"offsetLag":0,"timeLag":-1}}                                                                                   |
++--------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+
+````
+
+### 查看Pipe运行历史
+由于每次都是Pipe下发copy执行，你可以在作业历史中查看所有操作。通过[作业历史](<web-job-history.md>)中的query_tag来筛选，所有的pipe执行的copy作业都会在query_tag打上标签，格式为`pipe.``workspace_name``.schema_name.pipe_name`，方便追踪和管理。
+
+### 停止和启动Pipe
+- 暂停Pipe
+```
+ALTER PIPE pipe_name SET PIPE_EXECUTION_PAUSED = true;
+```
+- 启动Pipe
+```
+ALTER PIPE pipe_name SET PIPE_EXECUTION_PAUSED = false;
+```
+
+### 修改Pipe属性
+您可以修改 PIPE 的属性，但每次只能修改一个属性。如果需要修改多个属性，则需要多次执行 `ALTER` 命令。以下是可修改的属性及其语法：
+
+```SQL
+ALTER PIPE pipe_name SET 
+    [VIRTUAL_CLUSTER = 'virtual_cluster_name'],
+    [BATCH_INTERVAL_IN_SECONDS=''],
+    [BATCH_SIZE_PER_KAFKA_PARTITION=''],
+    [MAX_SKIP_BATCH_COUNT_ON_ERROR=''],
+    [COPY_JOB_HINT='']
+```
+案例
+```
+--修改计算集群
+ALTER PIPE pipe_name SET VIRTUAL_CLUSTER = 'default'
+--设置COPY_JOB_HINT
+ALTER PIPE pipe_name SET COPY_JOB_HINT='{"cz.mapper.kafka.message.size": "2000000"}'
+
+```
+**注意**
+- 不支持修改COPY语句逻辑，如果您需要修改请删除Pipe重新创建
+- 当你修改 Pipe 的 `COPY_JOB_HINT` 时，新的设置会覆盖原有的 hints。因此，如果你的 Pipe 中已经存在某些 hints，例如 `{"cz.sql.split.kafka.strategy":"size"}`，当你再次添加新的 hints 时，必须将所有需要的 hints 一起设置，否则原有的 hints 会被新设置的 hints 覆盖。多个参数之间使用逗号分隔

package/bin/skills/lakehouse-doc/references/pipe-kafka.md

@@ -0,0 +1,210 @@
+# 使用Pipe自动采集Kafka数据
+
+## 概述
+
+Pipe 是 Lakehouse 提供的**持续数据摄取**解决方案，专门用于从 Kafka 自动、持续地将数据导入到 Lakehouse 表中。Pipe 会创建持久的消费者组，保持消费位置，并按照设定的调度策略持续运行。
+
+## Kafka Pipe语法
+
+```SQL
+-- 从Kafka创建Pipe的语法
+CREATE PIPE [ IF NOT EXISTS ] <pipe_name>
+    VIRTUAL_CLUSTER = 'virtual_cluster_name'
+    [INITIAL_DELAY_IN_SECONDS='']
+    [BATCH_INTERVAL_IN_SECONDS='']
+    [BATCH_SIZE_PER_KAFKA_PARTITION='']
+    [MAX_SKIP_BATCH_COUNT_ON_ERROR='']
+    [RESET_KAFKA_GROUP_OFFSETS='']
+    [COPY_JOB_HINT='']
+AS <copy_statement>;
+```
+
+* `<pipe_name>`：Pipe 对象的名称，用于管理和监控
+* `VIRTUAL_CLUSTER`：指定执行 Pipe 任务的虚拟集群名称
+* `INITIAL_DELAY_IN_SECONDS`:首个作业调度延迟，选填项（默认 0 秒）
+* `BATCH_INTERVAL_IN_SECONDS`：（可选）设置批处理间隔时间，默认值为60秒。
+* `BATCH_SIZE_PER_KAFKA_PARTITION`：（可选）设置每个Kafka分区的批处理大小，默认值为500,000条。
+* `MAX_SKIP_BATCH_COUNT_ON_ERROR`：（可选）设置在出错时跳过的批次的最大重试次数，默认值为30。
+* `RESET_KAFKA_GROUP_OFFSETS`：（可选）控制 Pipe 启动时从 Kafka 的哪个位置开始消费数据只支持启动时设置，如果不设置此参数且消费者组无历史位置信息，将使用 Kafka 的 [auto.offset.reset](https://kafka.apache.org/documentation/#consumerconfigs_auto.offset.reset) 配置（默认为 `latest`）。支持的可选值如下
+  * 'none'无操作，如果设置为none则会使用[auto.offset.reset](https://kafka.apache.org/documentation/#consumerconfigs_auto.offset.reset)
+  * 'valid' 检查 group 中的当前点位是否过期，将过期的 partition 点位重置到当前的 earliest
+  * 'earliest' 重置到当前 earliest
+  * 'latest' 重置到当前 latest
+  * '${TIMESTAMP\_MILLISECONDS}' 重置到毫秒时间戳对应点位，如 '1737789688000'（2025-01-25 15:21:28）
+
+## 在 Pipe 中使用 READ\_KAFKA
+
+如果您想临时探查则可以使READ_KAFKA函数参考文档[READ_KAFKA函数](<sql_functions/table_functions/read_kafka.md>)，在 Pipe 的 COPY 语句中使用 `READ_KAFKA` 时，有以下**重要差异**：
+
+### 参数传递规则
+
+```sql
+-- Pipe 中的 READ_KAFKA 语法
+read_kafka (
+    'bootstrap_servers',     -- 必填：Kafka 集群地址
+    'topic',                 -- 必填：Topic 名称
+    '',                      -- 必填：Topic 模式（暂不支持，填空字符串）
+    'group_id',              -- 必填：持久消费者组 ID
+    '',                      -- 留空：起始位置由 Pipe 自动管理
+    '',                      -- 留空：结束位置由 Pipe 自动管理  
+    '',                      -- 留空：起始时间戳由 Pipe 自动管理
+    '',                      -- 留空：结束时间戳由 Pipe 自动管理
+    'raw',                   -- Key 格式
+    'raw',                   -- Value 格式
+    0,                       -- 最大错误数
+    map()                    -- Kafka 配置参数
+)
+```
+### 关键区别
+
+| 特性     | READ\_KAFKA 函数（独立使用）     | READ\_KAFKA（在 Pipe 中） |
+| ------ | ------------------------ | --------------------- |
+| 消费者组   | 临时，执行完即销毁                | 持久，保持消费位置状态           |
+| 位置管理   | 手动指定 starting\_offsets 等 | Pipe 自动管理，位置参数必须留空    |
+| 执行方式   | 一次性查询                    | 持续调度执行                |
+| 默认起始位置 | earliest（探查历史数据）         | latest（处理新数据）         |
+
+### 最佳实践
+参考使用 [Pipe 高效接入 kafka 数据](<pipe-kafka-bestpractice-1.md>)
+
+## 使用实例
+
+```SQL
+/*使用Lakehouse Pipe任务对象持续导入Kafka数据到目标表*/
+---Step01: 创建Kafka写入的目标表
+create table kafka_raw(value string);
+
+---Step02: 创建PIPE任务，从Kafka读取并写入目标表
+CREATE PIPE  load_kafka01
+VIRTUAL_CLUSTER = 'DEFAULT' 
+BATCH_INTERVAL_IN_SECONDS = '10'
+AS
+COPY INTO kafka_raw
+FROM (
+        SELECT
+                CAST(value AS string) as value
+        FROM 
+        read_kafka (
+        'host01:9092,host02:9092,host03:9092',-- bootstrap
+        'test',-- topic name
+        '', -- topic prefix 暂不支持
+        'pipe_kafka_group',-- group id
+        '',-- 点位相关参数，在 pipe ddl 中留空
+        '',-- 点位相关参数，在 pipe ddl 中留空
+        '',-- 点位相关参数，在 pipe ddl 中留空
+        '',-- 点位相关参数，在 pipe ddl 中留空
+        'raw',-- key  的 format，目前只支持 binary
+        'raw',-- value 的 format，目前只支持 binary
+        0,
+        map()
+        )
+);
+---Step03：查看与管理PIPE对象
+--查看pipe列表
+show pipes;
+
+pipe_name    copy_statement                                                                                                                                                                                                                                                                                                                                                                                                                                                                         
+-----             ------ 
+load_kafka01 COPY INTO TABLE ur_ws.public.kafka_raw FROM (SELECT CAST(read_kafka.`value` AS string) AS `value` FROM READ_KAFKA('host01:9092,host02:9092,host03:9092', 'mytopic', '', 'pipe_kafka_group', '', '', '', '', 'raw', 'raw', 0) read_kafka) 
+
+--查看pipe对象详情
+desc pipe load_kafka01;
+info_name          info_value                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             
+--                        ------- 
+name               load_kafka01                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           
+creator            czuser                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 
+created_time       2024-06-08 23:11:16.079                                                                                                                                                                                                                                                                                                                                                                                                                                                                                
+last_modified_time 2024-06-08 23:11:16.079                                                                                                                                                                                                                                                                                                                                                                                                                                                                                
+comment            my first pipe                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          
+properties         ((batch_interval_in_seconds,10),(virtual_cluster,DEFAULT))                                                                                                                                                                                                                                                                                                                                                                                                                                             
+copy_statement     COPY INTO TABLE ql_ws.rc5_l.kafka_raw FROM (SELECT CAST(read_kafka.`value` AS string) AS `value` FROM READ_KAFKA('host01:9092,host02:9092,host03:9092', 'mytopic', '', 'pipe_kafka_group', '', '', '', '', 'raw', 'raw', 0) read_kafka)                 
+copy_template      PCF1______::COPY INTO TABLE ql_ws.rc5_l.kafka_raw FROM (SELECT CAST(read_kafka.`value` AS string) AS `value` FROM READ_KAFKA('host01:9092,host02:9092,host03:9092', 'mytopic', '', 'pipe_kafka_group', PCF1______, '', '', 'raw', 'raw', 0) read_kafka) 
+pipe_status        PTS_RUNNING                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            
+invalid_reason                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            
+
+--查看导入数据
+SELECT * FROM kafka_raw LIMIT 100;
+
+--删除PIPE任务对象
+DROP PIPE load_kafka01;
+```
+
+
+
+## 状态监控与管理
+
+### 查看Kafka消费延迟
+
+通过 DESC PIPE 命令。如下面的pipe\_latency中的json字符串。
+\- lastConsumeTimestamp：上一次消费的点位
+\- offsetLag：Kafka数据得堆积量
+\- timeLag：消费延迟，计算为当前时间减去上一次消费的点位。当Kafka消费异常时值为-1
+
+````
+DESC PIPE EXTENDED kafka_pipe_stream
++--------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+|     info_name      |                                                                                                               info_value                                                            |
++--------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| name               | kafka_pipe_stream                                                                                                                                                                   |
+| creator            | UAT_TEST                                                                                                                                                                            |
+| created_time       | 2025-03-05 10:40:55.405                                                                                                                                                             |
+| last_modified_time | 2025-03-05 10:40:55.405                                                                                                                                                             |
+| comment            |                                                                                                                                                                                     |
+| properties         | ((virtual_cluster,test_alter))                                                                                                                                                      |
+| copy_statement     | COPY INTO TABLE qingyun.pipe_schema.kafka_sink_table_1 FROM (SELECT `current_timestamp`() AS ```current_timestamp``()`, CAST(kafka_table_stream_pipe1.`value` AS string) AS `value` |
+| pipe_status        | RUNNING                                                                                                                                                                             |
+| output_name        | xxxxxxx.pipe_schema.kafka_sink_table_1                                                                                                                                              |
+| input_name         | kafka_table_stream:xxxxxxx.pipe_schema.kafka_table_stream_pipe1                                                                                                                     |
+| invalid_reason     |                                                                                                                                                                                     |
+| pipe_latency       | {"kafka":{"lags":{"0":0,"1":0,"2":0,"3":0},"lastConsumeTimestamp":-1,"offsetLag":0,"timeLag":-1}}                                                                                   |
++--------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+
+````
+
+### 查看Pipe运行历史
+
+由于每次都是Pipe下发copy执行，你可以在作业历史中查看所有操作。通过[作业历史](web-job-history.md)中的query\_tag来筛选，所有的pipe执行的copy作业都会在query\_tag打上标签，格式为`pipe.``workspace_name``.schema_name.pipe_name`，方便追踪和管理。
+
+### 停止和启动Pipe
+
+* 暂停Pipe
+
+```
+ALTER PIPE pipe_name SET PIPE_EXECUTION_PAUSED = true;
+```
+
+* 启动Pipe
+
+```
+ALTER PIPE pipe_name SET PIPE_EXECUTION_PAUSED = false;
+```
+
+### 修改Pipe属性
+
+您可以修改 PIPE 的属性，但每次只能修改一个属性。如果需要修改多个属性，则需要多次执行 `ALTER` 命令。以下是可修改的属性及其语法：
+
+```SQL
+ALTER PIPE pipe_name SET 
+   [VIRTUAL_CLUSTER = 'virtual_cluster_name'],
+   [BATCH_INTERVAL_IN_SECONDS=''],
+   [BATCH_SIZE_PER_KAFKA_PARTITION=''],
+   [MAX_SKIP_BATCH_COUNT_ON_ERROR=''],
+   [COPY_JOB_HINT='']
+```
+
+案例
+
+```
+--修改计算集群
+ALTER PIPE pipe_name SET VIRTUAL_CLUSTER = 'default'
+--设置COPY_JOB_HINT
+ALTER PIPE pipe_name SET COPY_JOB_HINT='{"cz.mapper.kafka.message.size": "2000000"}'
+
+```
+
+**注意**
+
+* 不支持修改 COPY 语句逻辑，如果您需要修改，请删除 Pipe 后重新创建。
+* 当你修改 Pipe 的 `COPY_JOB_HINT` 时，新的设置会覆盖原有的 hints。因此，如果你的 Pipe 中已经存在某些 hints，例如 `{"cz.sql.split.kafka.strategy":"size"}`，当你再次添加新的 hints 时，必须将所有需要的 hints 一起设置，否则原有的 hints 会被新设置的 hints 覆盖。多个参数之间使用逗号分隔
+
+

package/bin/skills/lakehouse-doc/references/pipe-storage-object.md

@@ -0,0 +1,247 @@
+# 概述
+
+Pipe 是 Lakehouse 平台中的一项强大数据导入功能，它允许用户以固定频率直接从对象存储中读取数据并导入到 Lakehouse。通过实现文件检测机制，Pipe 支持以微批处理方式加载文件，使得用户能够迅速访问最新数据。特别适合需要实时或近实时数据处理的场景。
+
+## Pipe 工作原理
+
+1. **文件检测**：
+
+   1. **EVENT\_NOTIFICATION\_MODE**：需要开通消息服务，利用阿里云消息服务通知Lakehouse新文件的上传，目前只支持阿里云OSS和AWS S3。
+   2. **LIST\_PURGE模式**：定期扫描目录，同步未记录的文件，并在同步后删除原文件。
+
+2. **COPY 语句**：定义数据文件的源位置和目标表，支持多种文件格式。
+
+3. **自动化加载**：自动检测新文件并执行COPY语句。
+
+4. **避免导入重复机制**：为了避免重复导入，load\_history函数记录了当前表的copy导入历史文件。Pipe在执行时会根据load\_history表名和导入文件名称去重，确保不会重复导入已有的文件。如果需要导入已记录的文件，可以手动执行copy命令。load\_history记录目前会保留7天。
+
+5. **Pipe导入作业历史**：由于每次都是Pipe下发copy执行，你可以在作业历史中查看所有操作。通过作业历史中的query\_tag来筛选，所有的pipe执行的copy作业都会在query\_tag打上标签，格式为`pipe.``workspace_name``.schema_name.pipe_name`，方便追踪和管理。
+
+## 使用场景
+
+* **实时数据同步**：当你的数据存储在对象存储中，且需要频繁同步以及时获取最新数据。
+* **成本优化**：在对象存储上进行数据导入导出可以避免产生网络公网流量费用。特别是在相同region下，可以指定对象存储为内网传输，进一步降低成本。
+
+## 注意事项
+
+* 使用EVENT\_NOTIFICATION\_MODE时，需要使用role arn授权方式创建存储连接。
+* LIST\_PURGE模式支持密钥和role arn两种授权方式。
+* **文件大小推荐**：gzip 压缩文件建议在 50MB。CSV、PARQUET 未压缩文件建议在 128MB 到 256MB 之间。
+* **数据加载顺序**：**数据加载无法保证严格有序**。
+* **Pipe 延迟**:Pipe加载时间受多种因素影响，包括文件格式、大小和COPY语句的复杂性。
+* **Pipe 与 Volume 对应关系**： 每个 Pipe 需对应独立的 Volume，不可复用。
+- 不支持修改COPY语句逻辑，如果您需要修改请删除Pipe重新创建
+- 当你修改 Pipe 的 `COPY_JOB_HINT` 时，新的设置会覆盖原有的 hints。因此，如果你的 Pipe 中已经存在某些 hints，例如 `{"cz.sql.split.kafka.strategy":"size"}`，当你再次添加新的 hints 时，必须将所有需要的 hints 一起设置，否则原有的 hints 会被新设置的 hints 覆盖。多个参数之间使用逗号分隔
+- PIPE中的COPY语句不支持files/regexp/subdirectory参数
+
+
+## 成本
+
+根据加载文件时使用的计算资源计费。
+## PIPE语法
+```SQL
+-- 从对象存储创建Pipe的语法
+CREATE PIPE [ IF NOT EXISTS ] <pipe_name>
+    VIRTUAL_CLUSTER = 'virtual_cluster_name'
+    INGEST_MODE='LIST_PURGE'|'EVENT_NOTIFICATION'
+    [COPY_JOB_HINT='']
+AS <copy_statement>;
+```
+- `<pipe_name>`：您要创建的Pipe对象的名称。
+- `VIRTUAL_CLUSTER`：指定虚拟集群的名称。
+- `INGEST_MODE`：设置为`LIST_PURGE`或`EVENT_NOTIFICATION`，以确定数据导入模式。
+- `COPY_JOB_HINT`：可选，Lakehouse保留参数
+- copy_statement：`<copy_statement>` 支持 中的中的文件参数都支持。当设置 `ON_ERROR=CONTINUE|ABORT` 参数时，可控制数据加载过程中遇到错误时的处理策略，且添加该参数后会返回导入文件列表：
+    * `CONTINUE`：跳过错误行，继续加载后续数据。适用于容忍部分错误，且要求最大限度完成数据加载的场景。目前，可忽略的错误仅限于文件不格式匹配的情况，例如命令中指定为 zip 压缩格式，而文件中存在 zstd 压缩格式。
+    * `ABORT`：立即终止整个`COPY`操作。适用于数据质量要求严格，任何错误都需要人工介入检查的场景。
+
+
+## 支持的文件格式
+
+参考[COPY INTO导入](copy-into-table.md)。
+
+## 使用PIPE加载案例
+
+### 使用扫描文件模式
+
+**具体使用步骤**
+
+步骤 1: 创建 connection 和 volume
+
+```SQL
+--创建连接用来连接对象存储
+CREATE STORAGE CONNECTION if not exists my_connection_exnet
+    TYPE OSS
+    ENDPOINT = 'oss-cn-hangzhou.aliyuncs.com'
+    ACCESS_KEY = 'LTAI5tMmbq1Ty1xxxxxxxxx'
+    SECRET_KEY = '0d7Ap1VBuFTzNg7gxxxxxxxxxxxx'
+    COMMENT = 'OSS public endpoint';
+
+--创建volume, 用于映射对象存储目录
+CREATE EXTERNAL VOLUME pipe_volume
+    location 'oss://ossmy/autoloader/pipe/'
+    using connection my_connection_exnet
+    directory = (
+        enable=true,
+        auto_refresh=true
+    )
+    recursive=true;
+    
+```
+
+步骤 2: 单独执行copy命令看是否可以导入成功
+
+```SQL
+copy into pipe_purge_mode from volume pipe_volume(id int,col string) 
+using csv OPTIONS(
+  'header'='false'
+) ;
+```
+
+步骤 3: 使用上面的语句构建pipe对象
+
+```SQL
+create pipe volume_pipe_list_purge
+  VIRTUAL_CLUSTER = 'default'
+  --执行获取最新文件使用扫描文件模式
+  INGEST_MODE = 'LIST_PURGE'
+  as
+copy into pipe_purge_mode from volume pipe_volume(id int,col string) 
+using csv OPTIONS(
+  'header'='false'
+)
+--必须添加purge参数导入成功后删除数据 
+purge=true
+;
+```
+
+步骤 4: 查看pipe执行历史和已经导入的文件
+
+* 查看pipe copy作业执行情况
+
+通过作业历史中的query\_tag来筛选,所有的pipe执行的copy作业都会在query\_tag打上标签:格式为pipe.worksapce\_name.schema\_name.pipe\_name
+
+* 查看copy作业导入的历史文件
+
+```SQL
+select * from load_history('schema_name.table_name');
+```
+
+### 使用消息服务通知模式（只支持阿里云OSS和AWS S3）
+
+步骤 1: 开通阿里云消息服务 (MNS)
+
+1. 在阿里云控制台中开通消息服务 MNS。
+2. 配置 MNS 监听要同步的 OSS (Object Storage Service) 文件夹。[具体参考文档](https://help.aliyun.com/zh/mns/user-guide/create-a-rule-to-generate-oss-event-notifications?spm=a2c4g.11186623.0.i14)
+
+步骤 2: 授权 Lakehouse 读取 OSS
+具体方式参考使用role arn方式[阿里云存储连接创建](aliyun_storage_connection.md)授权 Lakehouse 读取对应 OSS Bucket 的权限。
+
+步骤 3: 授权 MNS 给 Lakehouse
+
+```
+ 在阿里云 RAM 控制台中，将 `AliyunMNSFullAccess` 权限授权给步骤二中的 Role，步骤二中案例为CzUDFRole
+```
+
+![](.topwrite/assets/image_1722602785678.png)
+
+步骤 4: 创建 Storage Connection
+
+```SQL
+CREATE STORAGE CONNECTION my_connection_exnet_role
+    TYPE oss
+    REGION = 'cn-hangzhou'  -- 根据 OSS 所在的区域选择
+    ROLE_ARN = 'acs:ram::...:role/czudfrole'  -- 替换为你的 Role ARN
+    ENDPOINT = 'oss-cn-hangzhou.aliyuncs.com';  -- 根据 OSS 所在的区域选择 Endpoint
+```
+
+步骤 5: 创建 Volume
+
+```SQL
+CREATE EXTERNAL VOLUME my_volume_exnet_role
+    LOCATION 'oss://function-compute-my1/autoloader'  -- 替换为 OSS Bucket 的路径
+    USING connection my_connection_exnet_role
+    DIRECTORY = (
+        enable = TRUE,
+        auto_refresh = TRUE
+    )
+    RECURSIVE = TRUE;
+```
+
+步骤 6: 创建 Pipe
+
+```SQL
+CREATE PIPE my_pipe
+VIRTUAL_CLUSTER='TEST_VC'
+ALICLOUD_MNS_QUEUE = 'lakehouse-oss-event-queue'  -- 使用创建的 MNS 队列
+AS
+COPY INTO pipe_log_json FROM (
+    SELECT parse_json(col) json_col
+    FROM volume my_volume_exnet_role(col string)
+    USING csv
+    OPTIONS ('header' = 'false', 'sep' = '\001', 'quote' = '\0')
+);
+```
+
+## 状态监控与管理
+### 查看Pipe状态
+
+
+
+````
+DESC PIPE EXTENDED kafka_pipe_stream
++--------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+|     info_name      |                                                                                                               info_value                                                            |
++--------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| name               | kafka_pipe_stream                                                                                                                                                                   |
+| creator            | UAT_TEST                                                                                                                                                                            |
+| created_time       | 2025-03-05 10:40:55.405                                                                                                                                                             |
+| last_modified_time | 2025-03-05 10:40:55.405                                                                                                                                                             |
+| comment            |                                                                                                                                                                                     |
+| properties         | ((virtual_cluster,test_alter))                                                                                                                                                      |
+| copy_statement     | COPY INTO TABLE qingyun.pipe_schema.kafka_sink_table_1 FROM (SELECT `current_timestamp`() AS ```current_timestamp``()`, CAST(kafka_table_stream_pipe1.`value` AS string) AS `value` |
+| pipe_status        | RUNNING                                                                                                                                                                             |
+| output_name        | xxxxxxx.pipe_schema.kafka_sink_table_1                                                                                                                                              |
+| input_name         | kafka_table_stream:xxxxxxx.pipe_schema.kafka_table_stream_pipe1                                                                                                                     |
+| invalid_reason     |                                                                                                                                                                                     |
+| pipe_latency       | {"kafka":{"lags":{"0":0,"1":0,"2":0,"3":0},"lastConsumeTimestamp":-1,"offsetLag":0,"timeLag":-1}}                                                                                   |
++--------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+
+````
+
+### 查看Pipe运行历史
+由于每次都是Pipe下发copy执行，你可以在作业历史中查看所有操作。通过[作业历史](<web-job-history.md>)中的query_tag来筛选，所有的pipe执行的copy作业都会在query_tag打上标签，格式为`pipe.``workspace_name``.schema_name.pipe_name`，方便追踪和管理。
+
+### 停止和启动Pipe
+- 暂停Pipe
+```
+ALTER PIPE pipe_name SET PIPE_EXECUTION_PAUSED = true;
+```
+- 启动Pipe
+```
+ALTER PIPE pipe_name SET PIPE_EXECUTION_PAUSED = false
+```
+
+### 修改Pipe属性
+您可以修改 PIPE 的属性，但每次只能修改一个属性。如果需要修改多个属性，则需要多次执行 `ALTER` 命令。以下是可修改的属性及其语法：
+
+```SQL
+ALTER PIPE pipe_name SET 
+   [VIRTUAL_CLUSTER = 'virtual_cluster_name']
+   [BATCH_INTERVAL_IN_SECONDS='']
+   [BATCH_SIZE_PER_KAFKA_PARTITION='']
+   [MAX_SKIP_BATCH_COUNT_ON_ERROR='']
+   [RESET_KAFKA_GROUP_OFFSETS='']
+   [COPY_JOB_HINT='']
+```
+案例
+```
+--修改计算集群
+ALTER PIPE pipe_name SET VIRTUAL_CLUSTER = 'default'
+--设置COPY_JOB_HINT
+ALTER PIPE pipe_name SET COPY_JOB_HINT='{"cz.mapper.kafka.message.size": "2000000"}'
+
+```
+
+
+