@clickzetta/cz-cli-darwin-x64 0.3.1

package/bin/skills/lakehouse-doc/references/sql_functions/aggregate_functions/group_bitmap_xor_state.md

@@ -0,0 +1,99 @@
+# GROUP_BITMAP_XOR_STATE 函数
+
+## 简介
+
+`GROUP_BITMAP_XOR_STATE` 函数用于计算一组 `Bitmap` 数据的按位异或（`XOR`）操作，并返回中间状态。该函数在处理大规模数据集时非常高效，尤其适用于需要对多个 `Bitmap` 进行异或操作的场景。返回的中间状态可以用于后续的合并操作，从而实现更复杂的聚合逻辑。
+
+## 语法
+
+```sql
+group_bitmap_xor_state(bitmap)
+```
+
+## 参数
+
+* `bitmap`：`BITMAP` 类型的表达式，表示需要进行按位异或操作的 `Bitmap` 数据。
+
+## 返回值
+
+返回一个中间状态的 `BITMAP` 对象，表示按位异或操作的中间结果。该中间状态可以用于后续的合并操作。
+
+## 使用示例
+
+示例 1：计算多个 `Bitmap` 的按位异或操作的中间状态
+
+假设有一个数据表 `t`，其中包含列 `v`，存储了多个数组。现在需要计算这些数组的按位异或操作的中间状态。
+
+```sql
+SELECT bitmap_to_array(group_bitmap_xor_state(bitmap_build(v))) AS xor_state
+FROM VALUES
+  (ARRAY(1, 2, 3, 4, 5, 6, 7, 8, 9, 10)),
+  (ARRAY(6, 7, 8, 9, 10, 11, 12, 13, 14, 15)),
+  (ARRAY(2, 4, 6, 8, 10, 12))
+AS t(v);
++----------------------------+
+|         xor_state          |
++----------------------------+
+| [1,3,5,6,8,10,11,13,14,15] |
++----------------------------+
+```
+
+**结果**：
+返回一个中间状态的 `Bitmap` 对象，表示按位异或操作的中间结果。
+
+示例 2：与 `group_bitmap_merge` 结合使用
+
+```sql
+SELECT group_bitmap_merge(xor_state) AS final_bitmap
+FROM (
+  SELECT group_bitmap_xor_state(bitmap_build(v)) AS xor_state
+  FROM VALUES
+    (ARRAY(1, 2, 3, 4, 5, 6, 7, 8, 9, 10)),
+    (ARRAY(6, 7, 8, 9, 10, 11, 12, 13, 14, 15)),
+    (ARRAY(2, 4, 6, 8, 10, 12))
+  AS t(v)
+);
++--------------+
+| final_bitmap |
++--------------+
+| 10           |
++--------------+
+```
+
+**结果**：
+返回一个完整的 `Bitmap`，表示所有输入 `Bitmap` 的按位异或操作的结果。
+
+示例 3：直接计算最终结果
+
+`group_bitmap_xor` 函数用于直接计算按位异或操作的最终结果，适用于不需要中间状态的场景。
+
+```sql
+SELECT group_bitmap_xor(bitmap_build(v)) AS final_bitmap
+FROM VALUES
+  (ARRAY(1, 2, 3, 4, 5, 6, 7, 8, 9, 10)),
+  (ARRAY(6, 7, 8, 9, 10, 11, 12, 13, 14, 15)),
+  (ARRAY(2, 4, 6, 8, 10, 12))
+AS t(v);
++--------------+
+| final_bitmap |
++--------------+
+| 10           |
++--------------+
+```
+
+**结果**：
+返回一个完整的 `Bitmap`，表示所有输入 `Bitmap` 的按位异或操作的结果。
+
+## 注意事项
+
+1. **输入类型**：请确保输入的 `bitmap` 是 `BITMAP` 类型，否则会导致函数执行失败。
+2. **中间状态的使用**：返回的中间状态可以用于后续的合并操作，从而实现更复杂的聚合逻辑。
+3. **性能优化**：在处理大规模数据集时，`group_bitmap_xor_state` 函数非常高效。但如果数据量过大，仍需注意性能影响。在可能的情况下，尝试优化输入数据以提高函数执行效率。
+4. **客户端支持**：客户端可能不支持直接打印 `BITMAP` 类型的结果。如果需要查看结果，可以使用 `bitmap_to_array` 函数将 `Bitmap` 转换为数组形式。
+
+## 相关函数
+
+* `group_bitmap_xor`：直接计算按位异或操作的最终结果。
+* `group_bitmap_merge`：合并多个中间状态的 `Bitmap` 对象。
+* `bitmap_xor`：对两个 `Bitmap` 进行按位异或操作。
+* `bitmap_to_array`：将 `Bitmap` 转换为数组形式，便于查看结果。

