@clickzetta/cz-cli-darwin-x64 0.3.1

package/bin/skills/lakehouse-doc/references/sql_functions/table_functions/read_kafka.md

@@ -0,0 +1,85 @@
+## READ\_KAFKA
+
+## 功能描述
+
+`READ_KAFKA` 函数用于从 Apache Kafka 集群**一次性读取**数据并以表格形式返回。该函数主要用于**数据探查、测试和临时查询**场景，直接SELECT查询不会在 Kafka 中创建持久的消费者组。
+
+**语法**
+
+```SQL
+SELECT ... FROM READ_KAFKA(
+ 'bootstrap',
+ 'topic',
+'topic_pattern',
+ 'group_id', 
+'STARTING_OFFSETS', 'ENDING_OFFSETS', 'STARTING_OFFSETS_TIMESTAMP', 'ENDING_OFFSETS_TIMESTAMP', 
+'KEY_FORMAT', 
+'VALUE_FORMAT', 
+   0,
+MAP()      
+)
+```
+
+`read_kafka` 函数用于从Kafka读取数据。它支持以下参数：
+
+* **bootstrap**: Kafka服务器地址，如 `1.2.3.1:9092,1.2.3.2:9092`。
+* **topic**: Kafka主题名称，多个主题用逗号分隔，如 `topicA,topicB`。
+* **topic\_patternt**\*：topic正则，暂不支持，默认留空。如：''。\*
+* **group\_id**: Kafka消费者组ID。临时消费者组 ID，仅用于函数执行期间**不会在 Kafka 中创建持久消费者组**
+* **STARTING\_OFFSETS**: 指定读取的起始点位，默认为 `earliest`，在读取时推荐填写。
+* **ENDING\_OFFSETS**: 指定结束点位，默认为 `latest`，在读取时推荐填写。
+* **STARTING\_OFFSETS\_TIMESTAMP**: 指定起始点位的时间戳。
+* **ENDING\_OFFSETS\_TIMESTAMP**: 指定结束点位的时间戳。
+* **KEY\_FORMAT**:指定读取key的格式,类型是STRING类型忽略大小写。目前只支持raw格式
+* **VALUE\_FORMAT**：指定读取value的格式，类型是STRING类型忽略大小写。目前只支持raw格式
+* **MAX\_ERROR\_NUMBER**：读取窗口内，允许的最大错误行数。必须大于等于0。默认是 0，即不允许有错误行，取值范围0-100000
+* **MAP**()：需要传入到Kafka的参数，以kafka.开头，直接使用kafka的参数即可,可以在Kafka中找到这种选项。,格式如MAP('kafka.security.protocol', 'PLAINTEXT')，取值参考，[kafka文档](https://kafka.apache.org/documentation/#consumerconfigs)
+
+`read_kafka` 结果返回值：
+
+|                 |                     |                      |
+| --------------- | ------------------- | -------------------- |
+| 字段            | 含义                | 类型                 |
+| topic           | Kafka主题名称       | STRING               |
+| partition       | 数据分区ID          | INT                  |
+| offset          | Kafka分区中的偏移量 | BIGINT               |
+| timestamp       | Kafka消息时间戳     | TIMESTAMP\_LTZ       |
+| timestamp\_type | Kafka消息时间戳类型 | STRING               |
+| headers         | Kafka消息头         | MAP\<STRING, BINARY> |
+| key             | Kafka的key值        | BINARY               |
+| value           | Kafka的value值      | BINARY               |
+
+**注意事项**
+
+* 使用read\_kafka时请确保和Lakehouse网络打通
+
+**具体案例**
+
+```SQL
+-- 读取指定时间范围内的数据
+SELECT 
+    topic, 
+    partition, 
+    offset, 
+    timestamp,
+    CAST(key AS STRING) AS key_str,
+    CAST(value AS STRING) AS value_str
+FROM READ_KAFKA(
+    'kafka-broker:9092',
+    'order_events',
+    '',
+    'temp_analysis_group',
+    'earliest',                               -- 从最早开始
+    'latest',                                 -- 读取到最新
+    '1640995200000',                          -- 2022-01-01 00:00:00
+    '1641081600000',                          -- 2022-01-02 00:00:00
+    'raw',
+    'raw',
+     0,
+MAP() 
+
+)
+LIMIT 10；
+```
+
+^

package/bin/skills/lakehouse-doc/references/sql_functions/table_functions/stack.md

@@ -0,0 +1,69 @@
+### 函数栈（STACK）
+
+#### 概述
+
+`STACK` 函数是一个强大的数据转换工具,它可以将多列表达式按照指定的行数进行堆叠,生成新的行和列。该函数在处理数据时,能够灵活地将不同类型的数据进行整合,并且可以通过 `LATERAL VIEW` 配合使用,实现更复杂的数据操作。
+
+#### 语法
+
+```sql
+STACK(n, expr1, expr2, ..., exprK)
+```
+
+#### 参数说明
+
+* `n`：整数,表示要生成的行数。
+* `expr1 ~ exprK`：要求类型相同或者可以进行隐式类型转换的表达式列表。
+
+#### 返回结果
+
+返回一个与 `expr1 ~ exprK` 相同类型的值。
+
+#### 使用示例
+
+**例子 1：基本使用**
+
+```sql
+SELECT 'hello', STACK(2, 1, 2, 3) AS (first, second), 'world';
++---------+-------+--------+---------+
+| 'hello' | first | second | 'world' |
++---------+-------+--------+---------+
+| hello   | 1     | 2      | world   |
+| hello   | 3     | NULL   | world   |
++---------+-------+--------+---------+
+```
+
+**例子 2：与 LATERAL VIEW 搭配使用**
+
+```sql
+SELECT w, x, y FROM VALUES
+('apple', 1, 2, 3, 4),
+('banana', 11, 22, 33, 44),
+('orange', 111, 222, 333, 444),
+('dog', 1111, 2222, 3333, 4444) AS t(w, a, b, c, d)
+LATERAL VIEW STACK(2, a, b, c) lv AS x, y;
++--------+------+------+
+|   w    |  x   |  y   |
++--------+------+------+
+| apple  | 1    | 2    |
+| apple  | 3    | NULL |
+| banana | 11   | 22   |
+| banana | 33   | NULL |
+| orange | 111  | 222  |
+| orange | 333  | NULL |
+| dog    | 1111 | 2222 |
+| dog    | 3333 | NULL |
++--------+------+------+
+```
+
+**例子 3：隐式类型转换**
+
+```sql
+SELECT STACK(2, 1, '2', 3) AS (col1, col2);
++------+------+
+| col1 | col2 |
++------+------+
+| 1    | 2    |
+| 3    |      |
++------+------+
+```

package/bin/skills/lakehouse-doc/references/sql_functions/table_functions/table_changes.md

@@ -0,0 +1,136 @@
+# 功能
+
+`table_changes` 是一个用于查询 Lakehouse 表、动态表和物化视图的数据变化的表函数。通过指定一个时间区间，该函数可以返回该区间内的数据变化，无需创建表流。使用 `table_changes` 时需要确保已开启 `change_tracking` 功能。请在表上执行 `ALTER TABLE tbname SET PROPERTIES ('change_tracking'='true');` 来开启。是否可以查看的对象操作历史依赖于数据的保留周期。数据保留周期默认为七天。
+
+# 语法
+
+```SQL
+TABLE_CHANGES(table_str, start_timestamp, end_timestamp)
+```
+
+**参数要求**：
+
+* `table_str`：已存在的表、动态表或物化视图名称，需提供字符串格式。支持 'schema.tbname'、'tbname' 格式字符串。若未指定 schema，则默认使用当前 schema，即 `current_schema`。
+* `start_timestamp`：查询的时间版本起始时间，需提供标准时间戳类型表达式。
+* `end_timestamp`：查询的时间版本结束时间，需提供标准时间戳类型表达式。
+* opitons:可选参数，目前支持map('TABLE\_STREAM\_MODE', 'ORIGINAL')。当添加此参数时表示获取表变化的原始记录，未添加此参数时比如在start\_timestamp、end\_timestamp之间先insert一条记录再delete这条记录，不添加此参数将会查询不到，如果添加ORIGINAL参数则会显示insert记录和delete记录
+
+**说明**：
+
+* 指定的 `start_timestamp` 不能早于表创建时间，也不能超出数据保留周期。
+* `start_timestamp` 和 `end_timestamp` 分别表示查询的起始和结束时间。查询结果不包括 `start_timestamp` 那一刻的数据，但包括 `end_timestamp` 那一刻的数据。查询时间区间为 (start\_timestamp, end\_timestamp]，左边为开区间，右边为闭区间。
+
+# 示例
+
+示例一：查看表变化
+
+```SQL
+-- 创建表
+CREATE TABLE students_change(name STRING, class STRING) PARTITIONED BY (class);
+-- 开启 change_tracking
+ALTER TABLE students_change SET PROPERTIES ('change_tracking'='true');
+-- 插入数据
+INSERT INTO students_change (name, class) VALUES
+('Alice', 'A'),
+('Bob', 'B'),
+('Carol', 'A'),
+('David', 'C');
+-- 插入数据
+INSERT INTO students_change (name, class) VALUES ('person', 'c');
+-- 查看历史版本
+DESC HISTORY students_change;
++---------+-------------------------+------------+-------------+----------+-------------+-------------------------------+
+| version |          time           | total_rows | total_bytes |   user   |  operation  |            job_id             |
++---------+-------------------------+------------+-------------+----------+-------------+-------------------------------+
+| 7       | 2024-02-01 17:53:42.945 | 4          | 7640        | UAT_TEST | INSERT_INTO | 202402010953426415k3g3xp367p7 |
+| 6       | 2024-01-29 11:15:41.396 | 3          | 5087        | N/A      |             |                               |
++---------+-------------------------+------------+-------------+----------+-------------+-------------------------------+
+-- 查看两个版本的数据变化
+SELECT * FROM TABLE_CHANGES('students_change', TIMESTAMP '2024-01-29 11:15:41.396', TIMESTAMP '2024-02-01 17:53:42.945');
++---------------+------------------+-------------------------+------+--------+-------+
+| __change_type | __commit_version |   __commit_timestamp    | col1 |  name  | class |
++---------------+------------------+-------------------------+------+--------+-------+
+| INSERT        | 7                | 2024-02-01 17:53:42.945 | null | person | c     |
++---------------+------------------+-------------------------+------+--------+-------+
+```
+
+示例二：查看动态表变化
+
+```SQL
+-- 创建测试表，存储员工信息
+CREATE TABLE customer(id INT, name STRING, phone BIGINT, email STRING);
+-- 插入数据
+INSERT INTO customer VALUES
+(1, 'Alice', 1234567890, 'alice@example.com'),
+(2, 'Bob', 2345678901, 'bob@example.com'),
+(3, 'Carol', 3456789012, 'carol@example.com'),
+(4, 'Dave', 4567890123, 'dave@example.com'),
+(5, 'Eve', 5678901234, 'eve@example.com');
+-- 创建动态表处理数据
+CREATE DYNAMIC TABLE customer_masked AS
+SELECT id, name, MASK_OUTER(phone, 3, 4) AS phone, MASK_INNER(email, 0, 12) AS email
+FROM customer;
+-- 开启 change_tracking
+ALTER TABLE customer_masked SET PROPERTIES ('change_tracking'='true');
+-- 刷新动态表
+REFRESH DYNAMIC TABLE customer_masked;
+-- 向基表插入数据
+INSERT INTO customer VALUES
+(6, 'Alaac', 1234567890, 'alabcce@example.com');
+-- 刷新动态表
+REFRESH DYNAMIC TABLE customer_masked;
+-- 查看历史版本
+DESC HISTORY customer_masked;
+-- 查看动态表的数据变化，可以看到新增了一条记录
+SELECT * FROM TABLE_CHANGES('customer_masked', TIMESTAMP '2024-01-24 20:14:19.726', TIMESTAMP '2024-01-24 20:55:43.049');
++---------------+------------------+-------------------------+----+-------+------------+---------------------+
+| __change_type | __commit_version |   __commit_timestamp    | id | name  |   phone    |        email        |
++---------------+------------------+-------------------------+----+-------+------------+---------------------+
+| INSERT        | 4                | 2024-01-24 20:55:43.049 | 6  | Alaac | XXX456XXXX | XXXXXXX@example.com |
++---------------+------------------+-------------------------+----+-------+------------+---------------------+
+```
+
+示例三：显示原始记录
+
+```SQL
+-- 创建表
+CREATE TABLE students_change(name STRING, class STRING) PARTITIONED BY (class);
+-- 开启 change_tracking
+ALTER TABLE students_change SET PROPERTIES ('change_tracking'='true');
+-- 插入数据
+INSERT INTO students_change (name, class) VALUES
+('Alice', 'A'),
+('Bob', 'B'),
+('Carol', 'A'),
+('David', 'C');
+-- 更新数据
+UPDATE students_change SET class = lower(class) WHERE name='Alice'; 
+UPDATE students_change SET class = lower(class) WHERE name='Alice'; 
+DELETE FROM students_change WHERE name = 'Alice';
+--显示原始记录
+select * from table_changes('students_change',timestamp '2024-09-29 20:03:50.58',current_timestamp(),map('TABLE_STREAM_MODE', 'ORIGINAL'));
++---------------+------------------+-------------------------+-------+-------+
+| __change_type | __commit_version |   __commit_timestamp    | name  | class |
++---------------+------------------+-------------------------+-------+-------+
+| UPDATE_BEFORE | 3                | 2024-09-29 20:03:50.399 | Alice | A     |
+| UPDATE_AFTER  | 5                | 2024-09-29 20:05:16.443 | Alice | a     |
+| UPDATE_BEFORE | 5                | 2024-09-29 20:05:16.443 | Alice | a     |
+| UPDATE_AFTER  | 6                | 2024-09-29 20:05:46.118 | Alice | a     |
+| DELETE        | 6                | 2024-09-29 20:05:46.118 | Alice | a     |
++---------------+------------------+-------------------------+-------+-------+
+--显示压缩后的记录
+select * from table_changes('students_change',timestamp '2024-09-29 20:03:50.58',current_timestamp());
++---------------+------------------+-------------------------+-------+-------+
+| __change_type | __commit_version |   __commit_timestamp    | name  | class |
++---------------+------------------+-------------------------+-------+-------+
+| DELETE        | 3                | 2024-09-29 20:03:50.399 | Alice | A     |
++---------------+------------------+-------------------------+-------+-------+
+```
+
+# 注意事项
+
+1. 使用 `table_changes` 函数时，请确保已开启 `change_tracking` 功能。
+2. 指定的 `start_timestamp` 不能早于表创建时间，也不能超出数据保留周期。
+3. 查询结果不包括 `start_timestamp` 那一刻的数据，但包括 `end_timestamp` 那一刻的数据。
+
+^

package/bin/skills/lakehouse-doc/references/sql_functions/table_functions/unnset.md

@@ -0,0 +1,106 @@
+
+## 功能
+`UNNEST` 是一种用于展开数组或嵌套数据结构的函数,常用于将数组类型的列转换为多行数据,以便进行行级分析。
+
+## **语法**
+```sql
+SELECT [列名] FROM UNNEST(数组表达式) [AS 别名(列名)];
+SELECT [列名] FROM 表名, UNNEST(数组列) [AS 别名(列名)]; -- 隐式 JOIN
+```
+## **参数说明**
+`数组表达式`  ：需要展开的数组或嵌套数据结构（如多维数组、结构体）。
+ `别名(列名)`：可选,为展开后的列指定别名和列名。
+`LEFT JOIN` ：可选,保留左表的所有行,即使右表（`UNNEST` 结果）无匹配数据。
+## **使用示例**
+1. **基本数组展开**
+将一维数组展开为多行,每行对应数组中的一个元素。
+**示例：**
+```sql
+-- 输入：array(1,2,3)
+SELECT * FROM UNNEST(array(1,2,3));
+-- 输出：
+-- 1
+-- 2
+-- 3
+```
+ 2. **多数组列展开**
+支持同时展开多个数组,按行对齐。若数组长度不一致,缺失值以 `NULL` 填充。
+**示例：**
+```sql
+-- 输入：array(1,2,3), array('ab','cd')
+SELECT * FROM UNNEST(array(1,2,3), array('ab','cd'));
+-- 输出：
+-- 1    ab
+-- 2    cd
+-- 3    NULL
+```
+3. **嵌套数组展开**
+支持展开多维数组（递归展开）,生成扁平化结果。
+**示例：**
+```sql
+-- 输入：array(array(1,2,3), array(4,5,6))
+SELECT * FROM UNNEST(array(array(1,2,3), array(4,5,6)));
+-- 输出：
+-- 1
+-- 2
+-- 3
+-- 4
+-- 5
+-- 6
+```
+
+4. **与 JOIN 结合使用**
+可与其他表通过 `JOIN` 或 `CROSS JOIN` 进行关联,展开数组列。
+**示例：**
+```sql
+-- 输入：表 t 包含列 k 和数组列 a
+WITH t AS (SELECT * FROM VALUES (1, array(1,2,3)), (2, array(4,5)) AS t(k, a))
+SELECT * FROM t, UNNEST(a);
+-- 输出：
+-- 1    [1,2,3]    1
+-- 1    [1,2,3]    2
+-- 1    [1,2,3]    3
+-- 2    [4,5]      4
+-- 2    [4,5]      5
+```
+
+ 5. **处理 NULL 和空数组**
+- 若数组为 `NULL`,展开后无结果。
+- 若数组为空（`[]`）,展开后同样无结果。
+**示例：**
+```sql
+-- 输入：数组列包含 NULL 或空值
+CREATE VIEW student_score AS
+SELECT id, scores FROM VALUES
+(1, [80,85,87]),
+(2, [77, NULL, 89]),
+(3, NULL),
+(4, []) AS students(id, scores);
+
+SELECT id, scores, score FROM student_score, UNNEST(scores) AS t(score);
+-- 输出：
+-- 1    [80,85,87]    80
+-- 1    [80,85,87]    85
+-- 1    [80,85,87]    87
+-- 2    [77,null,89]  77
+-- 2    [77,null,89]  NULL
+-- 2    [77,null,89]  89
+```
+6. **过滤展开结果**
+```sql
+-- 仅保留偶数元素
+WITH t AS (SELECT * FROM VALUES (1, array(1,2,3)), (2, array(4,5)) AS t(k, a))
+SELECT * FROM t LEFT JOIN UNNEST(a) u(e) WHERE u.e % 2 = 0;
+-- 输出：
+-- 1    [1,2,3]    2
+-- 2    [4,5]      4
+```
+
+
+## **注意事项**
+1. **参数类型限制**
+   `UNNEST` 仅接受数组或嵌套结构作为输入,传递非数组类型会报错。
+   ```sql
+   -- 错误示例：输入为整数
+   SELECT * FROM UNNEST(1); -- 报错：expect array type
+   ```

package/bin/skills/lakehouse-doc/references/sql_functions/window_functions/avg.md

@@ -0,0 +1,91 @@
+### AVG 函数
+
+#### 概述
+
+`AVG` 函数用于计算窗口内表达式的平均值。该函数可以应用于各种数值类型的数据，包括 `TINYINT`、`SMALLINT`、`INT`、`BIGINT`、`FLOAT`、`DOUBLE` 和 `DECIMAL`。返回结果的类型会根据输入类型进行相应的转换，`DECIMAL` 类型的结果会保留原有的精度和标度，其他类型则返回为 `DOUBLE` 类型。需要注意的是，`NULL` 值不会参与平均值的计算。
+
+#### 语法
+
+```sql
+AVG(expr) OVER ([PARTITION_clause] [ORDER_BY_clause] [FRAME_clause])
+```
+
+#### 参数说明
+
+* `expr`: 需要计算平均值的数值类型表达式。
+* `PARTITION_clause`: 可选参数，用于将数据分区，以便在每个分区内分别计算平均值。
+* `ORDER_BY_clause`: 可选参数，用于指定窗口内记录的排序方式。
+* `FRAME_clause`: 可选参数，用于定义窗口的具体范围。
+
+#### 返回结果
+
+`AVG` 函数返回一个数值，表示窗口内数据的平均值。对于 `DECIMAL` 类型，返回结果也是 `DECIMAL` 类型，其精度和标度可能会增加。其他类型的返回结果为 `DOUBLE` 类型。
+
+#### 示例
+
+1. 查询同一个部门（`dep_no`）的工资（`salary`）的平均值，按照部门开窗，不排序：
+
+```sql
+SELECT dep_no, salary, AVG(salary) OVER (PARTITION BY dep_no)
+FROM VALUES
+  ('Eric', 1, 28000),
+  ('Alex', 1, 32000),
+  ('Felix', 2, 21000),
+  ('Frank', 1, 30000),
+  ('Tom', 2, 23000),
+  ('Jane', 3, 29000),
+  ('Jeff', 3, 35000),
+  ('Paul', 2, 29000),
+  ('Charles', 2, 23000)
+AS tab(name, dep_no, salary);
++--------+--------+------------------------------------------+
+| dep_no | salary | `AVG`(salary) OVER (PARTITION BY dep_no) |
++--------+--------+------------------------------------------+
+| 3      | 29000  | 32000.0                                  |
+| 3      | 35000  | 32000.0                                  |
+| 1      | 28000  | 30000.0                                  |
+| 1      | 32000  | 30000.0                                  |
+| 1      | 30000  | 30000.0                                  |
+| 2      | 21000  | 24000.0                                  |
+| 2      | 23000  | 24000.0                                  |
+| 2      | 29000  | 24000.0                                  |
+| 2      | 23000  | 24000.0                                  |
++--------+--------+------------------------------------------+
+```
+
+2. 查询同一个部门（`dep_no`）的工资（`salary`）的累计平均值，按照部门开窗，按照工资排序。返回当前窗口中从开始行到与当前行工资相同所有行的平均值：
+
+```sql
+SELECT dep_no, salary, AVG(salary) OVER (PARTITION BY dep_no ORDER BY salary)
+FROM VALUES
+  ('Eric', 1, 28000),
+  ('Alex', 1, 32000),
+  ('Felix', 2, 21000),
+  ('Frank', 1, 30000),
+  ('Tom', 2, 23000),
+  ('Jane', 3, 29000),
+  ('Jeff', 3, 35000),
+  ('Paul', 2, 29000),
+  ('Charles', 2, 23000)
+AS tab(name, dep_no, salary);
++--------+--------+--------------------------------------------------------------+
+| dep_no | salary | `AVG`(salary) OVER (PARTITION BY dep_no ORDER BY salary ASC) |
++--------+--------+--------------------------------------------------------------+
+| 3      | 29000  | 29000.0                                                      |
+| 3      | 35000  | 32000.0                                                      |
+| 1      | 28000  | 28000.0                                                      |
+| 1      | 30000  | 29000.0                                                      |
+| 1      | 32000  | 30000.0                                                      |
+| 2      | 21000  | 21000.0                                                      |
+| 2      | 23000  | 22333.333333333332                                           |
+| 2      | 23000  | 22333.333333333332                                           |
+| 2      | 29000  | 24000.0                                                      |
++--------+--------+--------------------------------------------------------------+
+```
+
+#### 注意事项
+
+* 当窗口内没有非 `NULL` 值时，`AVG` 函数返回 `NULL`。
+* 使用 `AVG` 函数时，应确保分区、排序和窗口范围的定义符合预期
+
+

package/bin/skills/lakehouse-doc/references/sql_functions/window_functions/count.md

@@ -0,0 +1,88 @@
+### COUNT 函数
+
+#### 概述
+
+COUNT 函数用于计算窗口内的数据行数。该函数有两种形式：`count(*)` 和 `count(expr1[,expr2...])`。`count(*)` 计算窗口内所有行的数量，包括包含 NULL 值的行；`count(expr1[,expr2...])` 计算窗口内非 NULL 表达式的数量。
+
+#### 语法
+
+```sql
+count(*) over ([partition_clause] [orderby_clause] [frame_clause])
+count(expr1[,expr2...]) over ([partition_clause] [orderby_clause] [frame_clause])
+```
+
+#### 参数
+
+* `exprN`: 任意类型，用于计算非 NULL 值的数量。
+
+#### 返回结果
+
+* 返回值类型为 bigint 类型。
+* 使用 `count(*)` 时，NULL 值也被计算为一行。
+* 使用 `count(expr1[,expr2...])` 时，任意一列出现 NULL 值，该行将被忽略。
+
+#### 示例 1：计算每个部门的人数
+
+```sql
+SELECT dep_no,name, count(*) OVER (PARTITION BY dep_no)
+FROM VALUES
+  ('Eric', 1, 28000),
+  ('Alex', 1, 32000),
+  ('Felix', 2, 21000),
+  ('Frank', 1, 30000),
+  ('Tom', 2, 23000),
+  ('Jane', 3, 29000),
+  ('Jeff', 3, 35000),
+  ('Paul', 2, 29000),
+  ('Charles', 2, 23000)
+AS tab(name, dep_no, salary);
++--------+---------+---------------------------------------+
+| dep_no |  name   | `count`(*) OVER (PARTITION BY dep_no) |
++--------+---------+---------------------------------------+
+| 3      | Jane    | 2                                     |
+| 3      | Jeff    | 2                                     |
+| 1      | Eric    | 3                                     |
+| 1      | Alex    | 3                                     |
+| 1      | Frank   | 3                                     |
+| 2      | Felix   | 4                                     |
+| 2      | Tom     | 4                                     |
+| 2      | Paul    | 4                                     |
+| 2      | Charles | 4                                     |
++--------+---------+---------------------------------------+
+```
+
+在此示例中，我们按照部门对员工进行分组，并计算每个部门的人数。
+
+#### 示例 2：计算每个部门按照工资递增排序后的累计人数
+
+```sql
+SELECT dep_no,name, count(*) OVER (PARTITION BY dep_no ORDER BY salary)
+FROM VALUES
+  ('Eric', 1, 28000),
+  ('Alex', 1, 32000),
+  ('Felix', 2, 21000),
+  ('Frank', 1, 30000),
+  ('Tom', 2, 23000),
+  ('Jane', 3, 29000),
+  ('Jeff', 3, 35000),
+  ('Paul', 2, 29000),
+  ('Charles', 2, 23000)
+AS tab(name, dep_no, salary);
++--------+---------+-----------------------------------------------------------+
+| dep_no |  name   | `count`(*) OVER (PARTITION BY dep_no ORDER BY salary ASC) |
++--------+---------+-----------------------------------------------------------+
+| 3      | Jane    | 1                                                         |
+| 3      | Jeff    | 2                                                         |
+| 1      | Eric    | 1                                                         |
+| 1      | Frank   | 2                                                         |
+| 1      | Alex    | 3                                                         |
+| 2      | Felix   | 1                                                         |
+| 2      | Tom     | 3                                                         |
+| 2      | Charles | 3                                                         |
+| 2      | Paul    | 4                                                         |
++--------+---------+-----------------------------------------------------------+
+```
+
+在此示例中，我们按照部门对员工进行分组，并按照工资递增排序。
+
+

package/bin/skills/lakehouse-doc/references/sql_functions/window_functions/cume_dist.md

@@ -0,0 +1,104 @@
+### CUME\_DIST 函数
+
+```sql
+cume_dist() OVER ([PARTITION BY column1, column2, ...] [ORDER BY column1 [ASC|DESC], column2 [ASC|DESC], ...])
+```
+
+#### 功能描述
+
+CUME\_DIST 函数用于计算当前行在指定分区中的累计分布比例。具体来说，它返回一个 double 类型的值，表示在当前行及其之前的所有行（在分区内）占整个分区行数的比例。该函数通常用于数据分析，以便了解数据在不同分组中的分布情况。
+
+#### 使用说明
+
+* PARTITION BY 子句用于将数据分为不同的分区。如果未指定 PARTITION BY 子句，则整个数据集将被视为一个分区。
+* ORDER BY 子句用于指定在每个分区内如何对数据进行排序。CUME\_DIST 函数的结果依赖于 ORDER BY 子句的排序顺序。
+* 如果 ORDER BY 列中存在相同的值，CUME\_DIST 函数将为这些行返回相同的结果，即最后一行的 row\_number() 除以窗口行数。
+
+#### 返回结果
+
+* 返回值类型为 double 类型。
+* 结果等于 `last_peer_row_number / partition_row_count`，其中 last\_peer\_row\_number 表示当前行及其之前的所有行（在分区内）的最大 row\_number() 值，partition\_row\_count 表示分区内的总行数。
+
+#### 示例
+
+```sql
+SELECT a,
+       b,
+       ROW_NUMBER() OVER(PARTITION BY a ORDER BY b) AS row_num,
+       CUME_DIST() OVER (PARTITION BY a ORDER BY b) AS cume_dist
+FROM VALUES ('A', 2), ('A', 1), ('B', 3), ('A', 1) tab(a, b);
+```
+
+结果：
+
+```
+A	b	row_num	cume_dist
+------------------------------------------------------------------------------------------
+A	1	1	0.6666666666666666
+A	1	2	0.6666666666666666
+A	2	3	1.0
+B	3	1	1.0
+```
+
+在这个示例中，我们可以看到：
+
+* 当 a = 'A' 时，有两个行（b = 1 和 b = 2），它们的 cume\_dist 分别为 0.67（2/3）和 1（3/3）。
+* 当 a = 'B' 时，只有一个行（b = 3），它的 cume\_dist 为 1（1/1）。
+
+#### 更多示例
+
+1. 计算每个部门内员工工资的累计分布：
+
+```sql
+SELECT dep_no,
+       name,
+       salary,
+       CUME_DIST() OVER (PARTITION BY dep_no ORDER BY salary) AS cume_dist_salary
+FROM VALUES
+  ('Eric', 1, 28000),
+  ('Alex', 1, 32000),
+  ('Felix', 2, 21000),
+  ('Frank', 1, 30000),
+  ('Tom', 2, 23000),
+  ('Jane', 3, 29000),
+  ('Jeff', 3, 35000),
+  ('Paul', 2, 29000),
+  ('Charles', 2, 23000),
+  ('null',4,null)
+AS tab(name, dep_no, salary);
++--------+---------+--------+--------------------+
+| dep_no |  name   | salary |  cume_dist_salary  |
++--------+---------+--------+--------------------+
+| 3      | Jane    | 29000  | 0.5                |
+| 3      | Jeff    | 35000  | 1.0                |
+| 1      | Eric    | 28000  | 0.3333333333333333 |
+| 1      | Frank   | 30000  | 0.6666666666666666 |
+| 1      | Alex    | 32000  | 1.0                |
+| 2      | Felix   | 21000  | 0.25               |
+| 2      | Tom     | 23000  | 0.75               |
+| 2      | Charles | 23000  | 0.75               |
+| 2      | Paul    | 29000  | 1.0                |
+| 4      | null    | null   | 1.0                |
++--------+---------+--------+--------------------+
+```
+
+2. 计算每个类别内商品销售额的累计分布：
+
+```sql
+SELECT category_id,
+       product_id,
+       sales_amount,
+       CUME_DIST() OVER (PARTITION BY category_id ORDER BY sales_amount) AS cume_dist_sales
+FROM sales_data;
+```
+
+3. 计算每个年龄段内用户数量的累计分布：
+
+```sql
+SELECT age_group,
+       user_id,
+       CUME_DIST() OVER (ORDER BY age_group) AS cume_dist_users
+FROM users;
+```
+
+通过这些示例，您可以更好地了解 CUME\_DIST 函数在不同场景下的应用。