This is an automated email from the ASF dual-hosted git repository.
zclll pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/doris-website.git
The following commit(s) were added to refs/heads/master by this push:
new e43db45a76e [doc](function) add a doc for array_sort(lambda functor
version) (#3070)
e43db45a76e is described below
commit e43db45a76ee47680a0782c694127b7cd08bfad5
Author: admiring_xm <[email protected]>
AuthorDate: Thu Nov 27 20:53:01 2025 +0800
[doc](function) add a doc for array_sort(lambda functor version) (#3070)
## Versions
- [x] dev
- [x] 4.x
- [ ] 3.x
- [ ] 2.1
## Languages
- [x] Chinese
- [x] English
## Docs Checklist
- [ ] Checked by AI
- [ ] Test Cases Built
---
.../scalar-functions/array-functions/array-sort.md | 167 +++++++++++++++++++--
.../scalar-functions/array-functions/array-sort.md | 160 ++++++++++++++++++--
.../scalar-functions/array-functions/array-sort.md | 160 ++++++++++++++++++--
.../scalar-functions/array-functions/array-sort.md | 167 +++++++++++++++++++--
4 files changed, 606 insertions(+), 48 deletions(-)
diff --git
a/docs/sql-manual/sql-functions/scalar-functions/array-functions/array-sort.md
b/docs/sql-manual/sql-functions/scalar-functions/array-functions/array-sort.md
index 2214ed035ff..cf7112e69a8 100644
---
a/docs/sql-manual/sql-functions/scalar-functions/array-functions/array-sort.md
+++
b/docs/sql-manual/sql-functions/scalar-functions/array-functions/array-sort.md
@@ -7,34 +7,173 @@
## Function
-Sort array elements in ascending order.
+If no lambda function is specified, the array elements are sorted in ascending
order. Otherwise, sorting is performed according to the lambda function.
## Syntax
- `ARRAY_SORT(arr)`
+- `ARRAY_SORT(lambda, arr)`
## Parameters
+- `lambda`: A `lambda` expression used to define sorting rules, whose return
value should be -1, 0, or 1 (representing less than, less than or equal to, and
greater than respectively).
- `arr`: `ARRAY<T>`, where `T` can be numeric, boolean, string, datetime, IP,
etc.
## Return value
-- Returns `ARRAY<T>` of the same type as the input.
-- `NULL` elements are placed at the beginning of the returned array.
+- If it does not contain a `lambda` expression
+ - Returns `ARRAY<T>` of the same type as the input.
+ - `NULL` elements are placed at the beginning of the returned array.
+- If it contains a `lambda` expression, sort according to the lambda
expression and return an `ARRAY<T>` of the same type as the input.
## Usage notes
-- If the input is `NULL`, returns `NULL`; if the input is an empty array `[]`,
returns an empty array.
-- `ARRAY_SORT` sorts in ascending order, while `ARRAY_REVERSE_SORT` sorts in
descending order.
+- If it does not contain a `lambda` expression
+ - If the input is `NULL`, returns `NULL`; if the input is an empty array
`[]`, returns an empty array.
+ - `ARRAY_SORT` sorts in ascending order, while `ARRAY_REVERSE_SORT` sorts in
descending order.
+- If containing a `lambda` expression
+ - The value of the `lambda` expression shall be -1, 0, or 1. Should a `NULL`
value exist, it shall be explicitly stated whether the `NULL` value is to be
placed before or after the array.
## Examples
-- Basic: `NULL` elements are placed at the beginning of the returned array
- - `ARRAY_SORT([2,1,3,null])` -> `[null, 1, 2, 3]`
-
-- If the input is `NULL`, returns `NULL`; if the input is an empty array `[]`,
returns an empty array.
- - `ARRAY_SORT(NULL)` -> `NULL`
- - `ARRAY_SORT([])` -> `[]`
-
-
-
+1. Basic: `NULL` elements are placed at the beginning of the returned array
+
+```sql
+SELECT ARRAY_SORT([2,1,3,null]);
+```
+
+```text
++--------------------------+
+| ARRAY_SORT([2,1,3,null]) |
++--------------------------+
+| [null, 1, 2, 3] |
++--------------------------+
+```
+
+2. If the input is `NULL`, returns `NULL`; if the input is an empty array
`[]`, returns an empty array.
+
+```sql
+SELECT ARRAY_SORT(NULL);
+```
+
+```text
++------------------+
+| ARRAY_SORT(NULL) |
++------------------+
+| NULL |
++------------------+
+```
+
+```sql
+SELECT ARRAY_SORT([]);
+```
+
+```text
++----------------+
+| ARRAY_SORT([]) |
++----------------+
+| [] |
++----------------+
+```
+
+3. Use `lambda` expressions
+
+```sql
+SELECT array_sort((x, y) -> IF(x < y, 1, IF(x = y, 0, -1)), [3, 2, 5, 1, 2]);
+```
+
+```text
++-----------------------------------------------------------------------+
+| array_sort((x, y) -> IF(x < y, 1, IF(x = y, 0, -1)), [3, 2, 5, 1, 2]) |
++-----------------------------------------------------------------------+
+| [5, 3, 2, 2, 1] |
++-----------------------------------------------------------------------+
+```
+
+```sql
+SELECT array_sort((x, y) -> IF(x < y, 1, IF(x = y, 0, -1)), ['bc', 'ab',
'dc']);
+```
+
+```text
++--------------------------------------------------------------------------+
+| array_sort((x, y) -> IF(x < y, 1, IF(x = y, 0, -1)), ['bc', 'ab', 'dc']) |
++--------------------------------------------------------------------------+
+| ["dc", "bc", "ab"] |
++--------------------------------------------------------------------------+
+```
+
+```sql
+SELECT array_sort((x, y) -> CASE WHEN x IS NULL THEN -1
+ WHEN y IS NULL THEN 1
+ WHEN x < y THEN 1
+ WHEN x = y THEN 0
+ ELSE -1 END,
+ [3, 2, null, 5, null, 1, 2]);
+```
+
+```text
++------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| array_sort((x, y) -> CASE WHEN x IS NULL THEN -1
+ WHEN y IS NULL THEN 1
+ WHEN x < y THEN 1
+ WHEN x = y THEN 0
+ ELSE -1 END,
+ [3, 2, null, 5, null, 1, 2]) |
++------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| [null, null, 5, 3, 2, 2, 1]
|
++------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+```
+
+```sql
+SELECT array_sort((x, y) -> CASE WHEN x IS NULL THEN 1
+ WHEN y IS NULL THEN -1
+ WHEN x < y THEN 1
+ WHEN x = y THEN 0
+ ELSE -1 END,
+ [3, 2, null, 5, null, 1, 2]);
+```
+
+```text
++------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| array_sort((x, y) -> CASE WHEN x IS NULL THEN 1
+ WHEN y IS NULL THEN -1
+ WHEN x < y THEN 1
+ WHEN x = y THEN 0
+ ELSE -1 END,
+ [3, 2, null, 5, null, 1, 2]) |
++------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| [5, 3, 2, 2, 1, null, null]
|
++------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+```
+
+```sql
+SELECT array_sort((x, y) -> IF(length(x) < length(y), -1,
+ IF(length(x) = length(y), 0, 1)),
+ ['a', 'abcd', 'abc']);
+```
+
+```text
++--------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| array_sort((x, y) -> IF(length(x) < length(y), -1,
+ IF(length(x) = length(y), 0, 1)),
+ ['a', 'abcd', 'abc']) |
++--------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ["a", "abc", "abcd"]
|
++--------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+```
+
+```sql
+SELECT array_sort((x, y) -> IF(cardinality(x) < cardinality(y), -1,
+ IF(cardinality(x) = cardinality(y), 0, 1)),
+ [[2, 3, 1], [4, 2, 1, 4], [1, 2]]);
+```
+
+```text
++-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| array_sort((x, y) -> IF(cardinality(x) < cardinality(y), -1,
+ IF(cardinality(x) = cardinality(y), 0, 1)),
+ [[2, 3, 1], [4, 2, 1, 4], [1, 2]]) |
++-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| [[1, 2], [2, 3, 1], [4, 2, 1, 4]]
|
++-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+```
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/array-functions/array-sort.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/array-functions/array-sort.md
index 5785c8e2643..c68befcfcd4 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/array-functions/array-sort.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/array-functions/array-sort.md
@@ -7,33 +7,173 @@
## 功能
-对数组元素按升序排序。
+若不指定lambda函数，则对数组元素按升序排序。否则按照lambda函数进行排序。
## 语法
- `ARRAY_SORT(arr)`
+- `ARRAY_SORT(lambda, arr)`
## 参数
+- `lambda`: `lambda` 表达式，用于定义排序规则，返回值应为-1， 0， 1（分别表示小于，等于，大于）。
- `arr`：`ARRAY<T>`，`T` 可为数值、布尔、字符串、日期时间、IP 等。
## 返回值
-- 返回与输入同类型的 `ARRAY<T>`。
-- `NULL` 元素放在返回的数组最前面。
+- 若不包含`lambda`表达式
+ - 返回与输入同类型的 `ARRAY<T>`。
+ - `NULL` 元素放在返回的数组最前面。
+- 若包含`lambda`表达式，按照lambda表达式进行排序，返回与输入同类型的 `ARRAY<T>`。
## 使用说明
-- 若输入为 `NULL`，返回 `NULL`; 若输入为空数组 `[]`，返回空数组。
-- `ARRAY_SORT` 是升序排序，`ARRAY_REVERSE_SORT` 是降序排序。
+- 若不包含`lambda`表达式
+ - 若输入为 `NULL`，返回 `NULL`; 若输入为空数组 `[]`，返回空数组。
+ - `ARRAY_SORT` 是升序排序，`ARRAY_REVERSE_SORT` 是降序排序。
+- 若包含`lambda`表达式
+ - `lambda`表达式的值应为-1，0，1，若存在`NULL`值，应明确说明`NULL`值应排在数组前还是数组后。
## 示例
-- 基本: `NULL` 元素放在返回的数组最前面
- - `ARRAY_SORT([2,1,3,null])` -> `[null, 1, 2, 3]`
+1. 基本: `NULL` 元素放在返回的数组最前面
-- 输入为 `NULL`，返回 `NULL`; 输入为空数组 `[]`，返回空数组。
- - `ARRAY_SORT(NULL)` -> `NULL`
- - `ARRAY_SORT([])` -> `[]`
+```sql
+SELECT ARRAY_SORT([2,1,3,null]);
+```
+```text
++--------------------------+
+| ARRAY_SORT([2,1,3,null]) |
++--------------------------+
+| [null, 1, 2, 3] |
++--------------------------+
+```
+2. 输入为 `NULL`，返回 `NULL`; 输入为空数组 `[]`，返回空数组。
+
+```sql
+SELECT ARRAY_SORT(NULL);
+```
+
+```text
++------------------+
+| ARRAY_SORT(NULL) |
++------------------+
+| NULL |
++------------------+
+```
+
+```sql
+SELECT ARRAY_SORT([]);
+```
+
+```text
++----------------+
+| ARRAY_SORT([]) |
++----------------+
+| [] |
++----------------+
+```
+
+3. 使用`lambda`表达式
+
+```sql
+SELECT array_sort((x, y) -> IF(x < y, 1, IF(x = y, 0, -1)), [3, 2, 5, 1, 2]);
+```
+
+```text
++-----------------------------------------------------------------------+
+| array_sort((x, y) -> IF(x < y, 1, IF(x = y, 0, -1)), [3, 2, 5, 1, 2]) |
++-----------------------------------------------------------------------+
+| [5, 3, 2, 2, 1] |
++-----------------------------------------------------------------------+
+```
+
+```sql
+SELECT array_sort((x, y) -> IF(x < y, 1, IF(x = y, 0, -1)), ['bc', 'ab',
'dc']);
+```
+
+```text
++--------------------------------------------------------------------------+
+| array_sort((x, y) -> IF(x < y, 1, IF(x = y, 0, -1)), ['bc', 'ab', 'dc']) |
++--------------------------------------------------------------------------+
+| ["dc", "bc", "ab"] |
++--------------------------------------------------------------------------+
+```
+
+```sql
+SELECT array_sort((x, y) -> CASE WHEN x IS NULL THEN -1
+ WHEN y IS NULL THEN 1
+ WHEN x < y THEN 1
+ WHEN x = y THEN 0
+ ELSE -1 END,
+ [3, 2, null, 5, null, 1, 2]);
+```
+
+```text
++------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| array_sort((x, y) -> CASE WHEN x IS NULL THEN -1
+ WHEN y IS NULL THEN 1
+ WHEN x < y THEN 1
+ WHEN x = y THEN 0
+ ELSE -1 END,
+ [3, 2, null, 5, null, 1, 2]) |
++------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| [null, null, 5, 3, 2, 2, 1]
|
++------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+```
+
+```sql
+SELECT array_sort((x, y) -> CASE WHEN x IS NULL THEN 1
+ WHEN y IS NULL THEN -1
+ WHEN x < y THEN 1
+ WHEN x = y THEN 0
+ ELSE -1 END,
+ [3, 2, null, 5, null, 1, 2]);
+```
+
+```text
++------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| array_sort((x, y) -> CASE WHEN x IS NULL THEN 1
+ WHEN y IS NULL THEN -1
+ WHEN x < y THEN 1
+ WHEN x = y THEN 0
+ ELSE -1 END,
+ [3, 2, null, 5, null, 1, 2]) |
++------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| [5, 3, 2, 2, 1, null, null]
|
++------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+```
+
+```sql
+SELECT array_sort((x, y) -> IF(length(x) < length(y), -1,
+ IF(length(x) = length(y), 0, 1)),
+ ['a', 'abcd', 'abc']);
+```
+
+```text
++--------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| array_sort((x, y) -> IF(length(x) < length(y), -1,
+ IF(length(x) = length(y), 0, 1)),
+ ['a', 'abcd', 'abc']) |
++--------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ["a", "abc", "abcd"]
|
++--------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+```
+
+```sql
+SELECT array_sort((x, y) -> IF(cardinality(x) < cardinality(y), -1,
+ IF(cardinality(x) = cardinality(y), 0, 1)),
+ [[2, 3, 1], [4, 2, 1, 4], [1, 2]]);
+```
+
+```text
++-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| array_sort((x, y) -> IF(cardinality(x) < cardinality(y), -1,
+ IF(cardinality(x) = cardinality(y), 0, 1)),
+ [[2, 3, 1], [4, 2, 1, 4], [1, 2]]) |
++-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| [[1, 2], [2, 3, 1], [4, 2, 1, 4]]
|
++-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+```
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/array-functions/array-sort.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/array-functions/array-sort.md
index 5785c8e2643..c68befcfcd4 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/array-functions/array-sort.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/array-functions/array-sort.md
@@ -7,33 +7,173 @@
## 功能
-对数组元素按升序排序。
+若不指定lambda函数，则对数组元素按升序排序。否则按照lambda函数进行排序。
## 语法
- `ARRAY_SORT(arr)`
+- `ARRAY_SORT(lambda, arr)`
## 参数
+- `lambda`: `lambda` 表达式，用于定义排序规则，返回值应为-1， 0， 1（分别表示小于，等于，大于）。
- `arr`：`ARRAY<T>`，`T` 可为数值、布尔、字符串、日期时间、IP 等。
## 返回值
-- 返回与输入同类型的 `ARRAY<T>`。
-- `NULL` 元素放在返回的数组最前面。
+- 若不包含`lambda`表达式
+ - 返回与输入同类型的 `ARRAY<T>`。
+ - `NULL` 元素放在返回的数组最前面。
+- 若包含`lambda`表达式，按照lambda表达式进行排序，返回与输入同类型的 `ARRAY<T>`。
## 使用说明
-- 若输入为 `NULL`，返回 `NULL`; 若输入为空数组 `[]`，返回空数组。
-- `ARRAY_SORT` 是升序排序，`ARRAY_REVERSE_SORT` 是降序排序。
+- 若不包含`lambda`表达式
+ - 若输入为 `NULL`，返回 `NULL`; 若输入为空数组 `[]`，返回空数组。
+ - `ARRAY_SORT` 是升序排序，`ARRAY_REVERSE_SORT` 是降序排序。
+- 若包含`lambda`表达式
+ - `lambda`表达式的值应为-1，0，1，若存在`NULL`值，应明确说明`NULL`值应排在数组前还是数组后。
## 示例
-- 基本: `NULL` 元素放在返回的数组最前面
- - `ARRAY_SORT([2,1,3,null])` -> `[null, 1, 2, 3]`
+1. 基本: `NULL` 元素放在返回的数组最前面
-- 输入为 `NULL`，返回 `NULL`; 输入为空数组 `[]`，返回空数组。
- - `ARRAY_SORT(NULL)` -> `NULL`
- - `ARRAY_SORT([])` -> `[]`
+```sql
+SELECT ARRAY_SORT([2,1,3,null]);
+```
+```text
++--------------------------+
+| ARRAY_SORT([2,1,3,null]) |
++--------------------------+
+| [null, 1, 2, 3] |
++--------------------------+
+```
+2. 输入为 `NULL`，返回 `NULL`; 输入为空数组 `[]`，返回空数组。
+
+```sql
+SELECT ARRAY_SORT(NULL);
+```
+
+```text
++------------------+
+| ARRAY_SORT(NULL) |
++------------------+
+| NULL |
++------------------+
+```
+
+```sql
+SELECT ARRAY_SORT([]);
+```
+
+```text
++----------------+
+| ARRAY_SORT([]) |
++----------------+
+| [] |
++----------------+
+```
+
+3. 使用`lambda`表达式
+
+```sql
+SELECT array_sort((x, y) -> IF(x < y, 1, IF(x = y, 0, -1)), [3, 2, 5, 1, 2]);
+```
+
+```text
++-----------------------------------------------------------------------+
+| array_sort((x, y) -> IF(x < y, 1, IF(x = y, 0, -1)), [3, 2, 5, 1, 2]) |
++-----------------------------------------------------------------------+
+| [5, 3, 2, 2, 1] |
++-----------------------------------------------------------------------+
+```
+
+```sql
+SELECT array_sort((x, y) -> IF(x < y, 1, IF(x = y, 0, -1)), ['bc', 'ab',
'dc']);
+```
+
+```text
++--------------------------------------------------------------------------+
+| array_sort((x, y) -> IF(x < y, 1, IF(x = y, 0, -1)), ['bc', 'ab', 'dc']) |
++--------------------------------------------------------------------------+
+| ["dc", "bc", "ab"] |
++--------------------------------------------------------------------------+
+```
+
+```sql
+SELECT array_sort((x, y) -> CASE WHEN x IS NULL THEN -1
+ WHEN y IS NULL THEN 1
+ WHEN x < y THEN 1
+ WHEN x = y THEN 0
+ ELSE -1 END,
+ [3, 2, null, 5, null, 1, 2]);
+```
+
+```text
++------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| array_sort((x, y) -> CASE WHEN x IS NULL THEN -1
+ WHEN y IS NULL THEN 1
+ WHEN x < y THEN 1
+ WHEN x = y THEN 0
+ ELSE -1 END,
+ [3, 2, null, 5, null, 1, 2]) |
++------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| [null, null, 5, 3, 2, 2, 1]
|
++------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+```
+
+```sql
+SELECT array_sort((x, y) -> CASE WHEN x IS NULL THEN 1
+ WHEN y IS NULL THEN -1
+ WHEN x < y THEN 1
+ WHEN x = y THEN 0
+ ELSE -1 END,
+ [3, 2, null, 5, null, 1, 2]);
+```
+
+```text
++------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| array_sort((x, y) -> CASE WHEN x IS NULL THEN 1
+ WHEN y IS NULL THEN -1
+ WHEN x < y THEN 1
+ WHEN x = y THEN 0
+ ELSE -1 END,
+ [3, 2, null, 5, null, 1, 2]) |
++------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| [5, 3, 2, 2, 1, null, null]
|
++------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+```
+
+```sql
+SELECT array_sort((x, y) -> IF(length(x) < length(y), -1,
+ IF(length(x) = length(y), 0, 1)),
+ ['a', 'abcd', 'abc']);
+```
+
+```text
++--------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| array_sort((x, y) -> IF(length(x) < length(y), -1,
+ IF(length(x) = length(y), 0, 1)),
+ ['a', 'abcd', 'abc']) |
++--------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ["a", "abc", "abcd"]
|
++--------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+```
+
+```sql
+SELECT array_sort((x, y) -> IF(cardinality(x) < cardinality(y), -1,
+ IF(cardinality(x) = cardinality(y), 0, 1)),
+ [[2, 3, 1], [4, 2, 1, 4], [1, 2]]);
+```
+
+```text
++-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| array_sort((x, y) -> IF(cardinality(x) < cardinality(y), -1,
+ IF(cardinality(x) = cardinality(y), 0, 1)),
+ [[2, 3, 1], [4, 2, 1, 4], [1, 2]]) |
++-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| [[1, 2], [2, 3, 1], [4, 2, 1, 4]]
|
++-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+```
diff --git
a/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/array-functions/array-sort.md
b/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/array-functions/array-sort.md
index 2214ed035ff..cf7112e69a8 100644
---
a/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/array-functions/array-sort.md
+++
b/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/array-functions/array-sort.md
@@ -7,34 +7,173 @@
## Function
-Sort array elements in ascending order.
+If no lambda function is specified, the array elements are sorted in ascending
order. Otherwise, sorting is performed according to the lambda function.
## Syntax
- `ARRAY_SORT(arr)`
+- `ARRAY_SORT(lambda, arr)`
## Parameters
+- `lambda`: A `lambda` expression used to define sorting rules, whose return
value should be -1, 0, or 1 (representing less than, less than or equal to, and
greater than respectively).
- `arr`: `ARRAY<T>`, where `T` can be numeric, boolean, string, datetime, IP,
etc.
## Return value
-- Returns `ARRAY<T>` of the same type as the input.
-- `NULL` elements are placed at the beginning of the returned array.
+- If it does not contain a `lambda` expression
+ - Returns `ARRAY<T>` of the same type as the input.
+ - `NULL` elements are placed at the beginning of the returned array.
+- If it contains a `lambda` expression, sort according to the lambda
expression and return an `ARRAY<T>` of the same type as the input.
## Usage notes
-- If the input is `NULL`, returns `NULL`; if the input is an empty array `[]`,
returns an empty array.
-- `ARRAY_SORT` sorts in ascending order, while `ARRAY_REVERSE_SORT` sorts in
descending order.
+- If it does not contain a `lambda` expression
+ - If the input is `NULL`, returns `NULL`; if the input is an empty array
`[]`, returns an empty array.
+ - `ARRAY_SORT` sorts in ascending order, while `ARRAY_REVERSE_SORT` sorts in
descending order.
+- If containing a `lambda` expression
+ - The value of the `lambda` expression shall be -1, 0, or 1. Should a `NULL`
value exist, it shall be explicitly stated whether the `NULL` value is to be
placed before or after the array.
## Examples
-- Basic: `NULL` elements are placed at the beginning of the returned array
- - `ARRAY_SORT([2,1,3,null])` -> `[null, 1, 2, 3]`
-
-- If the input is `NULL`, returns `NULL`; if the input is an empty array `[]`,
returns an empty array.
- - `ARRAY_SORT(NULL)` -> `NULL`
- - `ARRAY_SORT([])` -> `[]`
-
-
-
+1. Basic: `NULL` elements are placed at the beginning of the returned array
+
+```sql
+SELECT ARRAY_SORT([2,1,3,null]);
+```
+
+```text
++--------------------------+
+| ARRAY_SORT([2,1,3,null]) |
++--------------------------+
+| [null, 1, 2, 3] |
++--------------------------+
+```
+
+2. If the input is `NULL`, returns `NULL`; if the input is an empty array
`[]`, returns an empty array.
+
+```sql
+SELECT ARRAY_SORT(NULL);
+```
+
+```text
++------------------+
+| ARRAY_SORT(NULL) |
++------------------+
+| NULL |
++------------------+
+```
+
+```sql
+SELECT ARRAY_SORT([]);
+```
+
+```text
++----------------+
+| ARRAY_SORT([]) |
++----------------+
+| [] |
++----------------+
+```
+
+3. Use `lambda` expressions
+
+```sql
+SELECT array_sort((x, y) -> IF(x < y, 1, IF(x = y, 0, -1)), [3, 2, 5, 1, 2]);
+```
+
+```text
++-----------------------------------------------------------------------+
+| array_sort((x, y) -> IF(x < y, 1, IF(x = y, 0, -1)), [3, 2, 5, 1, 2]) |
++-----------------------------------------------------------------------+
+| [5, 3, 2, 2, 1] |
++-----------------------------------------------------------------------+
+```
+
+```sql
+SELECT array_sort((x, y) -> IF(x < y, 1, IF(x = y, 0, -1)), ['bc', 'ab',
'dc']);
+```
+
+```text
++--------------------------------------------------------------------------+
+| array_sort((x, y) -> IF(x < y, 1, IF(x = y, 0, -1)), ['bc', 'ab', 'dc']) |
++--------------------------------------------------------------------------+
+| ["dc", "bc", "ab"] |
++--------------------------------------------------------------------------+
+```
+
+```sql
+SELECT array_sort((x, y) -> CASE WHEN x IS NULL THEN -1
+ WHEN y IS NULL THEN 1
+ WHEN x < y THEN 1
+ WHEN x = y THEN 0
+ ELSE -1 END,
+ [3, 2, null, 5, null, 1, 2]);
+```
+
+```text
++------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| array_sort((x, y) -> CASE WHEN x IS NULL THEN -1
+ WHEN y IS NULL THEN 1
+ WHEN x < y THEN 1
+ WHEN x = y THEN 0
+ ELSE -1 END,
+ [3, 2, null, 5, null, 1, 2]) |
++------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| [null, null, 5, 3, 2, 2, 1]
|
++------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+```
+
+```sql
+SELECT array_sort((x, y) -> CASE WHEN x IS NULL THEN 1
+ WHEN y IS NULL THEN -1
+ WHEN x < y THEN 1
+ WHEN x = y THEN 0
+ ELSE -1 END,
+ [3, 2, null, 5, null, 1, 2]);
+```
+
+```text
++------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| array_sort((x, y) -> CASE WHEN x IS NULL THEN 1
+ WHEN y IS NULL THEN -1
+ WHEN x < y THEN 1
+ WHEN x = y THEN 0
+ ELSE -1 END,
+ [3, 2, null, 5, null, 1, 2]) |
++------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| [5, 3, 2, 2, 1, null, null]
|
++------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+```
+
+```sql
+SELECT array_sort((x, y) -> IF(length(x) < length(y), -1,
+ IF(length(x) = length(y), 0, 1)),
+ ['a', 'abcd', 'abc']);
+```
+
+```text
++--------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| array_sort((x, y) -> IF(length(x) < length(y), -1,
+ IF(length(x) = length(y), 0, 1)),
+ ['a', 'abcd', 'abc']) |
++--------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ["a", "abc", "abcd"]
|
++--------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+```
+
+```sql
+SELECT array_sort((x, y) -> IF(cardinality(x) < cardinality(y), -1,
+ IF(cardinality(x) = cardinality(y), 0, 1)),
+ [[2, 3, 1], [4, 2, 1, 4], [1, 2]]);
+```
+
+```text
++-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| array_sort((x, y) -> IF(cardinality(x) < cardinality(y), -1,
+ IF(cardinality(x) = cardinality(y), 0, 1)),
+ [[2, 3, 1], [4, 2, 1, 4], [1, 2]]) |
++-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| [[1, 2], [2, 3, 1], [4, 2, 1, 4]]
|
++-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+```
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
