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

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

@@ -0,0 +1,173 @@
+# 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
+
+动态表是 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_expr> ] interval <n> { SECOND | MINUTE | HOUR | DAY }
+  VCLUSTER <vcluster_name>
+AS
+  <query>;
+```
+
+**关键参数：**
+- `REFRESH interval <n> MINUTE`：刷新间隔，最小 1 分钟
+- `VCLUSTER`：运行刷新任务的计算集群名称（直接跟名称，不带等号和引号）
+- `OR REPLACE`：若同名动态表已存在则替换（修改 SQL 逻辑或调度配置必须用此方式）
+
+**示例：**
+```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>;
+
+-- 修改列注释
+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 [ IF EXISTS ] <name>;
+```
+
+## SHOW / DESC
+
+```sql
+-- 列出当前 schema 下所有动态表
+SHOW TABLES WHERE is_dynamic = true;
+
+-- 列出指定 schema 下的动态表
+SHOW TABLES IN <schema_name> WHERE is_dynamic = true;
+
+-- 查看动态表结构和调度配置
+DESC TABLE <name>;
+DESCRIBE DYNAMIC TABLE <name> EXTENDED;
+
+-- 查看完整建表语句
+SHOW CREATE TABLE <name>;
+
+-- 查看刷新历史（状态、耗时、触发方式、增量行数）
+SHOW DYNAMIC TABLE REFRESH HISTORY <name>;
+SHOW DYNAMIC TABLE REFRESH HISTORY <name> LIMIT 20;
+```
+
+## 注意事项
+
+- 修改 SQL 逻辑、调度周期、计算集群 → 用 `CREATE OR REPLACE`，不能用 `ALTER`
+- 刷新间隔最小 1 分钟
+- 动态表支持 Time Travel（`TIMESTAMP AS OF`）和 UNDROP
+- 刷新失败不影响表的可查询性（返回上次成功版本的数据）
+- 非简单加列/减列的 `CREATE OR REPLACE` 会触发一次全量刷新
+
+## 参数化动态表（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，需先开启参数：
+
+```sql
+-- 开启 DML 支持
+ALTER DYNAMIC TABLE <name> SET PROPERTIES ('cz.dynamic.table.enable.dml' = 'true');
+
+-- 支持的 DML 操作
+INSERT INTO <name> VALUES (...);
+DELETE FROM <name> WHERE ...;
+```
+
+> ⚠️ 执行 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,160 @@
+# Pipe SQL 参考
+
+> **⚠️ ClickZetta 特有语法**
+> - Kafka 读取函数是 `READ_KAFKA(...)`，不是 `KAFKA_SOURCE(...)` 或其他写法
+> - 参数使用 `=>` 命名参数语法：`KAFKA_BROKER => 'host:port'`
+> - JSON 字段提取用 `$1:field_name::TYPE` 语法（`$1` 表示整行 JSON）
+> - Pipe 创建后默认自动启动，无需手动 RESUME
+
+Pipe 是 ClickZetta Lakehouse 的持续数据导入对象，通过 SQL 定义从 Kafka 或对象存储（OSS/S3/COS）自动、持续地将数据导入目标表，无需外部调度。
+
+## CREATE PIPE — 从 Kafka 导入
+
+```sql
+CREATE [ OR REPLACE ] PIPE <pipe_name>
+  [ COMMENT = '<comment>' ]
+  [ AUTO_INGEST = { TRUE | FALSE } ]
+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>' ]
+  )
+);
+```
+
+**示例：**
+```sql
+-- 从 Kafka 持续导入 JSON 数据
+CREATE OR REPLACE PIPE kafka_orders_pipe
+  COMMENT '从 Kafka 持续导入订单数据'
+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'
+  )
+);
+```
+
+## CREATE PIPE — 从对象存储导入
+
+```sql
+CREATE [ OR REPLACE ] PIPE [ IF NOT EXISTS ] <pipe_name>
+  VIRTUAL_CLUSTER = <virtual_cluster_name>
+  INGEST_MODE = { LIST_PURGE | EVENT_NOTIFICATION }
+  [ COPY_JOB_HINT = '<hint>' ]
+AS
+COPY INTO <target_table>
+FROM VOLUME <volume_name>
+USING <csv | parquet | orc | json>
+[ OPTIONS ('<key>' = '<value>', ...) ];
+```
+
+**关键参数：**
+- `VIRTUAL_CLUSTER`：指定虚拟集群名称（OSS Pipe 必填）
+- `INGEST_MODE = LIST_PURGE`：通用模式，定期扫描文件列表
+- `INGEST_MODE = EVENT_NOTIFICATION`：事件通知模式，低延迟（仅阿里云 OSS + AWS S3）
+- `FROM VOLUME <volume_name>`：引用已创建的 External Volume（不是 `FROM '@path/'`）
+- PIPE 中的 COPY 语句不支持 `files`、`regexp`、`subdirectory` 参数
+
+**示例：**
+```sql
+-- 从 OSS Volume 持续导入 Parquet 文件（LIST_PURGE 模式）
+CREATE OR REPLACE PIPE oss_events_pipe
+  VIRTUAL_CLUSTER = default
+  INGEST_MODE = LIST_PURGE
+AS
+COPY INTO ods.events
+FROM VOLUME my_oss_volume
+USING PARQUET;
+
+-- EVENT_NOTIFICATION 模式（仅阿里云 OSS + AWS S3）
+CREATE OR REPLACE PIPE oss_events_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;
+```
+
+## DROP PIPE
+
+```sql
+DROP PIPE [ IF EXISTS ] <pipe_name>;
+```
+
+## SHOW PIPE
+
+```sql
+-- 列出当前 schema 下所有 Pipe
+SHOW PIPES;
+
+-- 按名称过滤
+SHOW PIPES LIKE 'kafka%';
+
+-- 查看 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;
+```
+
+## 注意事项
+
+- Pipe 创建后默认自动启动，无需手动 RESUME
+- Kafka Pipe 使用 consumer group 管理 offset，重建 Pipe 时注意 group_id 和 offset 设置
+- 对象存储 Pipe 通过文件列表或事件通知（EVENT_NOTIFICATION）检测新文件，避免重复导入
+- Pipe 不支持修改 AS 子句，需要 `CREATE OR REPLACE`
+
+## 参考文档
+
+- [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)
+- [最佳实践：使用 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,123 @@
+# 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 是一次性消费的：**每次 SELECT 后，已读取的数据会被标记为已消费**，下次 SELECT 只返回新增变更。
+
+```sql
+-- 查看当前未消费的变更数据
+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 IN ('INSERT', 'UPDATE_AFTER', 'DELETE')
+) 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);
+
+-- 配合 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>;
+```
+
+## 注意事项
+
+- Stream 数据**只能消费一次**，SELECT 后即标记为已读
+- 若长时间不消费，超出源表的 `data_retention_days` 后数据会丢失
+- `STANDARD` 模式下 UPDATE 会产生两条记录：`UPDATE_BEFORE`（更新前）和 `UPDATE_AFTER`（更新后）
+- 消费时通常过滤 `__change_type IN ('INSERT', 'UPDATE_AFTER', 'DELETE')`，忽略 `UPDATE_BEFORE`
+
+## 参考文档
+
+- [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)