@clickzetta/cz-cli-darwin-x64 0.3.1

package/bin/skills/lakehouse-doc/references/sql_functions/scalar_functions/nested_functions/map_keys.md

@@ -0,0 +1,37 @@
+### MAP_KEYS 函数
+
+#### 概述
+`MAP_KEYS` 函数用于从输入的 map 类型数据中提取所有的 key 值，并以数组形式返回。
+
+#### 语法
+```
+MAP_KEYS(map)
+```
+
+#### 参数
+- **map**: 输入的 map 数据类型，其中 K 为 key 类型，V 为 value 类型。
+
+#### 返回值
+返回一个包含所有 key 值的数组，类型为 `array<K>`。
+
+#### 使用示例
+1. 从简单的键值对 map 中提取 key：
+   ```sql
+   SELECT MAP_KEYS(map("苹果", 2, "香蕉", 3, "橙子", 4));
+   -- 返回结果：["苹果", "香蕉", "橙子"]
+   ```
+2. 从嵌套的 map 中提取 key：
+   ```sql
+   SELECT MAP_KEYS(map(map("a", 1, "b", 2), map("c", 3, "d", 4)));
+   -- 返回结果：[{"a":1,"b":2}]
+   ```
+3. 从空 map 中提取 key：
+   ```sql
+   SELECT MAP_KEYS(map());
+   -- 返回结果：[]
+   ```
+
+#### 注意事项
+- 如果输入的 map 为空，`MAP_KEYS` 函数将返回一个空数组。
+- `MAP_KEYS` 函数不会改变原始 map 中 key 的顺序。
+

package/bin/skills/lakehouse-doc/references/sql_functions/scalar_functions/nested_functions/map_values.md

@@ -0,0 +1,46 @@
+### MAP_VALUES 函数
+
+#### 功能描述
+MAP_VALUES 函数用于从输入的键值对映射（map）中提取所有的值（value），并返回一个包含这些值的数组（array）。
+
+#### 语法
+```
+MAP_VALUES(map<K, V>)
+```
+
+#### 参数说明
+- map<K, V>：输入的键值对映射，其中 K 表示键（key）的类型，V 表示值（value）的类型。
+
+#### 返回类型
+该函数返回一个数组，数组中的元素类型与输入映射的值类型 V 相同。
+
+#### 使用示例
+
+**示例 1**：提取字符串键值对映射中的值
+```sql
+SELECT MAP_VALUES(map('苹果', 5, '香蕉', 3, '橘子', 8));
+```
+返回结果：
+```
+[5, 3, 8]
+```
+
+**示例 2**：提取包含复杂类型键值对映射中的值
+```sql
+SELECT MAP_VALUES(map('id', 101, 'name', '张三', 'age', 25));
+```
+返回结果：
+```
+[101, null, 25]
+```
+
+**示例 3**：从空映射中提取值
+```sql
+SELECT MAP_VALUES(map());
+```
+返回结果：
+```
+[]
+```
+
+

package/bin/skills/lakehouse-doc/references/sql_functions/scalar_functions/nested_functions/multimap_from_entries.md

@@ -0,0 +1,47 @@
+###  MULTIMAP_FROM_ENTRIES
+``` sql
+multimap_from_entries(array)
+```
+
+#### 功能
+从 array 中创建 multimap（一个键可以对应多个值的 map）， array 格式参考 map_entries 函数。
+与 map_from_entries 不同的是，当存在重复的键时，multimap_from_entries 会将所有对应的值聚合到一个数组中，而不是报错或覆盖。
+
+#### 参数
+* array: `array<struct<key:K, value:V>>`
+
+#### 返回结果
+`map<K, array<V>>`
+
+#### 举例
+```sql
+-- 基本用法：将重复键的值聚合到数组中
+> select multimap_from_entries(array(struct(1, 'a'), struct(2, 'b'), struct(1, 'c')));
+{1:["a","c"],2:["b"]}
+
+-- 所有键都唯一的情况
+> select multimap_from_entries(array(struct(1, 'a'), struct(2, 'b'), struct(3, 'c')));
+{1:["a"],2:["b"],3:["c"]}
+
+-- 所有键都相同的情况
+> select multimap_from_entries(array(struct(1, 'a'), struct(1, 'b'), struct(1, 'c')));
+{1:["a","b","c"]}
+
+-- 空数组
+> select multimap_from_entries(array());
+{}
+
+-- 包含 null 值
+> select multimap_from_entries(array(struct(1, 'a'), struct(2, null), struct(1, 'b')));
+{1:["a","b"],2:[null]}
+
+-- 使用字符串作为键
+> select multimap_from_entries(array(struct('x', 1), struct('y', 2), struct('x', 3)));
+{"x":[1,3],"y":[2]}
+```
+
+#### 注意事项
+* 键不能为 null，否则会抛出异常
+* 值可以为 null
+* 保持键的第一次出现顺序
+