package/bin/skills/lakehouse-doc/references/sql_functions/aggregate_functions/group_concat.md

@@ -0,0 +1,53 @@
+#### 简介
+
+`group_concat` 函数用于将一组字符串值连接成一个单一的字符串。当处理多个行或记录时，此函数非常有用，可以将来自同一组的结果合并为一个字符串，通常用于报表生成和数据汇总场景。
+
+#### 语法
+
+```sql
+group_concat(expression [SEPARATOR sep_string]) [FILTER (WHERE condition)]
+```
+
+#### 参数
+
+* `expression`: 要连接的列或表达式。
+* `sep_string`: （可选）用作分隔符的字符串。如果省略，`Lakehouse` 默认使用逗号（`,`）作为分隔符。
+
+#### 返回结果
+
+* 返回一个字符串，其中包含连接后的所有非 `NULL` 值，值之间由指定的分隔符分隔。
+
+#### 使用示例
+
+1. 基本使用：
+
+```sql
+SELECT a, group_concat(b SEPARATOR "-")
+FROM VALUES ('A1', 2), ('A1', 1), ('A2', 3), ('A1', 1) AS tab(a, b)
+GROUP BY a;
++----+-------------------+
+| a  | WM_CONCAT('-', b) |
++----+-------------------+
+| A2 | 3                 |
+| A1 | 2-1-1             |
++----+-------------------+
+```
+
+2. 使用 FILTER 子句条件性地连接字符串：
+
+```sql
+SELECT a, group_concat(b SEPARATOR "-") FILTER (WHERE b > 1)
+FROM VALUES ('A1', 2), ('A1', 1), ('A2', 3), ('A1', 3) AS tab(a, b)
+GROUP BY a;
++----+----------------------------------------------------+
+| a  | WM_CONCAT('-', b) FILTER (WHERE (b > 1))           |
++----+----------------------------------------------------+
+| A2 | 3                                                  |
+| A1 | 2-3                                                |
++----+----------------------------------------------------+
+```
+
+#### 注意事项
+
+* 如果结果字符串超过系统设定的最大长度限制，`group_concat` 可能会报错。在 `Lakehouse` 中，可以通过设置表属性 `cz.storage.write.max.string.bytes` 系统变量来调整这个限制。
+* 在使用 `group_concat` 函数时，应注意 `NULL` 值会被忽略，不会包含在最终的字符串中。

package/bin/skills/lakehouse-doc/references/sql_functions/aggregate_functions/last_value.md

