@clickzetta/cz-cli-darwin-x64 0.3.1

package/bin/skills/lakehouse-doc/references/create-table-ddl.md

@@ -0,0 +1,405 @@
+# CREATE TABLE
+
+## 功能
+
+本语句用于创建一个新的表。在Lakehouse中，表是存储数据的基本单位。通过创建表，您可以将数据按照指定的结构进行组织和管理。
+
+## 语法
+
+### 基本建表语句
+
+```SQL
+CREATE TABLE [ IF NOT EXISTS ] table_name
+(
+    column_definition  [column_definition ,...]
+    index_definition_list
+)
+[ PARTITIONED BY (column_name column_type | column_name | transform_function) ]
+[ CLUSTERED BY (column_name,...) 
+    [SORTED BY (column_name [ ASC | DESC ])] 
+    [INTO num_buckets BUCKETS] 
+]
+[ COMMENT 'table_comment' ]
+[PROPERTIES('data_lifecycle'='day_num')];
+
+
+```
+
+### column\_definition说明
+
+#### 基本语法
+
+```
+column_name column_type 
+{ NOT NULL |
+  PRIMARY KEY|
+  IDENTITY[(seed)]|
+  GENERATED ALWAYS AS ( expr ) |
+  DEFAULT default_expression |
+  COMMENT column_comment |   
+}
+```
+
+#### 列类型column\_type
+
+* **column\_type**列类型，支持以下类型：
+
+```SQL
+TINYINT：1字节整数，范围 -128 到 127。
+SMALLINT：2字节整数，范围 -32,768 到 32,767。
+INT：4字节整数，范围 -2,147,483,648 到 2,147,483,647。
+BIGINT：8字节整数，范围 -9,223,372,036,854,775,808 到 9,223,372,036,854,775,807。
+FLOAT：4字节浮点数。
+DOUBLE：8字节浮点数。
+DECIMAL：可变长度的精确数值类型，支持指定精度和小数位数。
+VARCHAR：变长字符串，最大长度限制为 65,533 字符。
+CHAR：定长字符串，长度范围从 1 到 255 字符。
+DATE：日期，格式为 YYYY-MM-DD。
+TIMESTAMP：日期时间，时间戳表示为本地时间,格式为 YYYY-MM-DD HH:MM:SS。
+TIMESTAMP_NTZ：不包含时区信息的日期和时间值，格式为 YYYY-MM-DD HH:MM:SS。
+BINARY：固定长度的二进制字符串。
+BOOLEAN：布尔值，真或假。
+ARRAY：元素类型相同的有序集合。如：ARRAY<INT>
+MAP：键值对集合，键的类型必须相同，值的类型可以相同也可以不同。如：MAP<STRING,INT>
+STRUCT：字段类型不同的记录类型。如：struct<company_name:string,employee_count:int>
+JSON：一种轻量级的数据交换格式。
+VECTOR：数值向量类型，用于存储一系列数值。
+```
+
+* **NOT NULL**：表示该列不允许为NULL,只支持建表时指定不支持使用ALTER语法添加,需要取消NOT NULL约束时。请使用修改表类型语法：
+
+```
+ALTER TABLE table_name CHANGE COLUMN colum_name data_type
+```
+
+比如去除int类型not null约束
+
+```
+CREATE TABLE aa_not_null (id int NOT NULL)
+ALTER TABLE aa_not_null CHANGE COLUMN id TYPE int;
+```
+
+#### 主键（PRIMARY KEY）
+
+* **主键（PRIMARY KEY**） 用于确保表中每条记录的唯一性。在大数据场景下，由于数据量通常非常庞大，为了保证数据的唯一性而对所有 key 进行逐一检查是不现实且低效的，因此一般不推荐在大数据环境中使用主键约束。然而，Lakehouse 仍提供了对主键的支持，以便在特定场景下满足数据完整性的需求。在Lakehouse架构中，定义了主键的表在进行实时数据写入时，系统将自动根据主键值进行数据去重，这对于变更数据捕获（CDC）场景尤为重要。例如，您可以实时地将MySQL数据库的binlog日志同步到Lakehouse，确保数据的一致性。设置完主键需要通过[实时数据接口](java_reference/realtime-upload.md)来处理数据。在CDC实时写入过程中，系统将依据主键自动进行数据去重，以维护数据的准确性和完整性。只支持建表时指定。具体参考文档参考[主键介绍](primary-key.md)
+
+```
+CREATE    TABLE pk_table 
+(id int, col string PRIMARY KEY (id));
+
+CREATE    TABLE pk_table 
+(id int PRIMARY KEY, col string);
+--分桶表定义主键
+CREATE    TABLE pk_table (
+          id int,
+          col string,
+          cluster_key string,
+          PRIMARY key (id)
+          ) CLUSTERED BY (id, cluster_key) SORTED BY (id) INTO 16 BUCKETS;
+
+--分区表定义主键
+CREATE    TABLE pk_table (
+          id int,
+          col string,
+          pt string,
+          PRIMARY key (id, pt)
+          ) PARTITIONED BY (pt);
+```
+
+#### 自增列（IDENTITY\[(seed)]）
+
+* **IDENTITY\[(seed**)]:支持指定自增。无法保证序列中的值是连续的（无间隙），也无法保证序列值按特定顺序分配。因为表中可能会发生其他并发插入。这些限制是设计的一部分，目的是提高性能。具体使用参考[IDENTITY Column文档](IDENTITY-Column.md)
+
+```
+CREATE    TABLE identity_test (id bigint IDENTITY(1), col string);
+```
+
+#### 生成列（GENERATED ALWAYS AS）
+
+* **GENERATED ALWAYS AS (expr**)：通过表达式`expr`自动生成列的值。表达式可以包含常量和内置标量确定性SQL函数，不支持非确定性函数如（current\_date\random\current\_timestamp\上下文函数）或运算符，不支持聚合函数、窗口函数或表函数。支持分区列使用生成列
+
+```
+CREATE TABLE t_genet (col1 TIMESTAMP,pt STRING GENERATED ALWAYS AS (date_format(col1, 'yyyy-MM-dd'))) PARTITIONED BY (pt);
+```
+
+#### 默认值（DEFAULT）
+
+* **DEFAULT default\_expression**：为新添加的列定义一个默认值。如果在INSERT、UPDATE或MERGE操作中未指定该列的值，将自动使用此默认值。对于添加列之前已存在的数据行，该列将填充为null。支持非确定性函数如（current\_date\random\current\_timestamp\上下文函数）和常量值
+
+```
+CREATE TABLE t_default(id INT,col1 STRING DEFAULT current_timestamp());
+```
+
+### 索引定义（index\_definition\_list）
+
+#### 基本语法
+
+```
+INDEX index_name (col_name) index_type [COMMENT 'xxxxxx'] [PROPERTIES('key'='value')]
+```
+
+**columns\_difinition**:定义表的字段信息，最后一个字段必须使用逗号隔开
+
+**INDEX**：关键字
+
+**index\_name**：自定义index的名称
+
+**column\_name**：需要添加索引的字段名称
+
+**index\_type**：索引类型，目前支持[bloomfilter](BLOOMFILTER-INDEX.md)、[inverted](inverted-index.md)、[vector](vector-index.md)
+
+**COMMENT**：指定index的说明信息
+
+**PROPERTIES**：指定INDEX的参数,不同的索引支持不同的参数具体参考对应索引文档
+
+### 分区（PARTITIONED BY）
+
+分区是一种通过在写入时将相似的行分组在一起来加快查询速度的方法。使用分区可以达到数据裁剪，优化查询。查询表时通过WHERE子句查询指定所需查询的分区，避免全表扫描，提高处理效率，降低计算资源。具体可以参考[参考分区介绍](partition_table.md)。 注意执行写入分区时单个任务目前限制2048个分区，超出此限制将会报错：`The count of dynamic partitions exceeds the maximum number 2048`。插入之前建议您先统计分区的数量如：`select count(distinct pt) from table`。如果您确实有这么多分区可以分批次导入或者您可以通过添加参数set cz.sql.table.sink.max.partition.per.thread=10000来修改此限制，lakehouse的分区总数没有限制，会在单个任务限制。如果您的数据量较小建议可以不用设置cluster key和partiiton key。建议单分区和cluster key在百MB到GB级别。例如parquet格式文件压缩后128MB
+
+支持两种写法
+第一种分区字段和类型在create table时声明，在PARTITIONED BY字据中声明字段即可
+
+```SQL
+CREATE TABLE prod.db.sample (
+id bigint,
+category string,
+data string
+)
+PARTITIONED BY(category)
+```
+
+第二种分区字段和类型写在PARTITIONED BY语句中。
+
+```SQL
+CREATE TABLE prod.db.sample (
+id bigint,
+data string)
+PARTITIONED BY(category string)
+```
+
+### 分桶表（CLUSTERED BY）
+
+* CLUSTERED BY：指定Hash Key。Lakehouse将对指定列进行Hash运算，将数据根据Hash值分散到各个数据分桶中。为了避免数据倾斜和热点，并提高并行执行效果，建议选择取值范围大、重复键值少的列作为Hash Key。通常在进行join操作时会有明显效果。建议在数据量大的场景下使用CLUSTERED BY，一般按照一个桶的大小在128MB到1GB之间。如果没有指定分桶，默认为256个buckets。建议SORTED BY和CLUSTERED BY保持一致，以获得更好的性能。当指定SORTED BY子句后，行数据将按照指定的列进行排序。  更多信息可以参考[分桶](cluster-table.md)
+
+```
+--指定分桶并指定排序
+CREATE TABLE sales_data (
+    sale_id INT,
+    product_id INT,
+    quantity_sold INT,
+    sale_date DATE
+) CLUSTERED BY (product_id)
+SORTED BY (sale_date DESC)
+INTO 50 BUCKETS;
+--指定分桶并指定桶的个数
+CREATE TABLE sales_data (
+    sale_id INT,
+    product_id INT,
+    quantity_sold INT,
+    sale_date DATE
+) CLUSTERED BY (product_id)
+INTO 50 BUCKETS;
+```
+
+### SORTED BY
+
+SORTED BY：指定文件内字段的排序方式。Lakehouse的SORTED BY可以单独使用，单独使用时表示在文件内排序。指定SORTED BY可以加速数据检索速度，但是写入时由于要排序，写入时可能会增加耗时
+
+```
+CREATE TABLE sales_data (
+    sale_id INT,
+    product_id INT,
+    quantity_sold INT,
+    sale_date DATE
+) 
+SORTED BY (sale_date DESC);
+```
+
+### PROPERTIES
+
+* 支持设置生命周期'data\_lifecycle'='day\_num'[参考生命周期介绍](data-lifecycle.md)
+* 开启[TABLE STREAM](tablestream_summary.md) ，建表时指定'change\_tracking' = 'true'并不会生效，请使用alter开启
+  ALTER table test\_table set PROPERTIES ('change\_tracking' = 'true');
+* 设置表的缓存策略。partiton.cache.policy.latest.count=num设置表的缓存策略。计算集群可以通过配置 `preload_table`，定时或被触发拉取 `preload_table` 中指定的表数据到计算集群本地的 SSD 硬盘上进行缓存。您还可以在表上设置缓存策略。
+  例如，`partition.cache.policy.latest.count=10` 表示缓存最近的 10 个分区，当新分区添加时，旧分区的缓存将失效。也可以通过alter命令添加该参数
+  例如ALTER table test\_table set PROPERTIES ('partition.cache.policy.latest.count' =10);
+* 设置表的保留周期'data\_retention\_days'='num'，配置Time Travel的数据保留周期，以决定数据在时间旅行窗口中保留的时间长度。
+
+```
+--设置数据生命周期和表删除数据的保留周期
+CREATE TABLE historical_prices (
+    ticker_symbol STRING,
+    trading_date DATE,
+    closing_price DECIMAL(10, 2)
+) PROPERTIES (
+    'data_lifecycle' = '365',
+    'data_retention_days' = '7'
+);
+--修改已有表的生命周期
+ALTER TABLE historical_prices SET PROPERTIES(    'data_lifecycle' = '1')
+```
+
+### 使用LIKE语句建表
+
+```SQL
+CREATE TABLE [ IF NOT EXISTS ] table_name
+LIKE source_table
+[ COMMENT 'table_comment' ];
+```
+
+使用LIKE语句创建新表时，目标表将具有与源表相同的表结构，但不会复制数据。
+
+### 使用AS语句建表
+
+CREATE TABLE AS SELECT（简称CTAS）语句可用于同步或异步查询原表，并基于查询结果创建新表，然后将查询结果插入到新表中。需要注意的是，通过这种方式创建的表不会复制分区信息。
+
+```SQL
+CREATE TABLE [ IF NOT EXISTS ] table_name
+[ AS select_statement ];
+```
+
+## 示例
+
+1.创建分区表
+
+语法一：
+
+```SQL
+CREATE TABLE table_part (id INT, name STRING)
+PARTITIONED BY (age INT);
+```
+
+语法二：
+
+```SQL
+CREATE TABLE table_fpart (id INT, name STRING, dt STRING)
+PARTITIONED BY (dt) COMMENT '11';
+```
+
+2.创建一个自增列作为唯一标识符的商品表
+
+```sql
+CREATE TABLE IF NOT EXISTS products (
+    product_id BIGINT IDENTITY(1) COMMENT '商品ID',
+    name VARCHAR(255) NOT NULL COMMENT '商品名称',
+    price DECIMAL(10, 2) NOT NULL COMMENT '价格'
+) COMMENT '商品列表';
+```
+
+3.创建一个带有生成列的时间戳转换表
+
+```sql
+CREATE TABLE IF NOT EXISTS timestamps (
+    event_time TIMESTAMP COMMENT '事件发生时间',
+    formatted_date STRING GENERATED ALWAYS AS (date_format(event_time, 'yyyy-MM-dd')) COMMENT '格式化后的日期'
+) PARTITIONED BY (formatted_date);
+```
+
+4.创建一个默认值为当前时间戳的活动记录表
+
+```sql
+CREATE TABLE IF NOT EXISTS activities (
+    activity_id BIGINT NOT NULL COMMENT '活动ID',
+    description VARCHAR(255) COMMENT '描述',
+    event_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '记录时间'
+) COMMENT '活动记录';
+```
+
+5.创建一个带有Bloom Filter索引的搜索优化表
+
+```sql
+CREATE TABLE IF NOT EXISTS search_optimized (
+    id BIGINT COMMENT 'ID',
+    description VARCHAR(255) COMMENT '关键词',
+    INDEX bloom_index (id) BLOOMFILTER COMMENT '布隆过滤器索引'
+) COMMENT '用于快速查找的表';
+```
+
+6.创建一个带有倒排索引的文本分析表
+
+```sql
+CREATE TABLE IF NOT EXISTS text_analysis (
+    doc_id BIGINT COMMENT '文档ID',
+    content TEXT COMMENT '内容',
+    INDEX inverted_content (content) INVERTED PROPERTIES ('analyzer' = 'chinese') COMMENT '倒排索引'
+) COMMENT '用于文本分析的表';
+```
+
+7.创建一个带有分桶和排序的销售数据表
+
+```sql
+CREATE TABLE IF NOT EXISTS sales_data (
+    sale_id BIGINT COMMENT '销售ID',
+    product_id BIGINT COMMENT '产品ID',
+    quantity_sold INT COMMENT '售出数量',
+    sale_date DATE COMMENT '销售日期'
+) CLUSTERED BY (product_id)
+SORTED BY (sale_date DESC)
+INTO 50 BUCKETS COMMENT '销售数据表';
+```
+
+8.创建一个带有生命周期管理的数据保留表
+
+```sql
+CREATE TABLE IF NOT EXISTS historical_prices (
+    ticker_symbol VARCHAR(10) COMMENT '股票代码',
+    trading_date DATE COMMENT '交易日期',
+    closing_price DECIMAL(10, 2) COMMENT '收盘价'
+) PROPERTIES (
+    'data_lifecycle' = '365',
+    'data_retention_days' = '1'
+) COMMENT '历史股价表';
+```
+
+9.创建一个类似于现有表结构的新表
+
+```sql
+CREATE TABLE IF NOT EXISTS new_users LIKE users COMMENT '新用户表';
+```
+
+10.创建一个通过查询结果初始化的表
+
+```sql
+CREATE TABLE IF NOT EXISTS recent_sales AS
+SELECT * FROM sales WHERE sale_date >= DATE_SUB(CURRENT_DATE, 3);
+```
+
+11.创建一个包含数组类型的订单详情表
+
+```sql
+CREATE TABLE IF NOT EXISTS order_details (
+    order_id BIGINT COMMENT '订单ID',
+    items ARRAY<STRUCT<item_id:BIGINT, quantity:INT, price:DECIMAL(10, 2)>> COMMENT '商品列表'
+) COMMENT '订单详情';
+```
+
+12.创建一个带有JSON类型的客户反馈表
+
+```sql
+CREATE TABLE IF NOT EXISTS customer_feedback (
+    feedback_id BIGINT COMMENT '反馈ID',
+    feedback JSON COMMENT '反馈内容'
+) COMMENT '客户反馈表';
+```
+
+# 使用说明
+
+### 分区和分桶
+
+* **分区策略的选择**：根据查询模式选择合适的分区字段。通常来说，应该选择那些能够有效缩小扫描范围的列作为分区键。比如时间戳列非常适合用作日期范围查询的分区键。
+
+* **分桶数量的设定**：分桶数目应当根据预计的数据量及硬件资源配置来调整。一般来说，每个bucket大小应在 256MB 到 1GB 之间。过多或过少的分桶都会影响到系统的整体性能。为了获得最佳效果，建议测试不同配置下的表现，并据此做出适当调整。
+
+* **排序字段的选择**：当使用 `SORTED BY` 子句时，选择那些频繁出现在过滤条件中的列作为排序依据。良好的排序可以帮助加速点查询和范围查询的速度，但同时也增加了写入成本。因此，在权衡利弊后作出决策非常重要。
+
+### 索引
+
+用户可以在建表的同时创建多个列的索引。索引也可以在建表之后再添加。如果在之后的使用过程中添加索引，如果表中已有数据，则需要重写所有数据，因此索引的创建时间取决于当前数据量。
+
+### 表属性设置的最佳实践
+
+* **启用数据生命周期管理**：通过设置 `data_lifecycle` 属性，可以让系统自动清理不再需要的历史数据。这对于节省存储非常有用，尤其是在处理日志或交易记录等具有明确保留期限的数据集时
+* **配置变更跟踪**：如果你的应用场景涉及需要获取表的数据变化，则需要开启 `change_tracking` 。常见场景如[TABLE STRAM](tablestream_summary.md)
+* **删除数据设置数据保留周期**:此参数定义了在被删除数据被保留的时间长度，对于需要进行历史数据查询的场景非常重要。例如，[table stream](tablestream_summary.md)、[restore](restore.md) 和[dynamic table](dynamic-table-introduce.md) 等功能都会依赖于这个保留周期设置。Lakehouse默认保留数据一天。根据您的业务需求，您可以通过调整 `data_retention_days` 参数来延长或缩短数据的保留周期。请注意，调整数据保留周期可能会影响存储成本。延长保留周期会增加存储需求，从而可能增加相关的费用。
+
+

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