package/bin/skills/lakehouse-doc/references/sql_functions/scalar_functions/nested_functions/named_struct.md

@@ -0,0 +1,55 @@
+### 命名结构体函数：named_struct
+
+#### 功能描述
+`named_struct` 函数用于创建一个具有指定字段名（field name）和对应字段值（field value）的结构体（struct）。该函数能够将多个字段及其值组合成一个整体，便于在查询结果中以结构化的形式展示数据。
+
+#### 语法格式
+```
+named_struct(f1, v1, f2, v2, ..., fN, vN)
+```
+
+#### 参数说明
+- `f1, f2, ..., fN`: 字段名，类型为字符串（string），表示结构体中各个字段的名称。
+- `v1, v2, ..., vN`: 字段值，类型为 `T1, T2, ..., TN`，表示结构体中各个字段对应的值。
+
+#### 返回类型
+- 返回一个结构体，包含 `f1:T1, f2:T2, ..., fN:TN` 等字段。
+
+#### 使用示例
+
+**示例 1：创建简单的命名结构体**
+```sql
+SELECT named_struct('id', 1, 'name', 'Alice');
+```
+返回结果：
+```
+{"id":1,"name":"Alice"}
+```
+
+**示例 2：结合其他函数创建复杂结构体**
+```sql
+SELECT named_struct('user', named_struct('id', 1, 'name', 'Alice'), 'created_time', '2022-01-01 10:00:00');
+```
+返回结果：
+```
+{"user":{"id":1,"name":"Alice"},"created_time":"2022-01-01 10:00:00"}
+```
+
+**示例 3：在查询中使用命名结构体**
+```sql
+SELECT id, named_struct('name', name, 'age', age) AS user_info
+FROM users;
+```
+假设 `users` 表包含 `id`, `name`, `age` 三个字段，返回结果：
+```
+id | user_info
+--- | ---------------------------------------------------------------------------------
+1  | {"name":"Alice","age":30}
+2  | {"name":"Bob","age":25}
+...
+```
+
+#### 注意事项
+- 请确保字段名 `f1, f2, ..., fN` 的值是有效的字符串，否则可能会导致函数执行失败。
+- 当字段名与已有的字段名冲突时，需要使用别名或其他方法来避免冲突。
+- 在使用 `named_struct` 函数时，请注意字段值的类型与结构体中字段类型的匹配，以确保数据的正确性。

package/bin/skills/lakehouse-doc/references/sql_functions/scalar_functions/nested_functions/sequence.md