@@ -0,0 +1,100 @@
+### LAST_VALUE 函数
+
+```
+last_value(expr [, ignoreNulls]) [FILTER (WHERE condition)]
+last(expr [, ignoreNulls]) [FILTER (WHERE condition)]
+```
+
+#### 功能描述
+
+`LAST_VALUE` 函数用于返回聚合组或窗口中的最后一个值。可以选择是否忽略 `NULL` 值。`last` 是 `last_value` 的别名。
+
+#### 参数说明
+
+* `expr`：任意类型的表达式，要获取其最后一个值。
+* `ignoreNulls`：可选的布尔值参数，默认为 `false`。
+  * `false`（默认）：返回最后一个值，即使是 `NULL`。
+  * `true`：忽略 `NULL` 值，返回最后一个非 `NULL` 值。
+
+#### 返回类型
+
+* 返回与输入表达式相同的数据类型。
+* 返回聚合组或窗口中的最后一个值。
+
+#### 注意事项
+
+* 如果所有值都是 `NULL`（且 `ignoreNulls` 为 `true`），则返回 `NULL`。
+* 如果输入为空集，返回 `NULL`。
+* 在 `GROUP BY` 查询中，返回每个分组的最后一个值。使用 `WITHIN GROUP (ORDER BY ...)` 可以指定确定性的顺序。
+
+#### 使用示例
+
+1. 基本用法：返回最后一个值
+
+```sql
+SELECT last_value(col), last(col)
+FROM VALUES (10), (5), (20) AS tab(col);
++-----------------+-----------+
+| last_value(col) | last(col) |
++-----------------+-----------+
+| 20              | 20        |
++-----------------+-----------+
+```
+
+2. 处理 NULL 值（默认返回最后一个值，即使是 NULL）
+
+```sql
+SELECT last_value(col), last(col)
+FROM VALUES (NULL), (5), (NULL) AS tab(col);
++-----------------+-----------+
+| last_value(col) | last(col) |
++-----------------+-----------+
+| NULL            | NULL      |
++-----------------+-----------+
+```
+
+3. 忽略 NULL 值，返回最后一个非 NULL 值
+
+```sql
+SELECT last_value(col, true), last(col, true)
+FROM VALUES (NULL), (5), (NULL) AS tab(col);
++-----------------------+------------------+
+| last_value(col, true) | last(col, true)  |
++-----------------------+------------------+
+| 5                     | 5                |
++-----------------------+------------------+
+```
+
+4. 使用 WITHIN GROUP (ORDER BY ...) 指定顺序
+
+```sql
+SELECT a,
+       last_value(b) WITHIN GROUP(ORDER BY c) as last_b,
+       last_value(b, true) WITHIN GROUP(ORDER BY c) as last_non_null_b
+FROM VALUES
+  ('apple', 11, 22),
+  ('apple', 1, 2),
+  ('orange', NULL, 1),
+  ('orange', 111, 2),
+  ('orange', NULL, 3)
+AS t(a, b, c)
+GROUP BY a;
++--------+--------+-----------------+
+| a      | last_b | last_non_null_b |
++--------+--------+-----------------+
+| apple  | 11     | 11              |
+| orange | NULL   | 111             |
++--------+--------+-----------------+
+```
+
+5. 使用 FILTER 子句条件性地获取最后一个值
+
+```sql
+SELECT last_value(col) FILTER (WHERE col < 15)
+FROM VALUES (3), (10), (7), (12) AS tab(col);
++-------------------------------------------+
+| last_value(col) FILTER (WHERE (col < 15)) |
++-------------------------------------------+
+| 12                                        |
++-------------------------------------------+
+```

package/bin/skills/lakehouse-doc/references/sql_functions/aggregate_functions/map_agg.md

@@ -0,0 +1,79 @@
+### MAP_AGG 函数
+
+```
+map_agg(key, value)
+```
+
+#### 功能描述
+
+`MAP_AGG` 函数用于将键值对聚合成一个 `MAP` 类型的数据结构。该函数收集所有的键值对，并将它们组合成一个 Map，其中每个键对应一个值。
+
+#### 参数说明
+
+* `key`：任意可比较基本类型的表达式，作为 Map 的键。
+  * `NULL` 键会被忽略。
+  * 重复的键会保留第一个出现的值。
+* `value`：任意类型的表达式，作为 Map 的值。
+  * `value` 可以是 `NULL`。
+
+#### 返回类型
+
+* 返回 `map<key_type, value_type>` 类型（非空）。
+* 返回包含所有键值对的 Map。
+
+#### 注意事项
+
+* 如果所有 `key` 都是 `NULL`，返回空 Map `{}`。
+* 如果输入为空集，返回空 Map `{}`。
+* `key` 的顺序在 Map 中是不确定的，不要依赖顺序。
+* 重复 `key` 的行为可能因实现而异，建议避免使用重复的 `key`。
+
+#### 使用示例
+
+1. 基本用法：聚合键值对为 Map
+
+```sql
+SELECT map_agg(id, name)
+FROM VALUES (1, 'Alice'), (2, 'Bob'), (3, 'Charlie') AS t(id, name);
++---------------------------------+
+| map_agg(id, name)               |
++---------------------------------+
+| {1:"Alice",2:"Bob",3:"Charlie"} |
++---------------------------------+
+```
+
+2. NULL key 会被忽略
+
+```sql
+SELECT map_agg(a, b)
+FROM VALUES (1, 'apple'), (2, 'hi'), (NULL, 'good'), (3, NULL) AS t(a, b);
++--------------------------------+
+| map_agg(a, b)                  |
++--------------------------------+
+| {1:"apple",2:"hi",3:null}      |
++--------------------------------+
+```
+
+3. 重复的 key，保留第一个值
+
+```sql
+SELECT map_agg(a, b)
+FROM VALUES (1, 'apple'), (2, 'hi'), (1, 'pie') AS t(a, b);
++-------------------------+
+| map_agg(a, b)           |
++-------------------------+
+| {1:"apple",2:"hi"}      |
++-------------------------+
+```
+
+4. 所有 key 都是 NULL 时返回空 Map
+
+```sql
+SELECT map_agg(a, b)
+FROM VALUES (NULL, 'apple'), (NULL, 'banana') AS t(a, b);
++----------------+
+| map_agg(a, b)  |
++----------------+
+| {}             |
++----------------+
+```