@@ -0,0 +1,226 @@
+# Table Stream 功能
+
+Table Stream是一种实时数据流，用于记录对表所做的数据操作语言（DML）更改，包括插入、更新和删除操作。同时，Table Stream还提供有关每次更改的元数据，以便您可以根据更改的数据采取相应操作。支持在Table、Dynamic Table、Materialized View、External Table(Kafka)创建Table Stream，同时也支持在 External Volume 上创建 Volume Stream，用于监听外部对象存储（如 OSS）中的文件变更事件。
+
+## Table Stream 语法
+
+**Table、Dynamic Table、Materialized View 创建 Table Stream 语法**
+
+```SQL
+CREATE [OR REPLACE] TABLE STREAM [IF NOT EXISTS]
+  <name>
+  ON TABLE <table_name>
+  [TIMESTAMP AS OF timestamp_expression]
+  [COMMENT = '<string_literal>']
+  WITH PROPERTIES ('TABLE_STREAM_MODE' = 'APPEND_ONLY|STANDARD','SHOW_INITIAL_ROWS'='TRUE|FALSE');
+```
+
+* `<name>`：Table Stream的名称。
+
+* `<table_name>`：要获取增量的基表。不支持view。
+
+* `TIMESTAMP AS OF timestamp_expression`：（可选）指定Table Stream应从底层表开始接收更新的时间戳表达式。如果省略此参数，Table Stream将从当前时间开始接收更新。
+
+  * `timestamp_expression`返回结果是一个标准的时间戳类型的表达式，TIMESTAMP AS OF指定的最早时间戳取决[TIME TRAVEL](TIMETRAVEL.md)(data\_retention\_days)参数，如果指定的版本不存在则会报错。如果未指定则使用当前时间戳的版本数据，例如：
+    * `'2023-11-07 14:49:18'`，即可以强制转换为时间戳的字符串。
+    * `cast('2023-11-07 14:49:18 Asia/Shanghai' as timestamp)`。
+    * `current_timestamp() - interval '12' hours`。
+    * 本身就是时间戳或可强制转换为时间戳的任何其他表达式。
+
+* `COMMENT`：（可选）Table Stream的注释。
+
+* `'TABLE_STREAM_MODE' = 'APPEND_ONLY|STANDARD'`：（必选）值二选一，APPEND\_ONLY和STANDARD。
+
+  * APPEND\_ONLY只记录对象的INSERT操作的数据。Update和delete操作不会记录。例如，最初在表中插入了10行，然后在点位没有移动的时候执行delete操作删除5行，Table Stream仍然记录10行操作。
+  * STANDARD模式：STANDARD模式下可以跟踪源对象的所有DML变化，包括插入、更新和删除（包括表截断）。这种提供行级别的变化是通过将所有变化的delta数据进行连接加工来提供行级别增量。Table Stream中的delta变化指的是在两个事务时间点之间发生的数据变化。例如，如果在Table Stream的offset之后，有一个行被插入，然后被更新，那么delta变化就是一个新的行。如果在stream的offset之后，有一个行被插入，然后被删除，那么delta变化就是没有这个行。换句话说，delta变化会反映源对象的最新状态，而不是历史变化。
+
+* SHOW\_INITIAL\_ROWS:可选参数，指定为TRUE时，创建stream时候记录下table当时的版本，第一次消费该stream，永远拿的是创建时的那个版本，同时第一次消费时，所有数据都是insert模式，第一次消费结束后，后续的行为就和之前行为一样，从某个版本到下次版本之间的Delta数据。
+
+### 注意事项
+
+* 在创建Table Stream之前，必须在基表上执行以下操作：
+
+```SQL
+ALTER TABLE table_name set PROPERTIES ('change_tracking' = 'true');
+```
+
+* TIMESTAMP AS OF指定的最早时间戳取决[TIME TRAVEL](TIMETRAVEL.md)(data\_retention\_days)参数，如果指定的版本不存在则会报错。此参数定义了在被删除数据被保留的时间长度，Lakehouse默认保留数据一天。根据您的业务需求，您可以通过调整 `data_retention_days` 参数来延长或缩短数据的保留周期。请注意，调整数据保留周期可能会影响存储成本。延长保留周期会增加存储需求，从而可能增加相关的费用。
+* 通过实时上传数据写入的数据一分钟之后才可以读取，Table Stream 只能读取已经提交的数据。实时任务写入的数据需要等待 1 分钟才能确认，所以 Table Stream 也要等 1 分钟才能看到。
+
+### 使用案例
+
+案例1：创建APPEND\_ONLY模式的Table Stream
+
+```SQL
+-- 清理环境
+DROP      TABLE IF EXISTS data_change_test;
+
+DROP      TABLE STREAM IF EXISTS data_change_test_stream;
+
+-- 创建测试表
+CREATE    TABLE data_change_test (id int, name string);
+
+INSERT    INTO data_change_test
+VALUES    (1, 'apple');
+
+-- 在data_change_test上创建TABLE stream，获取从当前时间开始插入的增量记录
+ALTER     TABLE data_change_test set PROPERTIES ('change_tracking' = 'true');
+
+CREATE    TABLE STREAM data_change_test_stream ON TABLE data_change_test
+WITH      PROPERTIES ('TABLE_STREAM_MODE' = 'APPEND_ONLY');
+
+-- 插入测试数据
+INSERT    INTO data_change_test
+VALUES    (2, 'banana');
+
+-- 查看STREAM数据
+SELECT    *
+FROM      data_change_test_stream;
+```
+
+案例2：创建STANDARD模式的Table Stream
+
+```SQL
+-- 清理环境
+DROP      TABLE IF EXISTS data_change_test;
+
+DROP      TABLE STREAM IF EXISTS data_change_test_stream;
+
+-- 创建测试表
+CREATE    TABLE data_change_test (id int, name string);
+
+INSERT    INTO data_change_test
+VALUES    (1, 'apple');
+
+-- 在data_change_test上启用change_tracking
+ALTER     TABLE data_change_test set PROPERTIES ('change_tracking' = 'true');
+
+-- 创建STANDARD模式的Table Stream
+CREATE    TABLE STREAM data_change_test_stream ON TABLE data_change_test
+WITH      PROPERTIES ('TABLE_STREAM_MODE' = 'STANDARD');
+
+-- 插入测试数据
+INSERT    INTO data_change_test
+VALUES    (2, 'banana');
+
+-- 更新测试数据
+update data_change_test set name = 'orange'
+WHERE     id = 2;
+
+-- 删除测试数据
+DELETE
+FROM      data_change_test
+WHERE     id = 1;
+
+-- 查看stream数据
+SELECT    *
+FROM      data_change_test_stream;
+```
+
+## Kafka Table Stream
+
+支持在Kafka外部表上创建表流（Table Stream），实现实时消费Topic数据.
+
+#### 语法
+
+```sql
+CREATE TABLE STREAM [IF NOT EXISTS] stream_name 
+ON TABLE external_kafka_table 
+[TIMESTAMP AS OF timestamp_expression]  -- 可选，指定消费起始时间点位
+WITH PROPERTIES (
+  'table_stream_mode' = 'append_only',  -- 仅支持追加模式
+  'show_initial_rows' = 'true'|'false'
+);
+```
+
+### 参数说明
+
+* `TIMESTAMP AS OF`   :指定消费起始时间点（可选），支持格式：
+  * **明确时间戳**：`'2023-01-01 12:00:00'`
+  * **时间函数**：`CURRENT_TIMESTAMP() - INTERVAL '1' HOUR`
+* `show_initial_rows`  :控制初始数据加载行为：
+  * `true`：加载从外部表创建时指定的点位到Table Stream指定的点位之间的历史数据
+  * `false`：从最新点位（`latest`）开始消费，不加载历史数据（默认值）
+* `table_stream_mode`  : 固定为`append_only`，仅处理Kafka新增数据（不支持更新/删除操作）
+
+#### 示例
+
+1. Kafka 外部表创建
+   首先，您需要创建一个 [Kafka 外部表](kafka-external-table.md)。这是创建 Table Stream 的基础。以下是创建 Kafka 外部表的语法：
+
+创建Kafka Connection
+
+```SQL
+CREATE STORAGE CONNECTION pipe_kafka
+    TYPE kafka
+    BOOTSTRAP_SERVERS = ['47.99.48.62:9092']
+    SECURITY_PROTOCOL = 'PLAINTEXT';
+```
+
+创建Kafka外部表
+
+```SQL
+CREATE EXTERNAL TABLE external_table_kafka (   
+ key_column binary,   
+ value_column binary NOT NULL)
+USING kafka
+OPTIONS (    'group_id' = 'external_table_lh',    'topics' = 'test_long')
+CONNECTION pipe_kafka;
+```
+
+* `external_table_kafka` 是外部表的名称。
+* `key_column` 和 `value_column` 分别代表 Kafka 消息的键和值，其中 `value_column` 是必需的。
+* `USING kafka` 指定了使用 Kafka 作为数据源。
+* `OPTIONS` 部分包含了 Kafka 消费者配置，如消费者组 ID (`group_id`) 和要订阅的主题 (`topics`)。
+* `CONNECTION pipe_kafka` 指定了与 Kafka 的连接配置，这通常包括 Kafka 集群的地址和其他连接参数。
+
+2. 创建 Table Stream
+
+在 Kafka 外部表的基础上，您可以创建一个 Table Stream，用于实时处理 Kafka 数据流。以下是创建 Table Stream 的语法：
+
+```
+CREATE TABLE STREAM kafka_table_stream_pipe1
+ ON TABLE external_table_kafka
+WITH PROPERTIES (
+    'table_stream_mode' = 'append_only',
+    'show_initial_rows' = 'true');
+```
+
+^
+
+## Volume Stream
+
+**CREATE VOLUME STREAM 语法**
+
+用于在 External Volume 的 Directory Table 上创建 Volume Stream，以监听外部对象存储中文件的新增与删除事件。
+
+```
+CREATE [OR REPLACE] STREAM [IF NOT EXISTS] <name>
+  ON VOLUME <volume_name>;
+```
+
+**参数说明**
+
+`<name>`：Volume Stream 的名称。
+
+`<volume_name>`：要监听的 External Volume 名称。该 Volume 必须满足以下条件：
+
+* 已开启目录功能，即建表时指定 DIRECTORY = (ENABLE = TRUE)；
+* 已开启递归监听，即建表时指定 RECURSIVE = TRUE。
+
+**示例**
+
+```
+-- 创建Volume Stream，追踪文件新增和删除
+CREATE OR REPLACE STREAM str_app_log
+  ON VOLUME vol_app_log;
+
+```
+
+**注意事项**
+
+* 创建 Volume Stream 之前，须开启 DIRECTORY = (ENABLE = TRUE) 和 RECURSIVE = TRUE 。
+* Volume Stream 本质上是构建在 Directory Table 之上的 Table Stream，消费机制与 Table Stream 完全一致：仅 DML 语句（如 INSERT INTO ... SELECT FROM stream）会推进消费点位，纯 SELECT 查询不会推进。
+* 由于对象存储事件通过消息队列传递存在约 1 分钟的延迟，文件上传后需等待约 1 分钟才能在 Volume Stream 中查询到对应的变更记录。
+
+^