You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@datafusion.apache.org by co...@apache.org on 2025/08/01 19:47:57 UTC
(datafusion) branch main updated: Fix window_functions docs formatting (#17005)
This is an automated email from the ASF dual-hosted git repository.
comphead pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/datafusion.git
The following commit(s) were added to refs/heads/main by this push:
new a078cd257d Fix window_functions docs formatting (#17005)
a078cd257d is described below
commit a078cd257d8073a5d01b69b850d173c92f8bcd15
Author: Matt Matravers <ma...@hotmail.com>
AuthorDate: Fri Aug 1 20:47:52 2025 +0100
Fix window_functions docs formatting (#17005)
* Fix window_functions docs formatting
* Fix the source and make the docs consistent
---------
Co-authored-by: Andrew Lamb <an...@nerdnetworks.org>
---
datafusion/functions-window/src/cume_dist.rs | 15 ++--
datafusion/functions-window/src/lead_lag.rs | 28 +++----
datafusion/functions-window/src/nth_value.rs | 35 ++++----
datafusion/functions-window/src/ntile.rs | 18 ++--
datafusion/functions-window/src/rank.rs | 45 +++++-----
datafusion/functions-window/src/row_number.rs | 18 ++--
docs/source/user-guide/sql/window_functions.md | 109 ++++++++++---------------
7 files changed, 123 insertions(+), 145 deletions(-)
diff --git a/datafusion/functions-window/src/cume_dist.rs b/datafusion/functions-window/src/cume_dist.rs
index ed86699481..57ffa627eb 100644
--- a/datafusion/functions-window/src/cume_dist.rs
+++ b/datafusion/functions-window/src/cume_dist.rs
@@ -46,13 +46,13 @@ define_udwf_and_expr!(
doc_section(label = "Ranking Functions"),
description = "Relative rank of the current row: (number of rows preceding or peer with the current row) / (total rows).",
syntax_example = "cume_dist()",
- sql_example = r#"```sql
- --Example usage of the cume_dist window function:
- SELECT salary,
- cume_dist() OVER (ORDER BY salary) AS cume_dist
- FROM employees;
-```
+ sql_example = r#"
```sql
+-- Example usage of the cume_dist window function:
+SELECT salary,
+ cume_dist() OVER (ORDER BY salary) AS cume_dist
+FROM employees;
+
+--------+-----------+
| salary | cume_dist |
+--------+-----------+
@@ -60,7 +60,8 @@ define_udwf_and_expr!(
| 50000 | 0.67 |
| 70000 | 1.00 |
+--------+-----------+
-```"#
+```
+"#
)]
#[derive(Debug)]
pub struct CumeDist {
diff --git a/datafusion/functions-window/src/lead_lag.rs b/datafusion/functions-window/src/lead_lag.rs
index 05bbd1e114..04e0d4e095 100644
--- a/datafusion/functions-window/src/lead_lag.rs
+++ b/datafusion/functions-window/src/lead_lag.rs
@@ -159,15 +159,14 @@ static LAG_DOCUMENTATION: LazyLock<Documentation> = LazyLock::new(|| {
the value of expression should be retrieved. Defaults to 1.")
.with_argument("default", "The default value if the offset is \
not within the partition. Must be of the same type as expression.")
- .with_sql_example(r#"```sql
- --Example usage of the lag window function:
- SELECT employee_id,
- salary,
- lag(salary, 1, 0) OVER (ORDER BY employee_id) AS prev_salary
- FROM employees;
-```
-
+ .with_sql_example(r#"
```sql
+-- Example usage of the lag window function:
+SELECT employee_id,
+ salary,
+ lag(salary, 1, 0) OVER (ORDER BY employee_id) AS prev_salary
+FROM employees;
+
+-------------+--------+-------------+
| employee_id | salary | prev_salary |
+-------------+--------+-------------+
@@ -176,7 +175,8 @@ static LAG_DOCUMENTATION: LazyLock<Documentation> = LazyLock::new(|| {
| 3 | 70000 | 50000 |
| 4 | 60000 | 70000 |
+-------------+--------+-------------+
-```"#)
+```
+"#)
.build()
});
@@ -195,17 +195,16 @@ static LEAD_DOCUMENTATION: LazyLock<Documentation> = LazyLock::new(|| {
forward the value of expression should be retrieved. Defaults to 1.")
.with_argument("default", "The default value if the offset is \
not within the partition. Must be of the same type as expression.")
- .with_sql_example(r#"```sql
--- Example usage of lead() :
+ .with_sql_example(r#"
+```sql
+-- Example usage of lead window function:
SELECT
employee_id,
department,
salary,
lead(salary, 1, 0) OVER (PARTITION BY department ORDER BY salary) AS next_salary
FROM employees;
-```
-```sql
+-------------+-------------+--------+--------------+
| employee_id | department | salary | next_salary |
+-------------+-------------+--------+--------------+
@@ -215,7 +214,8 @@ FROM employees;
| 4 | Engineering | 40000 | 60000 |
| 5 | Engineering | 60000 | 0 |
+-------------+-------------+--------+--------------+
-```"#)
+```
+"#)
.build()
});
diff --git a/datafusion/functions-window/src/nth_value.rs b/datafusion/functions-window/src/nth_value.rs
index 4c7dd995ec..e4fa023166 100644
--- a/datafusion/functions-window/src/nth_value.rs
+++ b/datafusion/functions-window/src/nth_value.rs
@@ -136,16 +136,16 @@ static FIRST_VALUE_DOCUMENTATION: LazyLock<Documentation> = LazyLock::new(|| {
"first_value(expression)",
)
.with_argument("expression", "Expression to operate on")
- .with_sql_example(r#"```sql
- --Example usage of the first_value window function:
- SELECT department,
- employee_id,
- salary,
- first_value(salary) OVER (PARTITION BY department ORDER BY salary DESC) AS top_salary
- FROM employees;
-```
-
+ .with_sql_example(
+ r#"
```sql
+-- Example usage of the first_value window function:
+SELECT department,
+ employee_id,
+ salary,
+ first_value(salary) OVER (PARTITION BY department ORDER BY salary DESC) AS top_salary
+FROM employees;
+
+-------------+-------------+--------+------------+
| department | employee_id | salary | top_salary |
+-------------+-------------+--------+------------+
@@ -155,7 +155,9 @@ static FIRST_VALUE_DOCUMENTATION: LazyLock<Documentation> = LazyLock::new(|| {
| Engineering | 4 | 90000 | 90000 |
| Engineering | 5 | 80000 | 90000 |
+-------------+-------------+--------+------------+
-```"#)
+```
+"#,
+ )
.build()
});
@@ -178,9 +180,7 @@ SELECT department,
salary,
last_value(salary) OVER (PARTITION BY department ORDER BY salary) AS running_last_salary
FROM employees;
-```
-```sql
+-------------+-------------+--------+---------------------+
| department | employee_id | salary | running_last_salary |
+-------------+-------------+--------+---------------------+
@@ -190,7 +190,8 @@ FROM employees;
| Engineering | 4 | 40000 | 40000 |
| Engineering | 5 | 60000 | 60000 |
+-------------+-------------+--------+---------------------+
-```"#)
+```
+"#)
.build()
});
@@ -214,7 +215,8 @@ static NTH_VALUE_DOCUMENTATION: LazyLock<Documentation> = LazyLock::new(|| {
"Integer. Specifies the row number (starting from 1) in the window frame.",
)
.with_sql_example(
- r#"```sql
+ r#"
+```sql
-- Sample employees table:
CREATE TABLE employees (id INT, salary INT);
INSERT INTO employees (id, salary) VALUES
@@ -230,9 +232,7 @@ SELECT nth_value(salary, 2) OVER (
ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW
) AS nth_value
FROM employees;
-```
-```text
+-----------+
| nth_value |
+-----------+
@@ -242,7 +242,8 @@ FROM employees;
| 40000 |
| 40000 |
+-----------+
-```"#,
+```
+"#,
)
.build()
});
diff --git a/datafusion/functions-window/src/ntile.rs b/datafusion/functions-window/src/ntile.rs
index 6b4c0960e6..91e36d8053 100644
--- a/datafusion/functions-window/src/ntile.rs
+++ b/datafusion/functions-window/src/ntile.rs
@@ -53,15 +53,14 @@ pub fn ntile(arg: Expr) -> Expr {
name = "expression",
description = "An integer describing the number groups the partition should be split into"
),
- sql_example = r#"```sql
- --Example usage of the ntile window function:
- SELECT employee_id,
- salary,
- ntile(4) OVER (ORDER BY salary DESC) AS quartile
- FROM employees;
-```
-
+ sql_example = r#"
```sql
+-- Example usage of the ntile window function:
+SELECT employee_id,
+ salary,
+ ntile(4) OVER (ORDER BY salary DESC) AS quartile
+FROM employees;
+
+-------------+--------+----------+
| employee_id | salary | quartile |
+-------------+--------+----------+
@@ -74,7 +73,8 @@ pub fn ntile(arg: Expr) -> Expr {
| 7 | 40000 | 4 |
| 8 | 30000 | 4 |
+-------------+--------+----------+
-```"#
+```
+"#
)]
#[derive(Debug)]
pub struct Ntile {
diff --git a/datafusion/functions-window/src/rank.rs b/datafusion/functions-window/src/rank.rs
index 5099b25e1d..ca9efbeeaa 100644
--- a/datafusion/functions-window/src/rank.rs
+++ b/datafusion/functions-window/src/rank.rs
@@ -111,15 +111,14 @@ static RANK_DOCUMENTATION: LazyLock<Documentation> = LazyLock::new(|| {
skips ranks for identical values.",
"rank()")
- .with_sql_example(r#"```sql
- --Example usage of the rank window function:
- SELECT department,
- salary,
- rank() OVER (PARTITION BY department ORDER BY salary DESC) AS rank
- FROM employees;
-```
-
+ .with_sql_example(r#"
```sql
+-- Example usage of the rank window function:
+SELECT department,
+ salary,
+ rank() OVER (PARTITION BY department ORDER BY salary DESC) AS rank
+FROM employees;
+
+-------------+--------+------+
| department | salary | rank |
+-------------+--------+------+
@@ -130,7 +129,8 @@ static RANK_DOCUMENTATION: LazyLock<Documentation> = LazyLock::new(|| {
| Engineering | 90000 | 1 |
| Engineering | 80000 | 2 |
+-------------+--------+------+
-```"#)
+```
+"#)
.build()
});
@@ -142,15 +142,14 @@ static DENSE_RANK_DOCUMENTATION: LazyLock<Documentation> = LazyLock::new(|| {
Documentation::builder(DOC_SECTION_RANKING, "Returns the rank of the current row without gaps. This function ranks \
rows in a dense manner, meaning consecutive ranks are assigned even for identical \
values.", "dense_rank()")
- .with_sql_example(r#"```sql
- --Example usage of the dense_rank window function:
- SELECT department,
- salary,
- dense_rank() OVER (PARTITION BY department ORDER BY salary DESC) AS dense_rank
- FROM employees;
-```
-
+ .with_sql_example(r#"
```sql
+-- Example usage of the dense_rank window function:
+SELECT department,
+ salary,
+ dense_rank() OVER (PARTITION BY department ORDER BY salary DESC) AS dense_rank
+FROM employees;
+
+-------------+--------+------------+
| department | salary | dense_rank |
+-------------+--------+------------+
@@ -173,14 +172,12 @@ static PERCENT_RANK_DOCUMENTATION: LazyLock<Documentation> = LazyLock::new(|| {
Documentation::builder(DOC_SECTION_RANKING, "Returns the percentage rank of the current row within its partition. \
The value ranges from 0 to 1 and is computed as `(rank - 1) / (total_rows - 1)`.", "percent_rank()")
.with_sql_example(r#"```sql
- --Example usage of the percent_rank window function:
- SELECT employee_id,
- salary,
- percent_rank() OVER (ORDER BY salary) AS percent_rank
- FROM employees;
-```
+ -- Example usage of the percent_rank window function:
+SELECT employee_id,
+ salary,
+ percent_rank() OVER (ORDER BY salary) AS percent_rank
+FROM employees;
-```sql
+-------------+--------+---------------+
| employee_id | salary | percent_rank |
+-------------+--------+---------------+
diff --git a/datafusion/functions-window/src/row_number.rs b/datafusion/functions-window/src/row_number.rs
index ba8627dd86..01f52380ba 100644
--- a/datafusion/functions-window/src/row_number.rs
+++ b/datafusion/functions-window/src/row_number.rs
@@ -46,15 +46,14 @@ define_udwf_and_expr!(
doc_section(label = "Ranking Functions"),
description = "Number of the current row within its partition, counting from 1.",
syntax_example = "row_number()",
- sql_example = r"```sql
- --Example usage of the row_number window function:
- SELECT department,
- salary,
- row_number() OVER (PARTITION BY department ORDER BY salary DESC) AS row_num
- FROM employees;
-```
-
+ sql_example = r"
```sql
+-- Example usage of the row_number window function:
+SELECT department,
+ salary,
+ row_number() OVER (PARTITION BY department ORDER BY salary DESC) AS row_num
+FROM employees;
+
+-------------+--------+---------+
| department | salary | row_num |
+-------------+--------+---------+
@@ -65,7 +64,8 @@ define_udwf_and_expr!(
| Engineering | 90000 | 1 |
| Engineering | 80000 | 2 |
+-------------+--------+---------+
-```#"
+```
+#"
)]
#[derive(Debug)]
pub struct RowNumber {
diff --git a/docs/source/user-guide/sql/window_functions.md b/docs/source/user-guide/sql/window_functions.md
index bcb33bad7f..dc06f3d051 100644
--- a/docs/source/user-guide/sql/window_functions.md
+++ b/docs/source/user-guide/sql/window_functions.md
@@ -169,13 +169,11 @@ cume_dist()
#### Example
```sql
- --Example usage of the cume_dist window function:
- SELECT salary,
- cume_dist() OVER (ORDER BY salary) AS cume_dist
- FROM employees;
-```
+-- Example usage of the cume_dist window function:
+SELECT salary,
+ cume_dist() OVER (ORDER BY salary) AS cume_dist
+FROM employees;
-```sql
+--------+-----------+
| salary | cume_dist |
+--------+-----------+
@@ -196,14 +194,12 @@ dense_rank()
#### Example
```sql
- --Example usage of the dense_rank window function:
- SELECT department,
- salary,
- dense_rank() OVER (PARTITION BY department ORDER BY salary DESC) AS dense_rank
- FROM employees;
-```
+-- Example usage of the dense_rank window function:
+SELECT department,
+ salary,
+ dense_rank() OVER (PARTITION BY department ORDER BY salary DESC) AS dense_rank
+FROM employees;
-```sql
+-------------+--------+------------+
| department | salary | dense_rank |
+-------------+--------+------------+
@@ -231,14 +227,12 @@ ntile(expression)
#### Example
```sql
- --Example usage of the ntile window function:
- SELECT employee_id,
- salary,
- ntile(4) OVER (ORDER BY salary DESC) AS quartile
- FROM employees;
-```
+-- Example usage of the ntile window function:
+SELECT employee_id,
+ salary,
+ ntile(4) OVER (ORDER BY salary DESC) AS quartile
+FROM employees;
-```sql
+-------------+--------+----------+
| employee_id | salary | quartile |
+-------------+--------+----------+
@@ -264,14 +258,12 @@ percent_rank()
#### Example
```sql
- --Example usage of the percent_rank window function:
- SELECT employee_id,
- salary,
- percent_rank() OVER (ORDER BY salary) AS percent_rank
- FROM employees;
-```
+ -- Example usage of the percent_rank window function:
+SELECT employee_id,
+ salary,
+ percent_rank() OVER (ORDER BY salary) AS percent_rank
+FROM employees;
-```sql
+-------------+--------+---------------+
| employee_id | salary | percent_rank |
+-------------+--------+---------------+
@@ -292,14 +284,12 @@ rank()
#### Example
```sql
- --Example usage of the rank window function:
- SELECT department,
- salary,
- rank() OVER (PARTITION BY department ORDER BY salary DESC) AS rank
- FROM employees;
-```
+-- Example usage of the rank window function:
+SELECT department,
+ salary,
+ rank() OVER (PARTITION BY department ORDER BY salary DESC) AS rank
+FROM employees;
-```sql
+-------------+--------+------+
| department | salary | rank |
+-------------+--------+------+
@@ -323,14 +313,12 @@ row_number()
#### Example
```sql
- --Example usage of the row_number window function:
- SELECT department,
- salary,
- row_number() OVER (PARTITION BY department ORDER BY salary DESC) AS row_num
- FROM employees;
-```
+-- Example usage of the row_number window function:
+SELECT department,
+ salary,
+ row_number() OVER (PARTITION BY department ORDER BY salary DESC) AS row_num
+FROM employees;
-````sql
+-------------+--------+---------+
| department | salary | row_num |
+-------------+--------+---------+
@@ -341,8 +329,9 @@ row_number()
| Engineering | 90000 | 1 |
| Engineering | 80000 | 2 |
+-------------+--------+---------+
-```#
+```
+#
## Analytical Functions
@@ -358,7 +347,7 @@ Returns value evaluated at the row that is the first row of the window frame.
```sql
first_value(expression)
-````
+```
#### Arguments
@@ -367,15 +356,13 @@ first_value(expression)
#### Example
```sql
- --Example usage of the first_value window function:
- SELECT department,
- employee_id,
- salary,
- first_value(salary) OVER (PARTITION BY department ORDER BY salary DESC) AS top_salary
- FROM employees;
-```
+-- Example usage of the first_value window function:
+SELECT department,
+ employee_id,
+ salary,
+ first_value(salary) OVER (PARTITION BY department ORDER BY salary DESC) AS top_salary
+FROM employees;
-```sql
+-------------+-------------+--------+------------+
| department | employee_id | salary | top_salary |
+-------------+-------------+--------+------------+
@@ -404,14 +391,12 @@ lag(expression, offset, default)
#### Example
```sql
- --Example usage of the lag window function:
- SELECT employee_id,
- salary,
- lag(salary, 1, 0) OVER (ORDER BY employee_id) AS prev_salary
- FROM employees;
-```
+-- Example usage of the lag window function:
+SELECT employee_id,
+ salary,
+ lag(salary, 1, 0) OVER (ORDER BY employee_id) AS prev_salary
+FROM employees;
-```sql
+-------------+--------+-------------+
| employee_id | salary | prev_salary |
+-------------+--------+-------------+
@@ -443,9 +428,7 @@ SELECT department,
salary,
last_value(salary) OVER (PARTITION BY department ORDER BY salary) AS running_last_salary
FROM employees;
-```
-```sql
+-------------+-------------+--------+---------------------+
| department | employee_id | salary | running_last_salary |
+-------------+-------------+--------+---------------------+
@@ -474,16 +457,14 @@ lead(expression, offset, default)
#### Example
```sql
--- Example usage of lead() :
+-- Example usage of lead window function:
SELECT
employee_id,
department,
salary,
lead(salary, 1, 0) OVER (PARTITION BY department ORDER BY salary) AS next_salary
FROM employees;
-```
-```sql
+-------------+-------------+--------+--------------+
| employee_id | department | salary | next_salary |
+-------------+-------------+--------+--------------+
@@ -526,9 +507,7 @@ SELECT nth_value(salary, 2) OVER (
ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW
) AS nth_value
FROM employees;
-```
-```text
+-----------+
| nth_value |
+-----------+
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@datafusion.apache.org
For additional commands, e-mail: commits-help@datafusion.apache.org