package/bin/skills/lakehouse-doc/references/sql_functions/aggregate_functions/max.md

@@ -0,0 +1,102 @@
+### MAX 函数
+
+```
+max([DISTINCT] expr) [FILTER (WHERE condition)]
+```
+
+#### 功能描述
+
+`MAX` 函数用于从一组数据中找出最大值。该函数适用于多种数据类型，包括数值型、时间型和字符串型等。
+
+#### 参数说明
+
+* `expr`: 可比较的数据类型，支持的类型包括：
+  * 数值类型：`TINYINT`、`SMALLINT`、`INT`、`BIGINT`、`FLOAT`、`DOUBLE` 和 `DECIMAL`；
+  * 时间类型：`DATE` 和 `TIMESTAMP`；
+  * 字符串类型：`CHAR`、`VARCHAR`、`STRING` 和 `BINARY`。
+* `DISTINCT`: 可选参数，用于指定是否去除重复值。若设置 `DISTINCT`，则返回去重后的集合中的最大值。注意，对于数值型数据，`DISTINCT` 并不会对结果产生影响。
+
+#### 返回值
+
+* 返回值的类型与输入参数 `expr` 的类型相同。
+* 如果输入参数中包含 `NULL` 值，则这些值不会参与计算。
+* 设置 `DISTINCT` 参数不会影响数值型数据的结果。
+
+#### 使用示例
+
+1. 求数值型数据的最大值：
+
+```sql
+SELECT max(col) FROM VALUES (10), (50), (20), (NULL) AS tab(col);
++------------+
+| `max`(col) |
++------------+
+| 50         |
++------------+
+```
+
+2. 求时间型数据的最大值：
+
+```sql
+SELECT max(col) FROM VALUES ('2023-01-01'), ('2022-12-31'), ('2023-02-01') AS tab(col);
++------------+
+| `max`(col) |
++------------+
+| 2023-02-01 |
++------------+
+```
+
+3. 求字符串型数据的最大值：
+
+```sql
+SELECT max(col) FROM VALUES ('apple'), ('banana'), ('cherry') AS tab(col);
++------------+
+| `max`(col) |
++------------+
+| cherry     |
++------------+
+```
+
+4. 使用 `DISTINCT` 参数求数值型数据的最大值（对结果无影响）：
+
+```sql
+SELECT max(DISTINCT col) FROM VALUES (10), (50), (20), (NULL), (10) AS tab(col);
++---------------------+
+| `max`(DISTINCT col) |
++---------------------+
+| 50                  |
++---------------------+
+```
+
+5. 使用 `DISTINCT` 参数求字符串型数据的最大值：
+
+```sql
+SELECT max(DISTINCT col) FROM VALUES ('apple'), ('banana'), ('cherry'), ('apple') AS tab(col);
++---------------------+
+| `max`(DISTINCT col) |
++---------------------+
+| cherry              |
++---------------------+
+```
+
+6. 使用 FILTER 子句条件性地找出最大值：
+
+```sql
+SELECT max(col) FILTER (WHERE col < 40) FROM VALUES (10), (20), (50), (NULL) AS tab(col);
++---------------------------------------+
+| `max`(col) FILTER (WHERE (col < 40))  |
++---------------------------------------+
+| 20                                    |
++---------------------------------------+
+```
+
+7. 结合 FILTER 子句和 DISTINCT 找出条件最大值：
+
+```sql
+SELECT max(DISTINCT col) FILTER (WHERE col != 'cherry') FROM VALUES ('apple'), ('banana'), ('cherry'), ('apple') AS tab(col);
++--------------------------------------------------------------+
+| `max`(DISTINCT col) FILTER (WHERE (NOT (col = 'cherry')))    |
++--------------------------------------------------------------+
+| banana                                                       |
++--------------------------------------------------------------+
+```

