@clickzetta/cz-cli-darwin-x64 0.3.17 → 0.3.18

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

@@ -0,0 +1,185 @@
+# Dynamic Table（动态表）SQL 参考
+
+> **⚠️ ClickZetta 特有语法**
+> - 刷新调度写法：`REFRESH INTERVAL 5 MINUTE vcluster default`（不是 `TARGET_LAG`）
+> - 修改调度周期或计算集群必须用 `CREATE OR REPLACE`，`ALTER` 不支持
+> - `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 查询定义，自动增量刷新，无需手动调度。
+
+## CREATE DYNAMIC TABLE
+
+```sql
+CREATE [ OR REPLACE ] DYNAMIC TABLE <name>
+  [ (<column_list>) ]
+  [ PARTITIONED BY (<col_name>) ]
+  [ CLUSTERED BY (<col_name>) ]
+  [ COMMENT <comment> ]
+  [ PROPERTIES ( data_lifecycle = <day_num> ) ]
+  REFRESH [ START WITH TIMESTAMP '<timestamp>' ] INTERVAL <n> { SECOND | MINUTE | HOUR | DAY }
+  vcluster <vcluster_name>
+AS
+  <query>;
+```
+
+**关键参数：**
+- `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
+AS
+SELECT
+  date_trunc('hour', created_at) AS hour,
+  region,
+  COUNT(*) AS order_cnt,
+  SUM(amount) AS total_amount
+FROM ods.orders
+GROUP BY 1, 2;
+
+-- 修改调度周期（必须用 CREATE OR REPLACE）
+CREATE OR REPLACE DYNAMIC TABLE dw.order_summary
+  REFRESH INTERVAL 10 MINUTE vcluster default
+AS
+SELECT
+  date_trunc('hour', created_at) AS hour,
+  region,
+  COUNT(*) AS order_cnt,
+  SUM(amount) AS total_amount
+FROM ods.orders
+GROUP BY 1, 2;
+```
+
+## ALTER DYNAMIC TABLE
+
+```sql
+-- 暂停刷新
+ALTER DYNAMIC TABLE <name> SUSPEND;
+
+-- 恢复刷新
+ALTER DYNAMIC TABLE <name> RESUME;
+
+-- 修改注释
+ALTER DYNAMIC TABLE <name> SET COMMENT '<comment>';
+
+-- 修改列名
+ALTER DYNAMIC TABLE <name> RENAME COLUMN <old_col> TO <new_col>;
+
+-- 修改列注释（注意用 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');
+```
+
+> 注意：修改调度周期、计算集群、SQL 查询逻辑，必须用 `CREATE OR REPLACE DYNAMIC TABLE`，ALTER 不支持这些操作。
+
+## REFRESH DYNAMIC TABLE（手动触发）
+
+```sql
+-- 手动触发一次刷新
+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
+
+```sql
+-- 列出当前 schema 下所有动态表
+SHOW TABLES WHERE is_dynamic = true;
+
+-- 列出指定 schema 下的动态表
+SHOW TABLES IN <schema_name> WHERE is_dynamic = true;
+
+-- 查看动态表结构
+DESC TABLE <name>;
+
+-- 查看完整建表语句
+SHOW CREATE TABLE <name>;
+
+-- 查看刷新历史（状态、耗时、触发方式、增量行数）
+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 分钟
+- 删除用 `DROP DYNAMIC TABLE`（不是 `DROP TABLE`）
+- 恢复用 `UNDROP TABLE`（不是 `UNDROP DYNAMIC TABLE`）
+- 刷新失败不影响表的可查询性（返回上次成功版本的数据）
+- 非简单加列/减列的 `CREATE OR REPLACE` 会触发一次全量刷新
+- 建议使用 GP 型集群（如 `default`），AP 型集群不支持小文件合并
+
+## 参数化动态表（SESSION_CONFIGS）
+
+通过 `SESSION_CONFIGS()` 函数定义参数化查询，在刷新时传入分区值控制刷新范围：
+
+```sql
+-- 创建参数化动态表
+CREATE OR REPLACE DYNAMIC TABLE dwd.orders_partitioned
+  REFRESH INTERVAL 30 MINUTE vcluster default
+AS
+SELECT order_id, user_id, amount, dt
+FROM ods.orders
+WHERE dt = SESSION_CONFIGS('target_date', CAST(CURRENT_DATE() AS STRING));
+
+-- 手动触发刷新并传入参数
+REFRESH DYNAMIC TABLE dwd.orders_partitioned
+  WITH PROPERTIES ('target_date' = '2024-06-15');
+```
+
+适用场景：传统按天全量 ETL 改造为增量任务，用 SESSION_CONFIGS 替换调度变量。
+
+## 动态表 DML 操作
+
+动态表默认不支持 DML，需先开启参数（每次 DML 前都需要 SET）：
+
+```sql
+-- ⚠️ 必须在同一会话/批次中先执行 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 注意事项**：
+> - `SET cz.sql.dt.allow.dml = true` 必须与 DML 语句在同一执行批次中
+> - 执行 DML 后，下一次自动刷新会触发**全量刷新**（而非增量），可能耗时较长
+> - UPDATE 可能因内部隐藏列（`MV__KEY`）报错，建议改用 DELETE + INSERT
+> - 仅在数据修正等特殊场景使用 DML
+
+## 参考文档
+
+- [CREATE DYNAMIC TABLE](https://www.yunqi.tech/documents/create-dynamic-table)
+- [ALTER DYNAMIC TABLE](https://www.yunqi.tech/documents/alter-dynamic-table)
+- [DROP DYNAMIC TABLE](https://www.yunqi.tech/documents/drop-dynamic-table)
+- [SHOW DYNAMIC TABLES](https://www.yunqi.tech/documents/show-dynamic-table)
+- [SHOW DYNAMIC TABLE REFRESH HISTORY](https://www.yunqi.tech/documents/refresh-history)
+- [动态表简介](https://www.yunqi.tech/documents/dynamic_table_summary)
+- [查看动态表刷新模式](https://www.yunqi.tech/documents/dynamic-table-incre)
+- [传统离线任务转增量实践](https://www.yunqi.tech/documents/transformt-dt)
+- [动态表支持参数化定义](https://www.yunqi.tech/documents/dynamicTable-parmaters)
+- [动态表支持DML语句修改](https://www.yunqi.tech/documents/dynamicTable-dml)

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

@@ -0,0 +1,129 @@
+# Materialized View（物化视图）SQL 参考
+
+> **⚠️ ClickZetta 特有语法**
+> - 定时刷新：`REFRESH INTERVAL 10 MINUTE vcluster default`（与动态表语法相同）
+> - 手动刷新：`REFRESH MATERIALIZED VIEW <name>;`
+> - 修改注释用 `ALTER TABLE`，不是 `ALTER MATERIALIZED VIEW`
+
+物化视图将查询结果预计算并物理存储，适合固定维度的聚合加速场景。与动态表的区别：物化视图支持手动或定时刷新，不支持增量刷新。
+
+## CREATE MATERIALIZED VIEW
+
+```sql
+CREATE [ OR REPLACE ] MATERIALIZED VIEW <name>
+  [ COMMENT = '<comment>' ]
+  [ BUILD DEFERRED ]
+  [ REFRESH INTERVAL <N> { SECOND | MINUTE | HOUR | DAY } vcluster <vcluster_name> ]
+  [ DISABLE QUERY REWRITE ]
+AS
+  <query>;
+```
+
+**关键参数：**
+- `REFRESH INTERVAL 10 MINUTE vcluster default`：定时自动刷新（与动态表语法相同）
+- 不写 REFRESH 子句：只能手动触发 `REFRESH MATERIALIZED VIEW <name>;`
+- `BUILD DEFERRED`：延迟构建，创建时不立即计算结果
+- `DISABLE QUERY REWRITE`：禁用查询改写（不自动用 MV 加速查询）
+
+**示例：**
+```sql
+-- 定时自动刷新的物化视图（每 10 分钟）
+CREATE MATERIALIZED VIEW mv_dept_stats
+REFRESH INTERVAL 10 MINUTE vcluster default
+AS
+SELECT
+  d.dept_id,
+  d.dept_name,
+  COUNT(e.emp_id) AS emp_count,
+  AVG(e.salary) AS avg_salary
+FROM departments d
+JOIN employees e ON d.dept_id = e.dept_id
+GROUP BY d.dept_id, d.dept_name;
+
+-- 修改刷新周期（需要 CREATE OR REPLACE）
+CREATE OR REPLACE MATERIALIZED VIEW mv_dept_stats
+BUILD DEFERRED
+REFRESH INTERVAL 20 MINUTE vcluster default
+DISABLE QUERY REWRITE
+AS
+SELECT
+  d.dept_id,
+  d.dept_name,
+  d.location,
+  ANY_VALUE(d.col1) AS col1,
+  COUNT(e.emp_id) AS emp_count,
+  AVG(e.salary) AS avg_salary
+FROM departments d
+JOIN employees e ON d.dept_id = e.dept_id
+GROUP BY d.dept_id, d.dept_name, d.location;
+
+-- 手动刷新
+REFRESH MATERIALIZED VIEW mv_dept_stats;
+```
+
+## ALTER MATERIALIZED VIEW
+
+```sql
+-- 暂停自动刷新
+ALTER MATERIALIZED VIEW <name> SUSPEND;
+
+-- 恢复自动刷新
+ALTER MATERIALIZED VIEW <name> RESUME;
+
+-- 修改注释
+ALTER TABLE <mv_name> SET COMMENT '<comment>';
+
+-- 修改列注释（物化视图用 ALTER TABLE 语法）
+ALTER TABLE <mv_name> CHANGE COLUMN <col_name> COMMENT '<comment>';
+```
+
+> 注意：物化视图的注释修改使用 `ALTER TABLE`，不是 `ALTER MATERIALIZED VIEW`。
+
+## REFRESH MATERIALIZED VIEW
+
+```sql
+-- 手动触发全量刷新
+REFRESH MATERIALIZED VIEW <name>;
+```
+
+## DROP MATERIALIZED VIEW
+
+```sql
+DROP MATERIALIZED VIEW [ IF EXISTS ] <name>;
+```
+
+## SHOW / DESC
+
+```sql
+-- 列出当前 schema 下所有物化视图
+SHOW TABLES WHERE is_materialized_view = true;
+
+-- 按名称过滤
+SHOW TABLES LIKE 'mv_%' WHERE is_materialized_view = true;
+
+-- 查看物化视图结构
+DESC MATERIALIZED VIEW <name>;
+DESCRIBE MATERIALIZED VIEW <name> EXTENDED;
+
+-- 查看完整建表语句
+SHOW CREATE TABLE <name>;
+```
+
+## 动态表 vs 物化视图 选择指南
+
+| 场景 | 推荐 |
+|---|---|
+| 需要秒/分钟级自动增量刷新 | Dynamic Table |
+| 固定聚合，手动或低频刷新 | Materialized View |
+| 需要 CDC 变更感知 | Dynamic Table + Table Stream |
+| 加速 BI 查询，数据不要求实时 | Materialized View |
+
+## 参考文档
+
+- [CREATE MATERIALIZED VIEW](https://www.yunqi.tech/documents/CREATEMATERIALIZEDVIEW)
+- [ALTER MATERIALIZED VIEW](https://www.yunqi.tech/documents/alter-materialzied-view)
+- [REFRESH MATERIALIZED VIEW](https://www.yunqi.tech/documents/REFRESH)
+- [DROP MATERIALIZED VIEW](https://www.yunqi.tech/documents/DROPMATERIALIZEDVIEW)
+- [SHOW MATERIALIZED VIEWS](https://www.yunqi.tech/documents/show-materialized-view)
+- [物化视图概念与场景](https://www.yunqi.tech/documents/MATERIALIZEDVIEW)
+- [物化视图 DDL 汇总](https://www.yunqi.tech/documents/materialized_ddl)

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

@@ -0,0 +1,222 @@
+# Pipe SQL 参考
+
+> **⚠️ ClickZetta 特有语法**
+> - 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）自动、持续地将数据导入目标表，无需外部调度。
+
+## CREATE PIPE — 从 Kafka 导入
+
+```sql
+CREATE [ OR REPLACE ] PIPE <pipe_name>
+  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
+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 配置参数
+  )
+);
+```
+
+**示例：**
+```sql
+-- 从 Kafka 持续导入 JSON 数据
+CREATE OR REPLACE 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,
+    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'
+  [ COMMENT '<comment>' ]
+  [ COPY_JOB_HINT = '<hint>' ]
+AS
+COPY INTO <target_table>
+FROM VOLUME <volume_name>
+USING <csv | parquet | orc | json> [OPTIONS ('<key>' = '<value>', ...)] PURGE=true;
+```
+
+**关键参数：**
+- `VIRTUAL_CLUSTER`：指定虚拟集群名称（OSS Pipe 必填）
+- `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
+-- LIST_PURGE 模式（带 OPTIONS）
+CREATE OR REPLACE PIPE oss_events_pipe
+  VIRTUAL_CLUSTER = 'default'
+  INGEST_MODE = 'LIST_PURGE'
+  COMMENT 'OSS events pipeline'
+AS
+COPY INTO ods.events
+FROM VOLUME my_oss_volume
+USING PARQUET PURGE=true;
+
+-- 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
+FROM VOLUME my_oss_event_volume
+USING PARQUET;
+```
+
+## 启停 Pipe
+
+```sql
+-- 暂停 Pipe
+ALTER PIPE <pipe_name> SET PIPE_EXECUTION_PAUSED = true;
+
+-- 恢复 Pipe
+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
+DROP PIPE [ IF EXISTS ] <pipe_name>;
+```
+
+## SHOW PIPE
+
+```sql
+-- 列出当前 schema 下所有 Pipe
+SHOW PIPES;
+
+-- 查看 Pipe 详情（状态、延迟、定义）
+DESC PIPE <pipe_name>;
+DESC PIPE EXTENDED <pipe_name>;
+```
+
+## 注意事项
+
+- Pipe 创建后默认自动启动，无需手动 RESUME
+- 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-summary)
+- [借助 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)
+- [使用 Pipe 持续导入对象存储数据](https://www.yunqi.tech/documents/pipe-storage-object)

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

@@ -0,0 +1,125 @@
+# Table Stream（表流）SQL 参考
+
+> **⚠️ ClickZetta 特有语法**
+> - 创建语法是 `CREATE TABLE STREAM`，参数放在 `WITH PROPERTIES (...)` 里
+> - 元数据字段是 `__change_type`（双下划线），值：`INSERT` / `UPDATE_BEFORE` / `UPDATE_AFTER` / `DELETE`
+> - UPDATE 产生两条记录：`UPDATE_BEFORE`（更新前）和 `UPDATE_AFTER`（更新后）
+> - 通常只需要 `UPDATE_AFTER` 和 `INSERT`，忽略 `UPDATE_BEFORE`
+
+Table Stream 捕获源表的变更数据（INSERT / UPDATE / DELETE），是构建 CDC 管道的核心对象。通常与 Dynamic Table 或 SQL 任务配合消费变更数据。
+
+## CREATE TABLE STREAM
+
+```sql
+CREATE [ OR REPLACE ] TABLE STREAM [ IF NOT EXISTS ] <stream_name>
+  ON TABLE <source_name>
+  [ TIMESTAMP AS OF <timestamp_expr> ]
+  [ COMMENT '<comment>' ]
+  WITH PROPERTIES (
+    'TABLE_STREAM_MODE' = 'STANDARD | APPEND_ONLY',
+    'SHOW_INITIAL_ROWS' = 'TRUE | FALSE'
+  );
+```
+
+**关键参数：**
+- `TABLE_STREAM_MODE = STANDARD`（默认）：捕获 INSERT、UPDATE、DELETE 所有变更，每行附带 `__change_type` 字段（`INSERT` / `UPDATE_BEFORE` / `UPDATE_AFTER` / `DELETE`）
+- `TABLE_STREAM_MODE = APPEND_ONLY`：只捕获 INSERT，性能更好，适合仅追加写入的源表
+- `SHOW_INITIAL_ROWS = TRUE`：首次消费返回建 Stream 时表中已有行；`FALSE`（默认）仅返回建 Stream 后的新变更
+- `TIMESTAMP AS OF`：指定 Stream 从哪个时间点开始捕获变更
+
+**示例：**
+```sql
+-- 在普通表上创建标准流（捕获所有变更，需先开启 change_tracking）
+ALTER TABLE ods.orders SET PROPERTIES ('change_tracking' = 'true');
+
+CREATE TABLE STREAM orders_stream
+  ON TABLE ods.orders
+  WITH PROPERTIES ('TABLE_STREAM_MODE' = 'STANDARD');
+
+-- 仅追加流
+CREATE TABLE STREAM events_stream
+  ON TABLE dw.events
+  COMMENT '事件流，仅追加'
+  WITH PROPERTIES ('TABLE_STREAM_MODE' = 'APPEND_ONLY');
+
+-- 从指定时间点开始捕获
+CREATE TABLE STREAM orders_stream_from_ts
+  ON TABLE ods.orders
+  TIMESTAMP AS OF '2024-01-01 00:00:00'
+  WITH PROPERTIES ('TABLE_STREAM_MODE' = 'STANDARD', 'SHOW_INITIAL_ROWS' = 'TRUE');
+```
+
+## 消费 Table Stream
+
+Table Stream 的 offset 通过 DML 操作移动。**仅 SELECT 不会移动 offset**，可以反复查询预览。执行 DML（INSERT INTO / MERGE INTO / UPDATE / DELETE）消费数据后，offset 前进。
+
+```sql
+-- 查看当前未消费的变更数据（不移动 offset）
+SELECT * FROM orders_stream;
+
+-- 变更数据包含的系统字段
+-- __change_type: INSERT | UPDATE_BEFORE | UPDATE_AFTER | DELETE
+-- __commit_version: 变更版本号
+-- __commit_timestamp: 变更发生时间
+
+-- 典型用法：将变更数据 MERGE 到目标表（过滤掉 UPDATE_BEFORE）
+MERGE INTO dw.orders_dim AS target
+USING (
+  SELECT * FROM orders_stream
+  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 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
+AS
+SELECT order_id, status, amount, __change_type, __commit_timestamp
+FROM orders_stream
+WHERE __change_type IN ('INSERT', 'UPDATE_AFTER');
+```
+
+## DROP TABLE STREAM
+
+```sql
+DROP TABLE STREAM [ IF EXISTS ] <stream_name>;
+```
+
+## SHOW / DESC
+
+```sql
+-- 列出当前 schema 下所有 Table Stream
+SHOW TABLE STREAMS;
+
+-- 列出指定 schema 下的 Table Stream
+SHOW TABLE STREAMS IN <schema_name>;
+
+-- 按名称过滤
+SHOW TABLE STREAMS LIKE 'orders%';
+
+-- 查看 Table Stream 详情（源表、模式、创建时间）
+DESC TABLE STREAM <stream_name>;
+```
+
+## 注意事项
+
+- 仅 SELECT 不会移动 offset，可反复查询预览
+- DML 操作（INSERT INTO / MERGE INTO / UPDATE / DELETE）会移动 offset
+- ⚠️ 即使 DML 带 WHERE 条件过滤了部分行，**所有行的 offset 都会移动**
+- 若长时间不消费，超出源表的 `data_retention_days` 后数据会丢失
+- `STANDARD` 模式下 UPDATE 会产生两条记录：`UPDATE_BEFORE`（更新前）和 `UPDATE_AFTER`（更新后）
+- 消费时通常过滤 `__change_type != 'UPDATE_BEFORE'`，忽略旧值
+- 源表需先开启 `change_tracking`：`ALTER TABLE name SET PROPERTIES ('change_tracking' = 'true')`
+
+## 参考文档
+
+- [CREATE TABLE STREAM](https://www.yunqi.tech/documents/create-table-stream)
+- [DESC TABLE STREAM](https://www.yunqi.tech/documents/desc-table-stream)
+- [SHOW TABLE STREAMS](https://www.yunqi.tech/documents/show-table-streams)
+- [DROP TABLE STREAM](https://www.yunqi.tech/documents/drop-table-stream)
+- [TABLE STREAM 简介](https://www.yunqi.tech/documents/tablestream_summary)
+- [Table Stream 变化数据捕获](https://www.yunqi.tech/documents/table_stream)
+- [Table Stream 最佳实践](https://www.yunqi.tech/documents/lakehouse-table-stream-best-practices)