Merge pull request #50556 from den-crane/patch-49

Doc. A note for first_value/last_value
ClickHouse · Jun 5, 2023 · 21e3b6d · 21e3b6d
2 parents a27de9a + bcd89cb
commit 21e3b6d
Show file tree

Hide file tree

Showing 2 changed files with 60 additions and 7 deletions.
diff --git a/docs/en/sql-reference/aggregate-functions/reference/first_value.md b/docs/en/sql-reference/aggregate-functions/reference/first_value.md
@@ -6,24 +6,32 @@ sidebar_position: 7
 # first_value
 
 Selects the first encountered value, similar to `any`, but could accept NULL.
+Mostly it should be used with [Window Functions](../../window-functions/index.md).
+Without Window Functions the result will be random if the source stream is not ordered.
 
 ## examples
 
 ```sql
-insert into test_data (a,b) values (1,null), (2,3), (4, 5), (6,null)
+CREATE TABLE test_data
+(
+    a Int64,
+    b Nullable(Int64)
+)
+ENGINE = Memory;
+
+INSERT INTO test_data (a, b) Values (1,null), (2,3), (4, 5), (6,null);
 ```
 
 ### example1
 The NULL value is ignored at default.
 ```sql
-select first_value(b) from test_data
+select first_value(b) from test_data;
 ```
 
 ```text
 ┌─first_value_ignore_nulls(b)─┐
 │                           3 │
 └─────────────────────────────┘
-
 ```
 
 ### example2
@@ -36,7 +44,6 @@ select first_value(b) ignore nulls from test_data
 ┌─first_value_ignore_nulls(b)─┐
 │                           3 │
 └─────────────────────────────┘
-
 ```
 
 ### example3
@@ -46,10 +53,28 @@ select first_value(b) respect nulls from test_data
 ```
 
 ```text
-
 ┌─first_value_respect_nulls(b)─┐
 │                         ᴺᵁᴸᴸ │
 └──────────────────────────────┘
 ```
 
+### example4
+Stabilized result using the sub-query with `ORDER BY`.
+```sql
+SELECT
+    first_value_respect_nulls(b),
+    first_value(b)
+FROM
+(
+    SELECT *
+    FROM test_data
+    ORDER BY a ASC
+)
+```
+
+```text
+┌─first_value_respect_nulls(b)─┬─first_value(b)─┐
+│                         ᴺᵁᴸᴸ │              3 │
+└──────────────────────────────┴────────────────┘
+```
 
diff --git a/docs/en/sql-reference/aggregate-functions/reference/last_value.md b/docs/en/sql-reference/aggregate-functions/reference/last_value.md
@@ -6,12 +6,20 @@ sidebar_position: 8
 # last_value
 
 Selects the last encountered value, similar to `anyLast`, but could accept NULL.
-
+Mostly it should be used with [Window Functions](../../window-functions/index.md).
+Without Window Functions the result will be random if the source stream is not ordered.
 
 ## examples
 
 ```sql
-insert into test_data (a,b) values (1,null), (2,3), (4, 5), (6,null)
+CREATE TABLE test_data
+(
+    a Int64,
+    b Nullable(Int64)
+)
+ENGINE = Memory;
+
+INSERT INTO test_data (a, b) Values (1,null), (2,3), (4, 5), (6,null)
 ```
 
 ### example1
@@ -50,4 +58,24 @@ select last_value(b) respect nulls from test_data
 └─────────────────────────────┘
 ```
 
+### example4
+Stabilized result using the sub-query with `ORDER BY`.
+```sql
+SELECT
+    last_value_respect_nulls(b),
+    last_value(b)
+FROM
+(
+    SELECT *
+    FROM test_data
+    ORDER BY a ASC
+)
+```
+
+```text
+┌─last_value_respect_nulls(b)─┬─last_value(b)─┐
+│                        ᴺᵁᴸᴸ │             5 │
+└─────────────────────────────┴───────────────┘
+```
+