package/bin/skills/lakehouse-doc/references/sql_functions/aggregate_functions/max_by.md

@@ -0,0 +1,67 @@
+### MAX_BY 函数
+
+```sql
+max_by(expr1, expr2) [FILTER (WHERE condition)]
+```
+
+#### 功能描述
+
+`MAX_BY` 函数用于从一组数据中返回与 `expr2` 表达式的最大值相关联的 `expr1` 表达式的值。该函数在处理成对的数据时非常有用，可以帮助您快速找到与最大值相对应的数据项。
+
+#### 参数说明
+
+* `expr1`：任何数据类型的表达式。
+* `expr2`：可比较的数据类型表达式，包括数值类型（如 `TINYINT`、`SMALLINT`、`INT`、`BIGINT`、`FLOAT`、`DOUBLE`、`DECIMAL`），时间类型（如 `DATE`、`TIMESTAMP`）以及字符串类型（如 `CHAR`、`VARCHAR`、`STRING`、`BINARY`）。
+
+#### 返回结果
+
+返回与 `expr2` 表达式的最大值相关联的 `expr1` 表达式的值。结果类型与 `expr1` 的类型匹配。如果 `expr2` 中的所有值均为 `NULL`，则返回 `NULL`。
+
+#### 使用示例
+
+1.  从一组字符串和整数数据中找到与最大整数值相关联的字符串：
+
+    ```sql
+SELECT max_by(str, num) FROM VALUES ('apple', 1), ('banana', 3), ('cherry', 2) AS tab(str, num);
++------------------+
+| max_by(str, num) |
++------------------+
+| banana           |
++------------------+
+```
+
+2.  从一组日期和字符串数据中找到与最晚日期相关联的字符串：
+
+    ```sql
+SELECT max_by(str, date)
+FROM VALUES ('event1', '2022-01-01'), ('event2', '2022-02-01'), ('event3', '2022-01-15') AS tab(str, date);
++---------------------+
+| max_by(str, `date`) |
++---------------------+
+| event2              |
++---------------------+
+```
+
+3.  从一组员工姓名和工资数据中找到与最高工资相关联的员工姓名：
+
+    ```sql
+SELECT max_by(name, salary)
+FROM VALUES ('Alice', 5000), ('Bob', 6000), ('Charlie', 4500) AS tab(name, salary);
++----------------------+
+| max_by(name, salary) |
++----------------------+
+| Bob                  |
++----------------------+
+```
+
+4.  使用 FILTER 子句条件性地查找关联值：
+
+    ```sql
+SELECT max_by(name, salary) FILTER (WHERE salary < 6000)
+FROM VALUES ('Alice', 5000), ('Bob', 6000), ('Charlie', 4500) AS tab(name, salary);
++------------------------------------------------------+
+| max_by(name, salary) FILTER (WHERE (salary < 6000))  |
++------------------------------------------------------+
+| Alice                                                |
++------------------------------------------------------+
+```

package/bin/skills/lakehouse-doc/references/sql_functions/aggregate_functions/median.md