@@ -0,0 +1,35 @@
+### SEQUENCE 函数
+
+#### 概述
+SEQUENCE 函数用于生成一个序列，该序列从起始值（start）开始，到结束值（stop）结束，并按照指定的步长（step）递增。生成的序列包含起始值和结束值。如果未提供步长参数，系统会根据起始值和结束值的大小关系自动选择默认步长。
+
+#### 功能
+- 当起始值小于结束值时，若未指定步长，默认步长为 1。
+- 当起始值大于结束值时，若未指定步长，默认步长为 -1。
+- 支持整数和时间类型的参数。
+
+#### 参数
+- start (tinyint/smallint/int/bigint): 序列的起始值。
+- stop (tinyint/smallint/int/bigint): 序列的结束值。
+- step (tinyint/smallint/int/bigint): 序列中相邻两个元素之间的差值（步长）。可选参数。若未指定，默认值为 1 或 -1，具体取决于起始值和结束值的大小关系。
+
+#### 返回结果
+返回一个与参数类型相同的数组。
+
+#### 使用示例
+1. 生成整数序列：
+   ```sql
+   SELECT sequence(-2, 2); -- 结果：[-2, -1, 0, 1, 2]
+   SELECT sequence(2, -2); -- 结果：[2, 1, 0, -1, -2]
+   SELECT sequence(-2, 2, 3); -- 结果：[-2, 1]
+   ```
+   
+2. 生成时间序列：
+   ```sql
+   SELECT sequence(timestamp '2020-10-10 00:00:00', timestamp '2020-10-15 00:00:00', interval '1 12:00:00' day to second);
+   -- 结果：[2020-10-10 00:00:00, 2020-10-11 12:00:00, 2020-10-13 00:00:00, 2020-10-14 12:00:00]
+   ```
+
+#### 注意事项
+- 当起始值和结束值相等时，无论步长为何值（只要不为 0），生成的序列都仅包含一个元素，即起始值本身。
+- 当步长为 0 时，SEQUENCE 函数将报错。

package/bin/skills/lakehouse-doc/references/sql_functions/scalar_functions/nested_functions/size.md

@@ -0,0 +1,34 @@
+### 函数名称：SIZE
+
+#### 功能描述
+1. `SIZE(array)` 函数用于计算并返回数组（array）中元素的数量。
+2. `SIZE(map)` 函数用于计算并返回映射（map）中键值对的数量。
+
+#### 语法
+```
+SIZE(array)
+SIZE(map)
+```
+
+#### 参数说明
+- `array`: 数组类型 `array<T>`，表示需要计算元素个数的数组。
+- `map`: 映射类型 `map<K, V>`，表示需要计算键值对个数的映射。
+
+#### 返回类型
+整数（int）
+
+#### 使用示例
+1. 计算数组中元素的数量：
+```
+SELECT SIZE(array(1, 2, 3)); -- 结果为：3
+```
+2. 计算映射中键值对的数量：
+```
+SELECT SIZE(map("a", 1, "b", 2)); -- 结果为：2
+```
+
+#### 注意事项
+- 当传入的参数不是数组或映射时，函数将返回错误。
+- 如果数组或映射为空，函数将返回 0。
+
+

package/bin/skills/lakehouse-doc/references/sql_functions/scalar_functions/nested_functions/slice.md

@@ -0,0 +1,43 @@
+### SLICE 函数
+
+#### 概述
+SLICE 函数用于从数组中提取一个子集。根据指定的起始位置（start）和所需元素数量（limit），函数将返回一个包含至多 limit 个元素的新数组。如果指定的起始位置为负数，则从数组末尾开始计算位置。
+
+#### 语法
+```
+slice(array, start, limit)
+```
+
+#### 参数
+- `array`: `array<T>` 类型，表示需要进行切片操作的数组。
+- `start`: int 类型，表示切片开始的位置。从 1 开始计数。如果 start 为负数，则从数组末尾开始计算。
+- `limit`: int 类型，表示需要提取的元素数量。
+
+#### 返回结果
+返回一个新的数组，包含从 start 位置开始的最多 limit 个元素。
+
+#### 使用示例
+
+1. 提取数组中的前两个元素：
+```
+SELECT slice(array(1, 2, 3, 4), 1, 2);
+```
+结果：
+```
+[1, 2]
+```
+
+2. 从数组的第三个元素开始提取一个元素：
+```
+SELECT slice(array(1, 2, 3, 4), 3, 1);
+```
+结果：
+```
+[3]
+```
+
+
+#### 注意事项
+- 如果 start 和 limit 的值超出数组范围，函数将返回一个空数组。
+
+

package/bin/skills/lakehouse-doc/references/sql_functions/scalar_functions/nested_functions/sort_array.md

