add: rand window support respect|ignore nulls (#966)

* add: rand window support respect|ignore nulls

* Update last-value.md

* Update first-value.md

* Update nth-value.md

* fmt

* modify note and title

* merge

---------

Co-authored-by: Bohu <[email protected]>

Author: TCeason

docs/en/sql-reference/20-sql-functions/08-window-functions/first-value.md

@@ -4,9 +4,9 @@ title: FIRST_VALUE
 
 import FunctionDescription from '@site/src/components/FunctionDescription';
 
-<FunctionDescription description="Introduced: v1.1.50"/>
+<FunctionDescription description="Introduced: v1.2.568"/>
 
-Returns the first value from an ordered group of values.
+When `IGNORE NULLS` is used with FIRST_VALUE, the function returns the first value in the frame that is not NULL (or NULL if all values are NULL). If not specified, the default is RESPECT NULLS.
 
 See also:
 
@@ -16,7 +16,7 @@ See also:
 ## Syntax
 
 ```sql
-FIRST_VALUE(expression) OVER ([PARTITION BY partition_expression] ORDER BY order_expression [window_frame])
+FIRST_VALUE(expression) [ { IGNORE | RESPECT } NULLS ] OVER ([PARTITION BY partition_expression] ORDER BY order_expression [window_frame])
 ```
 
 For the syntax of window frame, see [Window Frame Syntax](index.md#window-frame-syntax).
@@ -52,4 +52,41 @@ employee_id | first_name | last_name | salary  | highest_salary_first_name
 3           | David      | Johnson   | 5500.00 | Mary
 1           | John       | Doe       | 5000.00 | Mary
 5           | Michael    | Brown     | 4500.00 | Mary
-```
+
+```
+
+### Returning NON-NULLs with IGNORE NULLS
+
+```sql
+CREATE or replace TABLE example AS SELECT * FROM (VALUES
+	(0, 1, 614),
+	(1, 1, null),
+	(2, 1, null),
+	(3, 1, 639),
+	(4, 1, 2027)
+) tbl(id, user_id, order_id);
+
+
+SELECT
+  id,
+  user_id,
+  order_id,
+  FIRST_VALUE (order_id) IGNORE nulls over (
+    PARTITION BY user_id
+    ORDER BY
+      id ROWS BETWEEN 1 PRECEDING AND UNBOUNDED FOLLOWING
+  ) AS last_order_id
+FROM
+  example
+
+┌───────────────────────────────────────────────────────┐
+│   id  │ user_id │     order_id     │   last_order_id  │
+├───────┼─────────┼──────────────────┼──────────────────┤
+│     0 │       1 │              614 │              614 │
+│     1 │       1 │             NULL │              614 │
+│     2 │       1 │             NULL │              639 │
+│     3 │       1 │              639 │              639 │
+│     4 │       1 │             2027 │              639 │
+└───────────────────────────────────────────────────────┘
+
+```

docs/en/sql-reference/20-sql-functions/08-window-functions/last-value.md

@@ -4,9 +4,9 @@ title: LAST_VALUE
 
 import FunctionDescription from '@site/src/components/FunctionDescription';
 
-<FunctionDescription description="Introduced: v1.1.50"/>
+<FunctionDescription description="Introduced: v1.2.568"/>
 
-Returns the last value from an ordered group of values.
+When `IGNORE NULLS` is used with LAST_VALUE, the function returns the last value in the frame that is not NULL (or NULL if all values are NULL). If not specified, the default is RESPECT NULLS.
 
 See also:
 
@@ -16,7 +16,7 @@ See also:
 ## Syntax
 
 ```sql
-LAST_VALUE(expression) OVER ([PARTITION BY partition_expression] ORDER BY order_expression [window_frame])
+LAST_VALUE(expression) [ { IGNORE | RESPECT } NULLS ] OVER ([PARTITION BY partition_expression] ORDER BY order_expression [window_frame])
 ```
 
 For the syntax of window frame, see [Window Frame Syntax](index.md#window-frame-syntax).
@@ -51,4 +51,40 @@ employee_id | first_name | last_name | salary  | lowest_salary_first_name
 3           | David      | Johnson   | 5500.00 | Michael
 1           | John       | Doe       | 5000.00 | Michael
 5           | Michael    | Brown     | 4500.00 | Michael
-```
+```
+
+### Returning NON-NULLs with IGNORE NULLS
+
+```sql
+CREATE or replace TABLE example AS SELECT * FROM (VALUES
+	(0, 1, 614),
+	(1, 1, null),
+	(2, 1, null),
+	(3, 1, 639),
+	(4, 1, 2027)
+) tbl(id, user_id, order_id);
+
+
+SELECT
+  id,
+  user_id,
+  order_id,
+  LAST_VALUE (order_id) IGNORE NULLS over (
+    PARTITION BY user_id
+    ORDER BY
+      id ROWS BETWEEN UNBOUNDED PRECEDING AND 1 PRECEDING
+  ) AS last_order_id
+FROM
+  example
+
+┌───────────────────────────────────────────────────────┐
+│   id  │ user_id │     order_id     │   last_order_id  │
+├───────┼─────────┼──────────────────┼──────────────────┤
+│     0 │       1 │              614 │             NULL │
+│     1 │       1 │             NULL │              614 │
+│     2 │       1 │             NULL │              614 │
+│     3 │       1 │              639 │              614 │
+│     4 │       1 │             2027 │              639 │
+└───────────────────────────────────────────────────────┘
+
+```

docs/en/sql-reference/20-sql-functions/08-window-functions/nth-value.md

@@ -4,9 +4,9 @@ title: NTH_VALUE
 
 import FunctionDescription from '@site/src/components/FunctionDescription';
 
-<FunctionDescription description="Introduced: v1.1.50"/>
+<FunctionDescription description="Introduced: v1.2.568"/>
 
-Returns the Nth value from an ordered group of values.
+Returns expr evaluated at the nth row (among rows with a non-null value of expr if `IGNORE NULLS` is set) of the window frame (counting from 1); NULL if no such row.
 
 See also:
 
@@ -16,7 +16,7 @@ See also:
 ## Syntax
 
 ```sql
-NTH_VALUE(expression, n) OVER ([PARTITION BY partition_expression] ORDER BY order_expression [window_frame])
+NTH_VALUE(expression, n) [ { IGNORE | RESPECT } NULLS ] OVER ([PARTITION BY partition_expression] ORDER BY order_expression [window_frame])
 ```
 
 For the syntax of window frame, see [Window Frame Syntax](index.md#window-frame-syntax).
@@ -51,4 +51,40 @@ employee_id | first_name | last_name | salary  | second_highest_salary_first_nam
 3           | David      | Johnson   | 5500.00 | Jane
 1           | John       | Doe       | 5000.00 | Jane
 5           | Michael    | Brown     | 4500.00 | Jane
-```
+```
+
+### Returning NON-NULLs with IGNORE NULLS
+
+```sql
+CREATE or replace TABLE example AS SELECT * FROM (VALUES
+	(0, 1, 614),
+	(1, 1, null),
+	(2, 1, null),
+	(3, 1, 639),
+	(4, 1, 2027)
+) tbl(id, user_id, order_id);
+
+
+SELECT
+  id,
+  user_id,
+  order_id,
+  NTH_VALUE (order_id, 2) IGNORE NULLS over (
+    PARTITION BY user_id
+    ORDER BY
+      id ROWS BETWEEN UNBOUNDED PRECEDING AND 1 PRECEDING
+  ) AS last_order_id
+FROM
+  example
+
+┌───────────────────────────────────────────────────────┐
+│   id  │ user_id │     order_id     │   last_order_id  │
+├───────┼─────────┼──────────────────┼──────────────────┤
+│     0 │       1 │              614 │             NULL │
+│     1 │       1 │             NULL │             NULL │
+│     2 │       1 │             NULL │             NULL │
+│     3 │       1 │              639 │             NULL │
+│     4 │       1 │             2027 │              639 │
+└───────────────────────────────────────────────────────┘
+
+```