@@ -0,0 +1,60 @@
+### MEDIAN 函数
+
+```
+median(expr)
+```
+
+#### 功能描述
+
+`MEDIAN` 函数用于计算数值列的中位数。中位数是将数据集按大小顺序排列后位于中间位置的值。该函数等价于 `percentile(expr, 0.5)`，即计算第 50 百分位数。
+
+#### 参数说明
+
+* `expr`：数值类型的表达式，可以是整数、浮点数或 `DECIMAL` 类型。
+
+#### 返回类型
+
+* 返回 `DOUBLE` 类型。
+* 返回数据集的中位数。
+
+#### 注意事项
+
+* 如果输入为空集，返回 `NULL`。
+* 对于偶数个值，返回中间两个值的平均值。
+* 对于奇数个值，返回正中间的值。
+* `NULL` 值会被自动忽略，不参与计算。
+
+#### 使用示例
+
+1. 基本用法：计算中位数
+
+```sql
+SELECT median(col) FROM VALUES (0), (10) AS tab(col);
++--------------+
+| median(col)  |
++--------------+
+| 5.0          |
++--------------+
+```
+
+2. 偶数个值的中位数（两个中间值的平均值）
+
+```sql
+SELECT median(value) FROM VALUES (1), (2), (3), (4) AS t(value);
++----------------+
+| median(value)  |
++----------------+
+| 2.5            |
++----------------+
+```
+
+3. 奇数个值的中位数
+
+```sql
+SELECT median(value) FROM VALUES (1), (2), (3), (4), (5) AS t(value);
++----------------+
+| median(value)  |
++----------------+
+| 3.0            |
++----------------+
+```

package/bin/skills/lakehouse-doc/references/sql_functions/aggregate_functions/min.md

@@ -0,0 +1,89 @@
+### MIN 函数
+
+```
+min([DISTINCT] expr) [FILTER (WHERE condition)]
+```
+
+#### 功能描述
+
+`MIN` 函数用于从一组数据中找出最小值。该函数支持多种数据类型，包括数值类型（如 `TINYINT`、`SMALLINT`、`INT`、`BIGINT`、`FLOAT`、`DOUBLE` 和 `DECIMAL`）、时间类型（如 `DATE` 和 `TIMESTAMP`）、字符串类型（如 `CHAR`、`VARCHAR` 和 `STRING`）以及 `BINARY` 类型。
+
+#### 参数说明
+
+* `expr`：可比较的数据类型，包括数值类型、时间类型和字符串类型。
+
+#### 返回结果
+
+* 返回值类型与输入参数类型相同。
+* 若设置 `DISTINCT` 关键字，则计算去重后的集合中的最小值，但对结果无影响。
+* `NULL` 值不参与计算。
+
+#### 使用示例
+
+1. 从一组数值中找出最小值：
+
+```sql
+SELECT min(col) FROM VALUES (10), (50), (20), (NULL) AS tab(col);
++------------+
+| `min`(col) |
++------------+
+| 10         |
++------------+
+```
+
+2. 从一组时间类型数据中找出最小值：
+
+```sql
+SELECT min(col) FROM VALUES ('2023-01-01'), ('2022-12-31'), ('2023-02-01') AS tab(col);
++------------+
+| `min`(col) |
++------------+
+| 2022-12-31 |
++------------+
+```
+
+3. 从一组字符串类型数据中找出最小值：
+
+```sql
+SELECT min(col) FROM VALUES ('apple'), ('banana'), ('cherry') AS tab(col);
++------------+
+| `min`(col) |
++------------+
+| apple      |
++------------+
+```
+
+4. 使用 `DISTINCT` 关键字从一组数值中找出最小值（对结果无影响）：
+
+```sql
+SELECT min(DISTINCT col) FROM VALUES (10), (50), (20), (NULL), (10), (20) AS tab(col);
++---------------------+
+| `min`(DISTINCT col) |
++---------------------+
+| 10                  |
++---------------------+
+```
+
+5. 使用 FILTER 子句条件性地找出最小值：
+
+```sql
+SELECT min(col) FILTER (WHERE col > 15) FROM VALUES (10), (20), (50), (NULL) AS tab(col);
++---------------------------------------+
+| `min`(col) FILTER (WHERE (col > 15))  |
++---------------------------------------+
+| 20                                    |
++---------------------------------------+
+```
+
+6. 结合 FILTER 子句和 DISTINCT 找出条件最小值：
+
+```sql
+SELECT min(DISTINCT col) FILTER (WHERE col < 50) FROM VALUES (10), (10), (20), (50) AS tab(col);
++------------------------------------------------------+
+| `min`(DISTINCT col) FILTER (WHERE (col < 50))        |
++------------------------------------------------------+
+| 10                                                   |
++------------------------------------------------------+
+```
+
+通过以上示例，您可以看到 `MIN` 函数在不同数据类型中的应用。请注意，`NULL` 值不参与计算。