@clickzetta/cz-cli-darwin-x64 0.3.1

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

@@ -0,0 +1,62 @@
+### 函数名称：approx_top_k
+
+```sql
+approx_top_k(col, k, [maxItemsTracked])
+```
+
+#### 功能描述
+
+该函数用于从指定列（`col`）中提取出现频率最高的前 `k` 个项目值，并返回它们的近似计数。这是一个基于概率的数据结构实现，因此结果可能会有一定的误差，但在大多数情况下，它能有效地反映数据的分布情况。
+
+#### 参数说明
+
+* `col`: 输入列，可以是数值类型、字符串类型或嵌套类型。
+* `k`: 需要返回的前 `k` 个最常出现项的数目，需为大于 0 的整数值。
+* `maxItemsTracked`: 可选参数，用于指定跟踪的最大项目数。默认值为 10000。如果指定的 `maxItemsTracked` 大于或等于 `k`，则使用指定值；否则，将使用 `k` 作为跟踪的最大项目数。
+
+#### 返回结果
+
+函数返回一个结构化数组，每个元素为一个结构体，包含三个字段：`item`（原始输入类型的值）、`count`（长整型，表示该项出现的近似次数）和 `approximation`（布尔值，表示结果是否为近似值，始终为 `true`）。数组按照 `count` 字段降序排列。
+
+#### 使用示例
+
+以下示例展示了如何使用 `approx_top_k` 函数来获取数据中最常见的项目及其出现次数。
+
+**示例 1**：
+
+```sql
+SELECT approx_top_k(col, 1) FROM VALUES (7), (7), (6), (9), (8), (7) AS tab(col);
++-------------------------+
+|  approx_top_k(col, 1)   |
++-------------------------+
+| [{"value":7,"count":3}] |
++-------------------------+
+```
+
+**示例 2**：
+
+```sql
+SELECT approx_top_k(col, 2, 100) FROM VALUES (7), (6), (6), (7), (9), (8), (7) AS tab(col);
++-----------------------------------------------+
+|           approx_top_k(col, 2, 100)           |
++-----------------------------------------------+
+| [{"value":7,"count":3},{"value":6,"count":2}] |
++-----------------------------------------------+
+```
+
+**示例 3**：
+
+```sql
+SELECT approx_top_k(col, 3)
+FROM VALUES ('apple'), ('banana'), ('apple'), ('orange'), ('banana'), ('apple') AS tab(col);
++-----------------------------------------------------------------------------------------+
+|                                  approx_top_k(col, 3)                                   |
++-----------------------------------------------------------------------------------------+
+| [{"value":"apple","count":3},{"value":"banana","count":2},{"value":"orange","count":1}] |
++-----------------------------------------------------------------------------------------+
+```
+
+**注意**：
+
+* 由于 `approx_top_k` 函数是基于概率的，因此返回的结果可能会有一定的误差。在实际应用中，可以通过调整 `maxItemsTracked` 参数来平衡精度和性能。
+* 当处理大量数据时，为了提高性能，可以适当降低 `maxItemsTracked` 的值。但请注意，这可能会影响结果的准确性。

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