@@ -0,0 +1,22 @@
+### SORT_ARRAY 函数
+
+#### 功能描述
+`SORT_ARRAY` 函数用于对数组元素进行排序。在排序过程中，`null` 值会被放置在数组的最前面。此函数在处理包含多种数据类型的数组时非常实用。
+
+#### 参数说明
+- `array`: `array<T>` 类型，表示需要排序的数组。
+- `asc`: 可选参数，布尔值，表示是否按照升序排列。默认值为 `true`，即默认进行升序排列。
+
+#### 返回类型
+- 返回一个排序后的数组，类型为 `array<T>`。
+
+#### 使用示例
+```sql
+-- 示例 1: 对整数数组进行升序排序
+SELECT sort_array(array(2, 1, 3)); -- 返回结果: [1, 2, 3]
+
+-- 示例 2: 对包含 null 值的数组进行升序排序
+SELECT sort_array(array(null, 4, 3, null, 5, 6)); -- 返回结果: [null, null, 3, 4, 5, 6]
+
+-- 示例 3: 对整数数组进行降序排序
+SELECT sort_array(array(2, 1, 3), false); -- 返回结果: [3, 2, 1]

package/bin/skills/lakehouse-doc/references/sql_functions/scalar_functions/nested_functions/struct.md

@@ -0,0 +1,35 @@
+### STRUCT 函数
+
+#### 功能描述
+`STRUCT` 函数用于创建一个结构化对象，该对象包含指定数量的字段（field），每个字段由其名称和对应的值组成。通过使用 `STRUCT` 函数，可以将多个不同类型的数据值组合成一个单一的数据结构，即结构化对象。
+
+#### 语法
+```
+STRUCT(v1, v2, ..., vN)
+```
+
+#### 参数
+- `v1`, `v2`, ..., `vN`: 任意数量的数据值，可以是不同的数据类型。
+
+#### 返回结果
+返回一个结构化对象，其中包含 N 个字段，字段名称默认为 `"col1"`, `"col2"`, ..., `"colN"`，字段值对应传入的参数 `v1`, `v2`, ..., `vN`。
+
+#### 使用示例
+1.  创建一个包含两个字段的结构化对象，字段名为 `"age"` 和 `"name"`，分别对应年龄和姓名：
+```sql
+SELECT STRUCT(25 , 'John Doe');
+```
+返回结果：
+```
+{"col1":25,"col2":"John Doe"}
+```
+
+2.  将不同类型的数据（整数、字符串、布尔值）组合成一个结构化对象：
+```sql
+SELECT STRUCT(42, 'Hello, world!', TRUE);
+```
+返回结果：
+```
+{"col1":42,"col2":"Hello, world!","col3":true}
+```
+

package/bin/skills/lakehouse-doc/references/sql_functions/scalar_functions/nested_functions/struct_insert.md

@@ -0,0 +1,54 @@
+### 函数名称
+`struct_insert`
+
+### 概述
+`struct_insert` 函数用于在结构体（struct）中插入一个新的字段。新字段的名称由 `name` 参数指定，其值为 `expr` 参数指定。可选的 `indexToInsert` 参数用于指定插入位置。如果未指定 `indexToInsert` 或其值为 0，则新字段将插入到结构体的末尾。如果 `indexToInsert` 为 1，则新字段将插入到第一个字段之后，以此类推。
+
+### 功能
+- 向结构体中添加新的字段。
+- 通过 `indexToInsert` 参数控制新字段的插入位置。
+
+### 参数
+- `struct`: 需要插入新字段的结构体。
+- `name`: 新字段的名称，必须为字符串常量。
+- `expr`: 新字段的值，可以是任意类型的数据。
+- `indexToInsert`: （可选）指定新字段的插入位置，为整数常量，默认值为 0。
+
+### 返回结果
+返回一个新的结构体，其结构取决于插入的键值对和指定的插入位置。
+
+### 使用示例
+1. 向结构体末尾添加新字段：
+   ```sql
+   SELECT struct_insert(named_struct('a', 1, 'b', 2), 'x', 'hello');
+   -- 结果：{"a":1, "b": 2, "x":"hello"}
+   ```
+
+2. 向结构体头部插入新字段：
+   ```sql
+   SELECT struct_insert(named_struct('a', 1, 'b', 2), 'x', 'hello', 0);
+   -- 结果：{"x":"hello", "a":1, "b": 2}
+   ```
+
+3. 在第一个字段之后插入新字段：
+   ```sql
+   SELECT struct_insert(named_struct('a', 1, 'b', 2), 'x', 'hello', 1);
+   -- 结果：{"a":1, "x":"hello", "b": 2}
+   ```
+
+4. 在第二个字段之前插入新字段：
+   ```sql
+   SELECT struct_insert(named_struct('a', 1, 'b', 2), 'y', 3, 2);
+   -- 结果：{"a":1, "y":3, "b": 2, "x": "hello"}
+   ```
+
+5. 向包含嵌套结构体的结构体中插入新字段：
+   ```sql
+   SELECT struct_insert(named_struct('outer', named_struct('inner', 'value')), 'newField', 'newValue');
+   -- 结果：{"outer":{"inner":{"value"},"newField":"newValue"}}
+   ```
+
+### 注意事项
+- 请确保 `name` 参数为字符串常量，否则可能导致函数执行失败。
+- `indexToInsert` 参数的有效范围为 0 到结构体字段数量（包含）。超出此范围的值将导致函数执行失败。
+- 当插入位置与现有字段冲突时（例如，尝试在已存在的字段位置插入新字段），函数将返回错误。

package/bin/skills/lakehouse-doc/references/sql_functions/scalar_functions/nested_functions/struct_update.md

@@ -0,0 +1,42 @@
+### STRUCT_UPDATE 函数
+
+#### 功能描述
+`STRUCT_UPDATE` 函数用于更新一个结构体（struct）中的指定字段（field），将给定字段名对应的值替换为新的表达式值（expr）。需要注意的是，新值的类型可以与原值不同。
+
+#### 参数说明
+* `struct`: 需要更新的结构体（struct）。
+* `name`: 待更新字段的名称，必须为字符串常量。
+* `expr`: 用于替换原字段值的新表达式，可以是任意类型。
+
+#### 返回结果
+返回一个新的结构体（struct），其结构与原结构体相同，但已更新指定字段的值。
+
+#### 使用示例
+1. 假设我们有一个结构体 `s1`，包含两个字段：`"a"` 的值为 1，`"b"` 的值为 2。我们可以使用 `STRUCT_UPDATE` 函数将字段 `"a"` 的值更新为字符串 `"hello"`：
+```sql
+SELECT STRUCT_UPDATE(named_struct('a', 1, 'b', 2), 'a', 'hello');
+```
+执行结果为：
+```json
+{"a":"hello", "b":2}
+```
+
+2. 同样，我们也可以将字段 `"b"` 的值更新为字符串 `"hello"`：
+```sql
+SELECT STRUCT_UPDATE(named_struct('a', 1, 'b', 2), 'b', 'hello');
+```
+执行结果为：
+```json
+{"a":1, "b":"hello"}
+```
+
+3. 除了字符串，我们还可以使用其他类型的表达式来更新字段值，例如将字段 `"a"` 的值更新为当前时间戳：
+```sql
+SELECT STRUCT_UPDATE(named_struct('a', 1, 'b', 2), 'a', TIMESTAMP "2023-04-01 12:00:00");
+```
+执行结果为：
+```json
+{"a":2023-04-01 12:00:00, "b":2}
+```
+
+通过以上示例，您可以看到 `STRUCT_UPDATE` 函数在更新结构体字段时非常灵活且易于使用。

package/bin/skills/lakehouse-doc/references/sql_functions/scalar_functions/nested_functions/trans_array.md

@@ -0,0 +1,147 @@
+# TRANS\_ARRAY 函数
+
+## 函数描述
+
+`TRANS_ARRAY` 是一个用户自定义表值函数（UDTF），用于将一行数据转换为多行数据。它将列中存储的以固定分隔符格式分隔的数组转换为多行，实现"行转列"的数据变换。该函数特别适合处理那些将多个值存储在单个字符串字段中的数据结构。
+
+### 核心特性
+
+* **行转列转换**：将单行中用分隔符分隔的多个值拆分为多行
+* **灵活的 Key 列**：支持指定一个或多个列作为 Key，这些列不参与拆分
+* **自动补全**：当数组长度不相等时，自动用 NULL 填充较短的数组
+* **分隔符可配置**：支持任意字符串作为分隔符
+
+## 语法
+
+```sql
+trans_array(<num_keys>, <separator>, <key1>, <key2>, ..., <col1>, <col2>, <col3>)AS (<key1>, <key2>, ..., <col1>, <col2>)
+```
+
+## 参数说明
+
+| 参数              | 类型     | 必填 | 说明                                                              |
+| ----------------- | -------- | ---- | --------------------------------------------------------------- |
+| num\_keys         | BIGINT   | 是   | 转置时作为 Key 的列的个数。必须为常量，值必须 ≥ 0。Key 列必须位于所有待转置列之前。                 |
+| separator         | STRING   | 是   | 用于将字符串拆分成多个元素的分隔符。必须为常量，不能为空字符串，否则返回错误。                          |
+| key1, key2, ...   | 任意类型 | 是   | 转置时作为 Key 的列，个数由 num\_keys 指定。Key 列在结果中保持原有数据类型。                 |
+| col1, col2, ...   | STRING   | 是   | 要转为行的数组列。这些列必须为 STRING 类型，存储的内容是字符串格式的数组，例如 `item1;item2;item3`。 |
+
+### 特殊说明
+
+* **Key 列的作用**：Key 列用于分组和标识，拆分过程中 Key 列的值保持不变
+
+* **转置列要求**：Key 之后的所有列都视为待转置的数组列，必须为 STRING 类型
+
+* **输出行数**：以长度最长的数组为准，其他较短数组不足的位置用 NULL 填充。
+
+* **输出类型**：Key 列保持原有类型，其余所有列为 STRING 类型
+
+
+## 返回值
+
+返回转置后的多行数据，其中：
+
+* Key 列的数据类型保持不变
+* 转置后的列全部为 STRING 类型
+* 新的列名由 AS 子句指定
+
+## 使用示例
+
+**示例 1：单 Key 的基础转置**
+
+场景描述：用户登录表中，每个用户有多条登录 IP 和时间信息，存储为用分隔符分隔的字符串。需要将其拆分为多行以便于分析。
+
+原始数据表：`test_user_login`
+
+```
+CREATE TABLE test_user_login ( login_id STRING, login_ip STRING, login_time STRING);
+INSERT INTO test_user_login VALUES('wangwangA', '192.168.0.1,192.168.0.2', '20120101010000,20120102010000'),('wangwangB', '192.168.45.10,192.168.67.22,192.168.6.3', '20120111010000,20120112010000,20120223080000');
+```
+
+SQL 语句：
+
+```sql
+SELECT  trans_array(1, ',', login_id, login_ip, login_time)  AS (login_id, login_ip, login_time)FROM test_user_login;
+```
+
+执行结果：
+
+| login\_id | login\_ip     | login\_time    |
+| --------- | ------------- | -------------- |
+| wangwangA | 192.168.0.1   | 20120101010000 |
+| wangwangA | 192.168.0.2   | 20120102010000 |
+| wangwangB | 192.168.45.10 | 20120111010000 |
+| wangwangB | 192.168.67.22 | 20120112010000 |
+| wangwangB | 192.168.6.3   | 20120223080000 |
+
+结果说明：
+
+* `num_keys=1` 表示只有 `login_id` 列作为 Key。
+* `separator=','` 指定逗号作为分隔符。
+* 每个用户的登录记录被拆分为单独的行。
+* `login_id` 保持不变，作为分组标识。
+
+**示例 2：多 Key 的转置**
+
+场景描述：用户信息表中包含用户 ID、姓名以及多条登录 IP 和时间记录。现需使用两个 Key 列进行转置。
+
+原始数据表：`test_user_info`
+
+```
+CREATE TABLE test_user_info ( id INT, name STRING, login\_ip STRING, login\_time STRING);
+INSERT INTO test_user_info VALUES(1, 'Tom', '192.168.100.1,192.168.100.2', '20211101010101,20211101010102'),(2, 'Jerry', '192.168.100.3,192.168.100.4', '20211101010103,20211101010104');
+```
+
+SQL 语句：
+
+```sql
+SELECT  trans_array(2, ',', id, name, login_ip, login_time)  AS (id, name, login_ip, login_time)FROM test_user_info;
+```
+
+执行结果：
+
+| id | name  | login\_ip     | login\_time    |
+| -- | ----- | ------------- | -------------- |
+| 1  | Tom   | 192.168.100.1 | 20211101010101 |
+| 1  | Tom   | 192.168.100.2 | 20211101010102 |
+| 2  | Jerry | 192.168.100.3 | 20211101010103 |
+| 2  | Jerry | 192.168.100.4 | 20211101010104 |
+
+结果说明：
+
+* `num_keys=2` 表示将 `id` 和 `name` 两列作为 Key。
+* 两个 Key 列在结果中保持不变。
+* 登录记录根据 Key 列的值保持分组关系。
+
+**示例 3：不等长数组处理（自动补 NULL）**
+
+场景描述：用户兴趣表中，不同用户拥有不同数量的爱好和运动项目。本示例展示如何处理数组长度不相等的情况。
+
+原始数据表：`test_unequal_array`
+
+```
+CREATE TABLE test_unequal_array ( user_id STRING, hobbies STRING, sports STRING);
+INSERT INTO test_unequal_array VALUES('user1', 'reading,coding', 'basketball,tennis,swimming');
+
+```
+
+SQL 语句：
+
+```sql
+SELECT  trans_array(1, ',', user_id, hobbies, sports)  AS (user_id, hobbies, sports)FROM test_unequal_array;
+```
+
+执行结果：
+
+| user\_id | hobbies | sports     |
+| -------- | ------- | ---------- |
+| user1    | reading | basketball |
+| user1    | coding  | tennis     |
+| user1    | NULL    | swimming   |
+
+结果说明：
+
+* `hobbies` 列有 2 个元素，`sports` 列有 3 个元素。
+* 输出行数以较长数组（3 行）为准。
+* `hobbies` 列的第三行用 NULL 填充。
+* 这种自动补全机制避免了数据丢失。

package/bin/skills/lakehouse-doc/references/sql_functions/scalar_functions/partition/max_pt.md

@@ -0,0 +1,41 @@
+## 功能概述
+
+`MAX_PT` 用于获取分区表中最大分区的值。该函数特别适用于处理分区表，可以帮助用户快速定位到最新的数据分区。
+
+## 命令格式
+
+```SQL
+max_pt('schema_name.table_name'｜ 'table_name')
+```
+
+## 参数说明
+
+* **schema\_name.table\_name**: 这是一个必填参数，类型为 STRING。支持 `schema_name.table_name` 或 `table_name` 形式。如果不指定 schema，则默认使用当前上下文环境。
+
+## 返回值说明
+
+* 该函数返回最大的一级分区的值。
+
+## 示例
+
+示例 1：基本使用
+
+假设 `tbl` 是一个分区表，其对应的分区为 `20120901` 和 `20120902`，并且这两个分区中都有数据。以下语句中，`max_pt` 返回的值为 `'20120902'`。
+
+```SQL
+SELECT * FROM tbl WHERE pt = max_pt('tbl');
+```
+
+等效于以下语句：
+
+```SQL
+SELECT * FROM tbl WHERE pt = (SELECT MAX(pt) FROM tbl);
+```
+
+示例 2：多级分区场景
+
+在多级分区的场景中，可以使用标准 SQL 获取最大分区下的数据。
+
+```SQL
+SELECT * FROM table WHERE pt1 = (SELECT MAX(pt1) FROM table) AND pt2 = (SELECT MAX(pt2) FROM table WHERE pt1 = (SELECT MAX(pt1) FROM table));
+```