Add window function examples in code (#16102)

Author: alamb

datafusion/functions-window/src/lead_lag.rs

@@ -157,6 +157,24 @@ 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;
+```
+
+```sql
++-------------+--------+-------------+
+| employee_id | salary | prev_salary |
++-------------+--------+-------------+
+| 1           | 30000  | 0           |
+| 2           | 50000  | 30000       |
+| 3           | 70000  | 50000       |
+| 4           | 60000  | 70000       |
++-------------+--------+-------------+
+```"#)
         .build()
 });
 
@@ -175,6 +193,27 @@ 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() :
+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  |
++-------------+-------------+--------+--------------+
+| 1           | Sales       | 30000  | 50000        |
+| 2           | Sales       | 50000  | 70000        |
+| 3           | Sales       | 70000  | 0            |
+| 4           | Engineering | 40000  | 60000        |
+| 5           | Engineering | 60000  | 0            |
++-------------+-------------+--------+--------------+
+```"#)
         .build()
 });
 

datafusion/functions-window/src/nth_value.rs

@@ -135,6 +135,26 @@ 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;
+```
+
+```sql
++-------------+-------------+--------+------------+
+| department  | employee_id | salary | top_salary |
++-------------+-------------+--------+------------+
+| Sales       | 1           | 70000  | 70000      |
+| Sales       | 2           | 50000  | 70000      |
+| Sales       | 3           | 30000  | 70000      |
+| Engineering | 4           | 90000  | 90000      |
+| Engineering | 5           | 80000  | 90000      |
++-------------+-------------+--------+------------+
+```"#)
     .build()
 });
 
@@ -150,6 +170,26 @@ static LAST_VALUE_DOCUMENTATION: LazyLock<Documentation> = LazyLock::new(|| {
         "last_value(expression)",
     )
     .with_argument("expression", "Expression to operate on")
+        .with_sql_example(r#"```sql
+-- SQL example of last_value:
+SELECT department,
+       employee_id,
+       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 |
++-------------+-------------+--------+---------------------+
+| Sales       | 1           | 30000  | 30000               |
+| Sales       | 2           | 50000  | 50000               |
+| Sales       | 3           | 70000  | 70000               |
+| Engineering | 4           | 40000  | 40000               |
+| Engineering | 5           | 60000  | 60000               |
++-------------+-------------+--------+---------------------+
+```"#)
     .build()
 });
 

datafusion/functions-window/src/ntile.rs

@@ -52,7 +52,29 @@ pub fn ntile(arg: Expr) -> Expr {
     argument(
         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
++-------------+--------+----------+
+| employee_id | salary | quartile |
++-------------+--------+----------+
+| 1           | 90000  | 1        |
+| 2           | 85000  | 1        |
+| 3           | 80000  | 2        |
+| 4           | 70000  | 2        |
+| 5           | 60000  | 3        |
+| 6           | 50000  | 3        |
+| 7           | 40000  | 4        |
+| 8           | 30000  | 4        |
++-------------+--------+----------+
+```"#
 )]
 #[derive(Debug)]
 pub struct Ntile {

datafusion/functions-window/src/rank.rs

@@ -110,6 +110,26 @@ 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;
+```
+
+```sql
++-------------+--------+------+
+| department  | salary | rank |
++-------------+--------+------+
+| Sales       | 70000  | 1    |
+| Sales       | 50000  | 2    |
+| Sales       | 50000  | 2    |
+| Sales       | 30000  | 4    |
+| Engineering | 90000  | 1    |
+| Engineering | 80000  | 2    |
++-------------+--------+------+
+```"#)
         .build()
 });
 
@@ -121,6 +141,26 @@ 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;
+```
+
+```sql
++-------------+--------+------------+
+| department  | salary | dense_rank |
++-------------+--------+------------+
+| Sales       | 70000  | 1          |
+| Sales       | 50000  | 2          |
+| Sales       | 50000  | 2          |
+| Sales       | 30000  | 3          |
+| Engineering | 90000  | 1          |
+| Engineering | 80000  | 2          |
++-------------+--------+------------+
+```"#)
         .build()
 });
 
@@ -131,6 +171,23 @@ fn get_dense_rank_doc() -> &'static Documentation {
 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;
+```
+
+```sql
++-------------+--------+---------------+
+| employee_id | salary | percent_rank  |
++-------------+--------+---------------+
+| 1           | 30000  | 0.00          |
+| 2           | 50000  | 0.50          |
+| 3           | 70000  | 1.00          |
++-------------+--------+---------------+
+```"#)
         .build()
 });
 

datafusion/functions-window/src/row_number.rs

@@ -44,7 +44,27 @@ define_udwf_and_expr!(
 #[user_doc(
     doc_section(label = "Ranking Functions"),
     description = "Number of the current row within its partition, counting from 1.",
-    syntax_example = "row_number()"
+    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
++-------------+--------+---------+
+| department  | salary | row_num |
++-------------+--------+---------+
+| Sales       | 70000  | 1       |
+| Sales       | 50000  | 2       |
+| Sales       | 50000  | 3       |
+| Sales       | 30000  | 4       |
+| Engineering | 90000  | 1       |
+| Engineering | 80000  | 2       |
++-------------+--------+---------+
+```#"
 )]
 #[derive(Debug)]
 pub struct RowNumber {

docs/source/user-guide/sql/window_functions.md

@@ -228,7 +228,7 @@ ntile(expression)
 
 - **expression**: An integer describing the number groups the partition should be split into
 
-#### Exmaple
+#### Example
 
 ```sql
     --Example usage of the ntile window function:
@@ -330,7 +330,7 @@ row_number()
     FROM employees;
 ```
 
-```sql
+````sql
 +-------------+--------+---------+
 | department  | salary | row_num |
 +-------------+--------+---------+
@@ -341,7 +341,8 @@ row_number()
 | Engineering | 90000  | 1       |
 | Engineering | 80000  | 2       |
 +-------------+--------+---------+
-```
+```#
+
 
 ## Analytical Functions
 
@@ -357,7 +358,7 @@ Returns value evaluated at the row that is the first row of the window frame.
 
 ```sql
 first_value(expression)
-```
+````
 
 #### Arguments
 
@@ -433,6 +434,8 @@ last_value(expression)
 
 - **expression**: Expression to operate on
 
+#### Example
+
 ```sql
 -- SQL example of last_value:
 SELECT department,
@@ -468,6 +471,8 @@ lead(expression, offset, default)
 - **offset**: Integer. Specifies how many rows forward the value of expression should be retrieved. Defaults to 1.
 - **default**: The default value if the offset is not within the partition. Must be of the same type as expression.
 
+#### Example
+
 ```sql
 -- Example usage of lead() :
 SELECT