@@ -0,0 +1,68 @@
+### AVG 函数
+
+```
+avg([DISTINCT] expr) [FILTER (WHERE condition)]
+```
+
+#### 功能描述
+
+`AVG` 函数用于计算指定表达式在一组数据中的算术平均值。当指定 `DISTINCT` 关键字时，将计算去重后的平均值。
+
+#### 参数说明
+
+* `expr`：数值类型表达式，可以是 `TINYINT`、`SMALLINT`、`INT`、`BIGINT`、`FLOAT`、`DOUBLE` 或 `DECIMAL` 类型。
+
+#### 返回类型
+
+* 对于 `DECIMAL` 类型表达式，`AVG` 函数返回 `DECIMAL` 类型的结果。返回值的精度（`precision`）和标度（`scale`）可能会增加以适应计算结果。
+* 对于其他数值类型表达式，`AVG` 函数返回 `DOUBLE` 类型的结果。
+
+#### 注意事项
+
+* 函数计算过程中，`NULL` 值将被忽略，不参与平均值的计算。
+
+#### 使用示例
+
+1. 计算数值列的平均值（不包含 `NULL` 值）：
+
+```sql
+SELECT avg(col) FROM VALUES (1), (2), (3), (4), (NULL) AS tab(col);
++------------+
+| `avg`(col) |
++------------+
+| 2.5        |
++------------+
+```
+
+2. 计算去重后数值列的平均值：
+
+```sql
+SELECT avg(DISTINCT col) FROM VALUES (1), (1), (2), (3), (4), (NULL) AS tab(col);
++---------------------+
+| `avg`(DISTINCT col) |
++---------------------+
+| 2.5                 |
++---------------------+
+```
+
+3. 使用 FILTER 子句条件性地计算平均值：
+
+```sql
+SELECT avg(col) FILTER (WHERE col > 2) FROM VALUES (1), (2), (3), (4), (NULL) AS tab(col);
++---------------------------------------+
+| `avg`(col) FILTER (WHERE (col > 2))   |
++---------------------------------------+
+| 3.5                                   |
++---------------------------------------+
+```
+
+4. 结合 FILTER 子句和 DISTINCT 计算去重后的条件平均值：
+
+```sql
+SELECT avg(DISTINCT col) FILTER (WHERE col <= 3) FROM VALUES (1), (1), (2), (3), (4) AS tab(col);
++------------------------------------------------------+
+| `avg`(DISTINCT col) FILTER (WHERE (col <= 3))        |
++------------------------------------------------------+
+| 2.0                                                  |
++------------------------------------------------------+
+```

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

@@ -0,0 +1,81 @@
+### BIT_AND 函数
+
+```sql
+bit_and([DISTINCT] expr) [FILTER (WHERE condition)]
+```
+
+#### 功能描述
+
+`BIT_AND` 函数用于计算指定表达式在一组数据中的按位与结果。该函数对整数类型的数据进行操作，包括 `TINYINT`、`SMALLINT`、`INT` 和 `BIGINT` 类型。通过使用 `BIT_AND` 函数，可以对数据进行位运算，从而实现对数据的精确控制和处理。
+
+#### 参数说明
+
+* `expr` (必需): 整数类型的表达式，包括 `TINYINT`、`SMALLINT`、`INT` 和 `BIGINT` 类型。
+* `DISTINCT` (可选): 当设置为 `DISTINCT` 时，函数将计算去重后的集合的按位与结果。
+
+#### 返回结果
+
+* 返回值类型与参数类型一致。
+* 如果设置了 `DISTINCT`，则返回去重后的集合的按位与结果。
+* `NULL` 值不参与计算。
+
+#### 使用示例
+
+1.  计算一组数据的按位与结果（未设置 `DISTINCT`）：
+
+    ```sql
+SELECT bit_and(col) FROM VALUES (3), (5), (7) AS tab(col);
++--------------+
+| bit_and(col) |
++--------------+
+| 1            |
++--------------+
+```
+
+2.  计算一组数据的按位与结果（设置 `DISTINCT` 并包含重复值）：
+
+    ```sql
+SELECT bit_and(DISTINCT col) FROM VALUES (3), (3), (5), (7), (NULL) AS tab(col);
++-----------------------+
+| bit_and(DISTINCT col) |
++-----------------------+
+| 1                     |
++-----------------------+
+```
+
+3.  计算一组数据的按位与结果（包含 `NULL` 值）：
+
+    ```sql
+SELECT bit_and(col) FROM VALUES (3), (NULL), (5), (7) AS tab(col);
++--------------+
+| bit_and(col) |
++--------------+
+| 1            |
++--------------+
+```
+
+4.  计算不同整数类型的按位与结果：
+
+    ```sql
+SELECT bit_and(tinyint_col) AS col1,
+       bit_and(smallint_col) AS col2,
+       bit_and(int_col) AS col3,
+       bit_and(bigint_col) AS col4
+FROM VALUES (11, 22, 33, 44) AS t(tinyint_col, smallint_col, int_col, bigint_col);
++------+------+------+------+
+| col1 | col2 | col3 | col4 |
++------+------+------+------+
+| 11   | 22   | 33   | 44   |
++------+------+------+------+
+```
+
+5.  使用 FILTER 子句条件性地计算按位与：
+
+    ```sql
+SELECT bit_and(col) FILTER (WHERE col > 3) FROM VALUES (3), (5), (7), (9) AS tab(col);
++---------------------------------------+
+| bit_and(col) FILTER (WHERE (col > 3)) |
++---------------------------------------+
+| 5                                     |
++---------------------------------------+
+```

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

