Skip to content

Commit e43db45

Browse files
wumeibanfawumeibanfa
authored
[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
1 parent 0c6e302 commit e43db45

File tree

4 files changed

+606
-48
lines changed
  • docs/sql-manual/sql-functions/scalar-functions/array-functions
  • i18n/zh-CN/docusaurus-plugin-content-docs
    • current/sql-manual/sql-functions/scalar-functions/array-functions
    • version-4.x/sql-manual/sql-functions/scalar-functions/array-functions
  • versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/array-functions

4 files changed

+606
-48
lines changed

‎docs/sql-manual/sql-functions/scalar-functions/array-functions/array-sort.md‎

Lines changed: 153 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -7,34 +7,173 @@
77

88
## Function
99

10-
Sort array elements in ascending order.
10+
If no lambda function is specified, the array elements are sorted in ascending order. Otherwise, sorting is performed according to the lambda function.
1111

1212
## Syntax
1313

1414
- `ARRAY_SORT(arr)`
15+
- `ARRAY_SORT(lambda, arr)`
1516

1617
## Parameters
1718

19+
- `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).
1820
- `arr`: `ARRAY<T>`, where `T` can be numeric, boolean, string, datetime, IP, etc.
1921

2022
## Return value
2123

22-
- Returns `ARRAY<T>` of the same type as the input.
23-
- `NULL` elements are placed at the beginning of the returned array.
24+
- If it does not contain a `lambda` expression
25+
- Returns `ARRAY<T>` of the same type as the input.
26+
- `NULL` elements are placed at the beginning of the returned array.
27+
- If it contains a `lambda` expression, sort according to the lambda expression and return an `ARRAY<T>` of the same type as the input.
2428

2529
## Usage notes
2630

27-
- If the input is `NULL`, returns `NULL`; if the input is an empty array `[]`, returns an empty array.
28-
- `ARRAY_SORT` sorts in ascending order, while `ARRAY_REVERSE_SORT` sorts in descending order.
31+
- If it does not contain a `lambda` expression
32+
- If the input is `NULL`, returns `NULL`; if the input is an empty array `[]`, returns an empty array.
33+
- `ARRAY_SORT` sorts in ascending order, while `ARRAY_REVERSE_SORT` sorts in descending order.
34+
- If containing a `lambda` expression
35+
- 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.
2936

3037
## Examples
3138

32-
- Basic: `NULL` elements are placed at the beginning of the returned array
33-
- `ARRAY_SORT([2,1,3,null])` -> `[null, 1, 2, 3]`
34-
35-
- If the input is `NULL`, returns `NULL`; if the input is an empty array `[]`, returns an empty array.
36-
- `ARRAY_SORT(NULL)` -> `NULL`
37-
- `ARRAY_SORT([])` -> `[]`
38-
39-
40-
39+
1. Basic: `NULL` elements are placed at the beginning of the returned array
40+
41+
```sql
42+
SELECT ARRAY_SORT([2,1,3,null]);
43+
```
44+
45+
```text
46+
+--------------------------+
47+
| ARRAY_SORT([2,1,3,null]) |
48+
+--------------------------+
49+
| [null, 1, 2, 3] |
50+
+--------------------------+
51+
```
52+
53+
2. If the input is `NULL`, returns `NULL`; if the input is an empty array `[]`, returns an empty array.
54+
55+
```sql
56+
SELECT ARRAY_SORT(NULL);
57+
```
58+
59+
```text
60+
+------------------+
61+
| ARRAY_SORT(NULL) |
62+
+------------------+
63+
| NULL |
64+
+------------------+
65+
```
66+
67+
```sql
68+
SELECT ARRAY_SORT([]);
69+
```
70+
71+
```text
72+
+----------------+
73+
| ARRAY_SORT([]) |
74+
+----------------+
75+
| [] |
76+
+----------------+
77+
```
78+
79+
3. Use `lambda` expressions
80+
81+
```sql
82+
SELECT array_sort((x, y) -> IF(x < y, 1, IF(x = y, 0, -1)), [3, 2, 5, 1, 2]);
83+
```
84+
85+
```text
86+
+-----------------------------------------------------------------------+
87+
| array_sort((x, y) -> IF(x < y, 1, IF(x = y, 0, -1)), [3, 2, 5, 1, 2]) |
88+
+-----------------------------------------------------------------------+
89+
| [5, 3, 2, 2, 1] |
90+
+-----------------------------------------------------------------------+
91+
```
92+
93+
```sql
94+
SELECT array_sort((x, y) -> IF(x < y, 1, IF(x = y, 0, -1)), ['bc', 'ab', 'dc']);
95+
```
96+
97+
```text
98+
+--------------------------------------------------------------------------+
99+
| array_sort((x, y) -> IF(x < y, 1, IF(x = y, 0, -1)), ['bc', 'ab', 'dc']) |
100+
+--------------------------------------------------------------------------+
101+
| ["dc", "bc", "ab"] |
102+
+--------------------------------------------------------------------------+
103+
```
104+
105+
```sql
106+
SELECT array_sort((x, y) -> CASE WHEN x IS NULL THEN -1
107+
WHEN y IS NULL THEN 1
108+
WHEN x < y THEN 1
109+
WHEN x = y THEN 0
110+
ELSE -1 END,
111+
[3, 2, null, 5, null, 1, 2]);
112+
```
113+
114+
```text
115+
+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
116+
| array_sort((x, y) -> CASE WHEN x IS NULL THEN -1
117+
WHEN y IS NULL THEN 1
118+
WHEN x < y THEN 1
119+
WHEN x = y THEN 0
120+
ELSE -1 END,
121+
[3, 2, null, 5, null, 1, 2]) |
122+
+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
123+
| [null, null, 5, 3, 2, 2, 1] |
124+
+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
125+
```
126+
127+
```sql
128+
SELECT array_sort((x, y) -> CASE WHEN x IS NULL THEN 1
129+
WHEN y IS NULL THEN -1
130+
WHEN x < y THEN 1
131+
WHEN x = y THEN 0
132+
ELSE -1 END,
133+
[3, 2, null, 5, null, 1, 2]);
134+
```
135+
136+
```text
137+
+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
138+
| array_sort((x, y) -> CASE WHEN x IS NULL THEN 1
139+
WHEN y IS NULL THEN -1
140+
WHEN x < y THEN 1
141+
WHEN x = y THEN 0
142+
ELSE -1 END,
143+
[3, 2, null, 5, null, 1, 2]) |
144+
+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
145+
| [5, 3, 2, 2, 1, null, null] |
146+
+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
147+
```
148+
149+
```sql
150+
SELECT array_sort((x, y) -> IF(length(x) < length(y), -1,
151+
IF(length(x) = length(y), 0, 1)),
152+
['a', 'abcd', 'abc']);
153+
```
154+
155+
```text
156+
+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+
157+
| array_sort((x, y) -> IF(length(x) < length(y), -1,
158+
IF(length(x) = length(y), 0, 1)),
159+
['a', 'abcd', 'abc']) |
160+
+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+
161+
| ["a", "abc", "abcd"] |
162+
+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+
163+
```
164+
165+
```sql
166+
SELECT array_sort((x, y) -> IF(cardinality(x) < cardinality(y), -1,
167+
IF(cardinality(x) = cardinality(y), 0, 1)),
168+
[[2, 3, 1], [4, 2, 1, 4], [1, 2]]);
169+
```
170+
171+
```text
172+
+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
173+
| array_sort((x, y) -> IF(cardinality(x) < cardinality(y), -1,
174+
IF(cardinality(x) = cardinality(y), 0, 1)),
175+
[[2, 3, 1], [4, 2, 1, 4], [1, 2]]) |
176+
+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
177+
| [[1, 2], [2, 3, 1], [4, 2, 1, 4]] |
178+
+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
179+
```

‎i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/array-functions/array-sort.md‎

Lines changed: 150 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -7,33 +7,173 @@
77

88
## 功能
99

10-
对数组元素按升序排序。
10+
若不指定lambda函数，则对数组元素按升序排序。否则按照lambda函数进行排序。
1111

1212
## 语法
1313

1414
- `ARRAY_SORT(arr)`
15+
- `ARRAY_SORT(lambda, arr)`
1516

1617
## 参数
1718

19+
- `lambda`: `lambda` 表达式，用于定义排序规则，返回值应为-1， 0， 1（分别表示小于，等于，大于）。
1820
- `arr`：`ARRAY<T>`，`T` 可为数值、布尔、字符串、日期时间、IP 等。
1921

2022
## 返回值
2123

22-
- 返回与输入同类型的 `ARRAY<T>`。
23-
- `NULL` 元素放在返回的数组最前面。
24+
- 若不包含`lambda`表达式
25+
- 返回与输入同类型的 `ARRAY<T>`。
26+
- `NULL` 元素放在返回的数组最前面。
27+
- 若包含`lambda`表达式，按照lambda表达式进行排序，返回与输入同类型的 `ARRAY<T>`。
2428

2529
## 使用说明
2630

27-
- 若输入为 `NULL`，返回 `NULL`; 若输入为空数组 `[]`，返回空数组。
28-
- `ARRAY_SORT` 是升序排序，`ARRAY_REVERSE_SORT` 是降序排序。
31+
- 若不包含`lambda`表达式
32+
- 若输入为 `NULL`，返回 `NULL`; 若输入为空数组 `[]`，返回空数组。
33+
- `ARRAY_SORT` 是升序排序，`ARRAY_REVERSE_SORT` 是降序排序。
34+
- 若包含`lambda`表达式
35+
- `lambda`表达式的值应为-1，0，1，若存在`NULL`值，应明确说明`NULL`值应排在数组前还是数组后。
2936

3037
## 示例
3138

32-
- 基本: `NULL` 元素放在返回的数组最前面
33-
- `ARRAY_SORT([2,1,3,null])` -> `[null, 1, 2, 3]`
39+
1. 基本: `NULL` 元素放在返回的数组最前面
3440

35-
- 输入为 `NULL`，返回 `NULL`; 输入为空数组 `[]`，返回空数组。
36-
- `ARRAY_SORT(NULL)` -> `NULL`
37-
- `ARRAY_SORT([])` -> `[]`
41+
```sql
42+
SELECT ARRAY_SORT([2,1,3,null]);
43+
```
3844

45+
```text
46+
+--------------------------+
47+
| ARRAY_SORT([2,1,3,null]) |
48+
+--------------------------+
49+
| [null, 1, 2, 3] |
50+
+--------------------------+
51+
```
3952

53+
2. 输入为 `NULL`，返回 `NULL`; 输入为空数组 `[]`，返回空数组。
54+
55+
```sql
56+
SELECT ARRAY_SORT(NULL);
57+
```
58+
59+
```text
60+
+------------------+
61+
| ARRAY_SORT(NULL) |
62+
+------------------+
63+
| NULL |
64+
+------------------+
65+
```
66+
67+
```sql
68+
SELECT ARRAY_SORT([]);
69+
```
70+
71+
```text
72+
+----------------+
73+
| ARRAY_SORT([]) |
74+
+----------------+
75+
| [] |
76+
+----------------+
77+
```
78+
79+
3. 使用`lambda`表达式
80+
81+
```sql
82+
SELECT array_sort((x, y) -> IF(x < y, 1, IF(x = y, 0, -1)), [3, 2, 5, 1, 2]);
83+
```
84+
85+
```text
86+
+-----------------------------------------------------------------------+
87+
| array_sort((x, y) -> IF(x < y, 1, IF(x = y, 0, -1)), [3, 2, 5, 1, 2]) |
88+
+-----------------------------------------------------------------------+
89+
| [5, 3, 2, 2, 1] |
90+
+-----------------------------------------------------------------------+
91+
```
92+
93+
```sql
94+
SELECT array_sort((x, y) -> IF(x < y, 1, IF(x = y, 0, -1)), ['bc', 'ab', 'dc']);
95+
```
96+
97+
```text
98+
+--------------------------------------------------------------------------+
99+
| array_sort((x, y) -> IF(x < y, 1, IF(x = y, 0, -1)), ['bc', 'ab', 'dc']) |
100+
+--------------------------------------------------------------------------+
101+
| ["dc", "bc", "ab"] |
102+
+--------------------------------------------------------------------------+
103+
```
104+
105+
```sql
106+
SELECT array_sort((x, y) -> CASE WHEN x IS NULL THEN -1
107+
WHEN y IS NULL THEN 1
108+
WHEN x < y THEN 1
109+
WHEN x = y THEN 0
110+
ELSE -1 END,
111+
[3, 2, null, 5, null, 1, 2]);
112+
```
113+
114+
```text
115+
+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
116+
| array_sort((x, y) -> CASE WHEN x IS NULL THEN -1
117+
WHEN y IS NULL THEN 1
118+
WHEN x < y THEN 1
119+
WHEN x = y THEN 0
120+
ELSE -1 END,
121+
[3, 2, null, 5, null, 1, 2]) |
122+
+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
123+
| [null, null, 5, 3, 2, 2, 1] |
124+
+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
125+
```
126+
127+
```sql
128+
SELECT array_sort((x, y) -> CASE WHEN x IS NULL THEN 1
129+
WHEN y IS NULL THEN -1
130+
WHEN x < y THEN 1
131+
WHEN x = y THEN 0
132+
ELSE -1 END,
133+
[3, 2, null, 5, null, 1, 2]);
134+
```
135+
136+
```text
137+
+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
138+
| array_sort((x, y) -> CASE WHEN x IS NULL THEN 1
139+
WHEN y IS NULL THEN -1
140+
WHEN x < y THEN 1
141+
WHEN x = y THEN 0
142+
ELSE -1 END,
143+
[3, 2, null, 5, null, 1, 2]) |
144+
+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
145+
| [5, 3, 2, 2, 1, null, null] |
146+
+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
147+
```
148+
149+
```sql
150+
SELECT array_sort((x, y) -> IF(length(x) < length(y), -1,
151+
IF(length(x) = length(y), 0, 1)),
152+
['a', 'abcd', 'abc']);
153+
```
154+
155+
```text
156+
+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+
157+
| array_sort((x, y) -> IF(length(x) < length(y), -1,
158+
IF(length(x) = length(y), 0, 1)),
159+
['a', 'abcd', 'abc']) |
160+
+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+
161+
| ["a", "abc", "abcd"] |
162+
+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+
163+
```
164+
165+
```sql
166+
SELECT array_sort((x, y) -> IF(cardinality(x) < cardinality(y), -1,
167+
IF(cardinality(x) = cardinality(y), 0, 1)),
168+
[[2, 3, 1], [4, 2, 1, 4], [1, 2]]);
169+
```
170+
171+
```text
172+
+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
173+
| array_sort((x, y) -> IF(cardinality(x) < cardinality(y), -1,
174+
IF(cardinality(x) = cardinality(y), 0, 1)),
175+
[[2, 3, 1], [4, 2, 1, 4], [1, 2]]) |
176+
+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
177+
| [[1, 2], [2, 3, 1], [4, 2, 1, 4]] |
178+
+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
179+
```

0 commit comments

Comments
 (0)