Skip to content

Commit 350b61b

Browse files
zhangstar333zhangstar333
authored
[doc](function) support nth_value function (#2350)
1 parent ac37f25 commit 350b61b

File tree

4 files changed

+156
-2
lines changed

4 files changed

+156
-2
lines changed

‎docs/sql-manual/sql-functions/window-functions/nth-value.md

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
---
2+
{
3+
"title": "NTH_VALUE",
4+
"language": "en"
5+
}
6+
---
7+
8+
<!-- Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
9+
10+
http://www.apache.org/licenses/LICENSE-2.0
11+
12+
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. -->
13+
14+
## Description
15+
16+
NTH_VALUE() is a window function used to return the Nth value in an ordered dataset within a window partition. When N exceeds the valid size of the window, it returns NULL as the result.
17+
18+
## Syntax
19+
20+
```sql
21+
NTH_VALUE(<expr>, <offset>)
22+
```
23+
24+
## Parameters
25+
| Parameter | Description |
26+
| ------------------- | ------------------------------------------------------------------------------------------------------------------- |
27+
| expr | The expression from which will get the value value |
28+
| offset | The parameter offset must be a positive integer greater than 0, indicating the Nth element value to retrieve, with the starting index at 1. |
29+
30+
## Return Value
31+
32+
Returns the same data type as the input expression.
33+
34+
## Examples
35+
36+
```sql
37+
WITH example_data AS (
38+
SELECT 1 as column1, 66 as column2, 'A' as group_name
39+
UNION ALL
40+
SELECT 1, 10, 'A'
41+
UNION ALL
42+
SELECT 1, 66, 'A'
43+
UNION ALL
44+
SELECT 1, 20, 'A'
45+
UNION ALL
46+
SELECT 2, 66, 'B'
47+
UNION ALL
48+
SELECT 2, 30, 'B'
49+
UNION ALL
50+
SELECT 2, 40, 'B'
51+
)
52+
SELECT
53+
group_name,
54+
column1,
55+
column2,
56+
NTH_VALUE(column2, 2) OVER (
57+
PARTITION BY column1
58+
ORDER BY column2
59+
ROWS BETWEEN 1 preceding and 1 following
60+
) as nth
61+
FROM example_data
62+
ORDER BY column1, column2;
63+
```
64+
65+
```text
66+
+------------+---------+---------+------+
67+
| group_name | column1 | column2 | nth |
68+
+------------+---------+---------+------+
69+
| A | 1 | 10 | 20 |
70+
| A | 1 | 20 | 20 |
71+
| A | 1 | 66 | 66 |
72+
| A | 1 | 66 | 66 |
73+
| B | 2 | 30 | 40 |
74+
| B | 2 | 40 | 40 |
75+
| B | 2 | 66 | 66 |
76+
+------------+---------+---------+------+
77+
```

‎docs/sql-manual/sql-functions/window-functions/overview.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@ function(<args>) OVER(
3737
| Parameter | Description |
3838
|-----------|-------------|
3939
| `<args>` | Input parameters for the window function, specific to the function being used |
40-
| `<function>` | Supported functions include: AVG(), COUNT(), DENSE_RANK(), FIRST_VALUE(), LAG(), LAST_VALUE(), LEAD(), MAX(), MIN(), RANK(), ROW_NUMBER(), SUM() and all aggregate functions |
40+
| `<function>` | Supported functions include: AVG(), COUNT(), DENSE_RANK(), FIRST_VALUE(), LAG(), LAST_VALUE(), LEAD(), MAX(), MIN(), RANK(), ROW_NUMBER(), SUM(), NTH_VALUE() And ALL Aggregate Functions |
4141
| `<partition_by>` | Similar to GROUP BY, groups data by specified columns |
4242
| `<order_by>` | Defines the ordering of data within the window |
4343
| `<window_clause>` | Defines the window range, syntax: ROWS BETWEEN [ { m \| UNBOUNDED } PRECEDING \| CURRENT ROW] [ AND [CURRENT ROW \| { UNBOUNDED \| n } FOLLOWING] ] |

‎i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/window-functions/nth-value.md

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
---
2+
{
3+
"title": "NTH_VALUE",
4+
"language": "zh-CN"
5+
}
6+
---
7+
8+
<!-- Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
9+
10+
http://www.apache.org/licenses/LICENSE-2.0
11+
12+
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. -->
13+
14+
## 描述
15+
16+
NTH_VALUE() 是一个窗口函数，用于返回窗口分区中有序数据集的第 N 个值，当 N 超出窗口有效大小时，返回结果 NULL。
17+
18+
## 语法
19+
20+
```sql
21+
NTH_VALUE(<expr>, <offset>)
22+
```
23+
24+
## 参数
25+
| 参数 | 说明 |
26+
| ------------------- | --------------------------------------------------------------------------------------- |
27+
| expr | 需要获取值的表达式 |
28+
| offset | 参数 offset 的值为大于0的正整数，用于表示获取的第N的元素值，起始值从1开始 |
29+
30+
## 返回值
31+
32+
返回与输入表达式相同的数据类型。
33+
34+
## 举例
35+
36+
```sql
37+
WITH example_data AS (
38+
SELECT 1 as column1, 66 as column2, 'A' as group_name
39+
UNION ALL
40+
SELECT 1, 10, 'A'
41+
UNION ALL
42+
SELECT 1, 66, 'A'
43+
UNION ALL
44+
SELECT 1, 20, 'A'
45+
UNION ALL
46+
SELECT 2, 66, 'B'
47+
UNION ALL
48+
SELECT 2, 30, 'B'
49+
UNION ALL
50+
SELECT 2, 40, 'B'
51+
)
52+
SELECT
53+
group_name,
54+
column1,
55+
column2,
56+
NTH_VALUE(column2, 2) OVER (
57+
PARTITION BY column1
58+
ORDER BY column2
59+
ROWS BETWEEN 1 preceding and 1 following
60+
) as nth
61+
FROM example_data
62+
ORDER BY column1, column2;
63+
```
64+
65+
```text
66+
+------------+---------+---------+------+
67+
| group_name | column1 | column2 | nth |
68+
+------------+---------+---------+------+
69+
| A | 1 | 10 | 20 |
70+
| A | 1 | 20 | 20 |
71+
| A | 1 | 66 | 66 |
72+
| A | 1 | 66 | 66 |
73+
| B | 2 | 30 | 40 |
74+
| B | 2 | 40 | 40 |
75+
| B | 2 | 66 | 66 |
76+
+------------+---------+---------+------+
77+
```

‎i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/window-functions/overview.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@ function(<args>) OVER(
3737
| 参数 | 说明 |
3838
|------|------|
3939
| `<args>` | 窗口函数的输入参数，具体参数根据所使用的函数而定 |
40-
| `<function>` | 支持的函数包括：AVG(), COUNT(), DENSE_RANK(), FIRST_VALUE(), LAG(), LAST_VALUE(), LEAD(), MAX(), MIN(), RANK(), ROW_NUMBER(), SUM() 和所有聚合函数 |
40+
| `<function>` | 支持的函数包括：AVG(), COUNT(), DENSE_RANK(), FIRST_VALUE(), LAG(), LAST_VALUE(), LEAD(), MAX(), MIN(), RANK(), ROW_NUMBER(), SUM(), NTH_VALUE() 和所有聚合函数 |
4141
| `<partition_by>` | 类似于 GROUP BY，按指定列对数据进行分组 |
4242
| `<order_by>` | 定义窗口内数据的排序方式 |
4343
| `<window_clause>` | 定义窗口范围，语法为：ROWS BETWEEN [ { m \| UNBOUNDED } PRECEDING \| CURRENT ROW] [ AND [CURRENT ROW \| { UNBOUNDED \| n } FOLLOWING] ] |

0 commit comments

Comments
 (0)