@@ -0,0 +1,78 @@
+### BIT_OR 函数
+
+```sql
+bit_or([DISTINCT] expr) [FILTER (WHERE condition)]
+```
+
+#### 功能描述
+
+`BIT_OR` 函数用于计算一组整数表达式的按位或（`bitwise OR`）结果。该函数可以处理包括 `TINYINT`、`SMALLINT`、`INT` 和 `BIGINT` 在内的整数数据类型。通过使用该函数，用户可以对一组整数进行按位操作，从而得到一个新的整数值。
+
+#### 参数说明
+
+* `expr`：表示要进行按位或操作的整数表达式。要求参数类型为整数类型，包括 `TINYINT`、`SMALLINT`、`INT` 和 `BIGINT`。
+* `DISTINCT`（可选）：当设置为 `DISTINCT` 时，函数会计算去重后的集合的按位或结果。如果未设置 `DISTINCT`，则对所有表达式进行按位或操作，包括重复值。
+
+#### 返回结果
+
+* 返回值类型与参数类型一致，即整数类型（`TINYINT`、`SMALLINT`、`INT` 或 `BIGINT`）。
+* 如果所有输入参数都为 `NULL`，则返回 `NULL`。
+* 对于未设置 `DISTINCT` 的情况，`NULL` 值不参与计算。
+* 对于设置 `DISTINCT` 的情况，`NULL` 值也不参与计算。
+
+#### 使用示例
+
+1. 计算一组数值的按位或结果（未设置 `DISTINCT`）：
+
+```sql
+SELECT bit_or(col) FROM VALUES (3), (5), (7) AS tab(col);
++-------------+
+| bit_or(col) |
++-------------+
+| 7           |
++-------------+
+```
+
+2. 计算一组数值的去重后的按位或结果（设置 `DISTINCT`）：
+
+```sql
+SELECT bit_or(DISTINCT col) FROM VALUES (3), (3), (5), (7), (NULL) AS tab(col);
++----------------------+
+| bit_or(DISTINCT col) |
++----------------------+
+| 7                    |
++----------------------+
+```
+
+3. 计算含有 `NULL` 值的数值的按位或结果（未设置 `DISTINCT`）：
+
+```sql
+SELECT bit_or(col) FROM VALUES (3), (NULL), (7) AS tab(col);
++-------------+
+| bit_or(col) |
++-------------+
+| 7           |
++-------------+
+```
+
+4. 计算含有 `NULL` 值的数值的去重后的按位或结果（设置 `DISTINCT`）：
+
+```sql
+SELECT bit_or(DISTINCT col) FROM VALUES (3), (NULL), (7), (NULL) AS tab(col);
++----------------------+
+| bit_or(DISTINCT col) |
++----------------------+
+| 7                    |
++----------------------+
+```
+
+5. 使用 FILTER 子句条件性地计算按位或：
+
+```sql
+SELECT bit_or(col) FILTER (WHERE col < 6) FROM VALUES (3), (5), (7) AS tab(col);
++--------------------------------------+
+| bit_or(col) FILTER (WHERE (col < 6)) |
++--------------------------------------+
+| 7                                    |
++--------------------------------------+
+```

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

@@ -0,0 +1,79 @@
+### BIT_XOR 函数
+
+```sql
+bit_xor([DISTINCT] expr) [FILTER (WHERE condition)]
+```
+
+#### 功能描述
+
+`BIT_XOR` 函数用于计算一组整数数据的按位异或（`bitwise XOR`）结果。按位异或操作是指对两个二进制数的对应位进行比较，如果两个比特位相同，则结果为 0；如果不同，则结果为 1。
+
+#### 参数说明
+
+* `expr`：整数类型表达式，可以是 `TINYINT`、`SMALLINT`、`INT` 或 `BIGINT` 类型。
+* `DISTINCT`（可选）：当使用 `DISTINCT` 关键字时，函数将计算去重后的集合的按位异或结果。
+
+#### 返回结果
+
+* 返回值类型与参数类型一致。
+* 如果参数中包含 `NULL` 值，则该值不参与计算。
+
+#### 使用示例
+
+1. 计算一组整数的按位异或结果：
+
+```sql
+SELECT bit_xor(col) FROM VALUES (3), (5), (7) AS tab(col);
++--------------+
+| bit_xor(col) |
++--------------+
+| 1            |
++--------------+
+```
+
+2. 计算去重后的整数集合的按位异或结果：
+
+```sql
+SELECT bit_xor(DISTINCT col) FROM VALUES (3), (3), (5), (7), (NULL) AS tab(col);
++-----------------------+
+| bit_xor(DISTINCT col) |
++-----------------------+
+| 1                     |
++-----------------------+
+```
+
+3. 在实际数据表中计算按位异或结果：
+
+```sql
+CREATE TABLE example_table (id INT);
+INSERT INTO example_table VALUES (3), (5), (7);
+SELECT bit_xor(id) FROM example_table;
++-------------+
+| bit_xor(id) |
++-------------+
+| 1           |
++-------------+
+```
+
+4. 计算包含 `NULL` 值的整数集合的按位异或结果：
+
+```sql
+INSERT INTO example_table VALUES (NULL), (8);
+SELECT bit_xor(id) FROM example_table;
++-------------+
+| bit_xor(id) |
++-------------+
+| 9           |
++-------------+
+```
+
+5. 使用 FILTER 子句条件性地计算按位异或：
+
+```sql
+SELECT bit_xor(col) FILTER (WHERE col > 3) FROM VALUES (3), (5), (7) AS tab(col);
++---------------------------------------+
+| bit_xor(col) FILTER (WHERE (col > 3)) |
++---------------------------------------+
+| 2                                     |
++---------------------------------------+
+```

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

@@ -0,0 +1,85 @@
+### BOOL_AND 函数
+
+```sql
+bool_and([DISTINCT] expr) [FILTER (WHERE condition)]
+```
+
+#### 功能描述
+
+`BOOL_AND` 函数用于判断一组布尔值（`expr`）是否全部为 `TRUE`。当所有给定的布尔值都为 `TRUE` 时，函数返回 `TRUE`；否则，返回 `FALSE`。如果设置了 `DISTINCT` 关键字，函数将仅计算不重复的布尔值。
+
+#### 参数说明
+
+* `expr`：需要进行逻辑与操作的布尔表达式。
+
+#### 返回类型
+
+布尔值（`BOOLEAN`）。
+
+#### 使用示例
+
+1. 判断所有布尔值为 `TRUE`：
+
+```sql
+SELECT bool_and(col) FROM VALUES (TRUE), (TRUE), (TRUE) AS tab(col);
++---------------+
+| bool_and(col) |
++---------------+
+| TRUE          |
++---------------+
+```
+
+2. 包含 `NULL` 值的情况：
+
+```sql
+SELECT bool_and(col) FROM VALUES (TRUE), (TRUE), (NULL) AS tab(col);
++---------------+
+| bool_and(col) |
++---------------+
+| TRUE          |
++---------------+
+```
+
+3. 使用 `DISTINCT` 关键字，去重后判断所有布尔值为 `TRUE`：
+
+```sql
+SELECT bool_and(DISTINCT col) FROM VALUES (TRUE), (TRUE), (TRUE) AS tab(col);
++------------------------+
+| bool_and(DISTINCT col) |
++------------------------+
+| TRUE                   |
++------------------------+
+```
+
+4. 包含 `FALSE` 值的情况：
+
+```sql
+SELECT bool_and(col) FROM VALUES (FALSE), (TRUE), (NULL) AS tab(col);
++---------------+
+| bool_and(col) |
++---------------+
+| FALSE         |
++---------------+
+```
+
+5. 仅包含一个 `TRUE` 值和一个 `FALSE` 值：
+
+```sql
+SELECT bool_and(col) FROM VALUES (TRUE), (FALSE) AS tab(col);
++---------------+
+| bool_and(col) |
++---------------+
+| FALSE         |
++---------------+
+```
+
+6. 使用 FILTER 子句条件性地计算布尔与：
+
+```sql
+SELECT bool_and(col1) FILTER (WHERE col2 > 1) FROM VALUES (TRUE, 2), (TRUE, 3), (FALSE, 1) AS tab(col1, col2);
++----------------------------------------------+
+| bool_and(col1) FILTER (WHERE (col2 > 1))     |
++----------------------------------------------+
+| TRUE                                         |
++----------------------------------------------+
+```

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

@@ -0,0 +1,86 @@
+### BOOL_OR 函数
+
+```sql
+bool_or([DISTINCT] expr) [FILTER (WHERE condition)]
+```
+
+#### 功能描述
+
+`BOOL_OR` 函数用于判断一组布尔值中是否存在 `TRUE`。当输入的数据集中至少有一个 `TRUE` 时，函数返回 `TRUE`；如果所有值都是 `FALSE` 或 `NULL`，则返回 `FALSE`。若不设置 `DISTINCT` 参数，函数将计算所有值；设置 `DISTINCT` 后，将计算去重后的值。
+
+#### 参数说明
+
+* `expr` (`BOOLEAN` 类型): 需要进行逻辑或运算的布尔表达式。
+
+#### 返回类型
+
+* 返回值类型为 `BOOLEAN`。当存在至少一个 `TRUE` 值时，返回 `TRUE`；否则返回 `FALSE`。
+* 如果输入数据全部为 `NULL`，则返回 `NULL`。
+
+#### 使用示例
+
+1. 存在至少一个 `TRUE` 值时返回 `TRUE`：
+
+```sql
+SELECT bool_or(col) FROM VALUES (TRUE), (TRUE), (NULL) AS tab(col);
++--------------+
+| bool_or(col) |
++--------------+
+| true         |
++--------------+
+```
+
+2. 所有值都为 `FALSE` 或 `NULL` 时返回 `FALSE`：
+
+```sql
+SELECT bool_or(col) FROM VALUES (FALSE), (FALSE), (NULL) AS tab(col);
++--------------+
+| bool_or(col) |
++--------------+
+| false        |
++--------------+
+```
+
+3. 使用 `DISTINCT` 参数进行去重后计算：
+
+```sql
+SELECT bool_or(DISTINCT col) FROM VALUES (TRUE), (TRUE), (NULL) AS tab(col);
++-----------------------+
+| bool_or(DISTINCT col) |
++-----------------------+
+| true                  |
++-----------------------+
+```
+
+4. 多个 `FALSE` 值和 `NULL` 值的情况：
+
+```sql
+SELECT bool_or(col) FROM VALUES (FALSE), (NULL), (NULL) AS tab(col);
++--------------+
+| bool_or(col) |
++--------------+
+| false        |
++--------------+
+```
+
+5. 混合值的情况：
+
+```sql
+SELECT bool_or(col) FROM VALUES (TRUE), (FALSE), (NULL), (TRUE) AS tab(col);
++--------------+
+| bool_or(col) |
++--------------+
+| true         |
++--------------+
+```
+
+6. 使用 FILTER 子句条件性地计算布尔或：
+
+```sql
+SELECT bool_or(col1) FILTER (WHERE col2 > 1) FROM VALUES (FALSE, 2), (TRUE, 3), (FALSE, 1) AS tab(col1, col2);
++---------------------------------------------+
+| bool_or(col1) FILTER (WHERE (col2 > 1))     |
++---------------------------------------------+
+| true                                        |
++---------------------------------------------+
+```

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

@@ -0,0 +1,95 @@
+### 收集列表函数：collect_list
+
+```
+collect_list([DISTINCT] expr [, limit]) [FILTER (WHERE condition)]
+```
+
+#### 功能描述
+
+`collect_list` 函数用于从输入的一组数据中收集并返回一个数组。用户可以选择性地使用 `DISTINCT` 关键字来返回一个不包含重复元素的数组。
+
+#### 参数说明
+
+* `expr`：任意类型的表达式，用于从输入数据中收集元素。
+* `limit`：可选参数，整数类型，表示最多收集的元素个数。如果不指定，则收集所有元素。
+
+#### 返回结果
+
+* 返回一个数组，数组中的元素类型与输入参数类型相同。
+* 如果设置了 `DISTINCT` 关键字，则返回一个去重后的数组。
+* 如果指定了 `limit` 参数，则返回的数组最多包含 `limit` 个元素。
+* 函数不保证返回结果中元素的顺序。
+* 如果输入数据包含 `NULL` 值，则这些值不会被包含在返回的数组中。
+
+#### 使用示例
+
+1. 返回包含非重复元素的数组：
+```sql
+SELECT collect_list(DISTINCT col) FROM VALUES (1), (2), (1), (NULL) AS tab(col);
++----------------------------+
+| collect_list(DISTINCT col) |
++----------------------------+
+| [2,1]                      |
++----------------------------+
+```
+
+2. 返回包含重复元素的数组：
+```sql
+SELECT collect_list(col) FROM VALUES (1), (2), (1), (NULL) AS tab(col);
++-------------------+
+| collect_list(col) |
++-------------------+
+| [1,2,1]           |
++-------------------+
+```
+
+3. 从字符串数据中收集字符：
+```sql
+SELECT collect_list(col)
+FROM VALUES ("apple"), ("banana"), ("cherry"), (NULL) AS tab(col);
++-----------------------------+
+|      collect_list(col)      |
++-----------------------------+
+| ["apple","banana","cherry"] |
++-----------------------------+
+```
+
+4. 收集并返回包含 null 值的数组：
+```sql
+SELECT collect_list(col) FROM VALUES (true), (false), (null) AS tab(col);
++-------------------+
+| collect_list(col) |
++-------------------+
+| [true,false]      |
++-------------------+
+```
+
+5. 使用 FILTER 子句条件性地收集元素：
+```sql
+SELECT collect_list(col) FILTER (WHERE col > 1) FROM VALUES (1), (2), (3), (1) AS tab(col);
++--------------------------------------------+
+| collect_list(col) FILTER (WHERE (col > 1)) |
++--------------------------------------------+
+| [2,3]                                      |
++--------------------------------------------+
+```
+
+6. 结合 FILTER 子句和 DISTINCT 收集不重复的条件元素：
+```sql
+SELECT collect_list(DISTINCT col) FILTER (WHERE col <= 3) FROM VALUES (1), (2), (3), (3), (4) AS tab(col);
++-----------------------------------------------------------+
+| collect_list(DISTINCT col) FILTER (WHERE (col <= 3))      |
++-----------------------------------------------------------+
+| [3,2,1]                                                   |
++-----------------------------------------------------------+
+```
+
+7. 使用 limit 参数限制返回的元素个数：
+```sql
+SELECT collect_list(col, 2) FROM VALUES (1), (2), (3), (4) AS tab(col);
++----------------------+
+| collect_list(col, 2) |
++----------------------+
+| [1,2]                |
++----------------------+
+```

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

@@ -0,0 +1,64 @@
+### 收集列表到数组函数：COLLECT_LIST_ON_ARRAY
+
+```
+collect_list_on_array([DISTINCT] array [, limit])
+```
+
+#### 功能描述
+
+该函数用于将输入的数组（`ARRAY`）中的元素收集到一个新的数组中，并返回该新数组。如果指定了 `DISTINCT` 参数，则返回的结果数组中的元素是去重后的。
+
+#### 参数说明
+
+* `array`：输入的数组（`ARRAY`）类型数据。
+* `limit`：可选参数，整数类型，表示最多收集的元素个数。如果不指定，则收集所有元素。
+
+#### 返回结果
+
+* 返回一个数组（`ARRAY`）类型数据，其元素类型与输入数组的元素类型相同。
+* 如果指定了 `DISTINCT` 参数，则返回的结果数组中的元素是唯一的（即重复元素会被去重）。
+* 如果指定了 `limit` 参数，则返回的数组最多包含 `limit` 个元素。
+* 函数不保证返回结果数组的元素顺序。
+* 输入数组中的 `NULL` 值不会影响结果数组的计算。
+
+#### 使用示例
+
+以下示例展示了如何使用 `collect_list_on_array` 函数来收集数组中的元素并返回一个新数组。
+
+示例 1：基本使用
+
+```sql
+SELECT collect_list_on_array(a)
+FROM VALUES
+  (ARRAY(3, 3, 4)),
+  (NULL),
+  (ARRAY(2, 2, 3)),
+  (ARRAY(NULL)),
+  (ARRAY(1, NULL, 2)),
+  (ARRAY(1, 2, 2))
+AS t(a);
++--------------------------+
+| collect_list_on_array(a) |
++--------------------------+
+| [3,3,4,2,2,3,1,2,1,2,2]  |
++--------------------------+
+```
+
+示例 2：使用 limit 参数限制返回的元素个数
+
+```sql
+SELECT collect_list_on_array(a, 5)
+FROM VALUES
+  (ARRAY(3, 3, 4)),
+  (NULL),
+  (ARRAY(2, 2, 3)),
+  (ARRAY(NULL)),
+  (ARRAY(1, NULL, 2)),
+  (ARRAY(1, 2, 2))
+AS t(a);
++-----------------------------+
+| collect_list_on_array(a, 5) |
++-----------------------------+
+| [3,3,4,2,2]                 |
++-----------------------------+
+```