Docs: Add unnest to SQL Reference (#10839)

* Add unnest to SQL Reference * Add unnest docs for struct, add additional example for unnest array * unnest -> unnest (struct) * prettier --------- Co-authored-by: Andrew Lamb <[email protected]>
apache · Jun 11, 2024 · d84d75a · d84d75a
1 parent f554c9f
commit d84d75a
Showing 1 changed file with 71 additions and 0 deletions.
diff --git a/docs/source/user-guide/sql/scalar_functions.md b/docs/source/user-guide/sql/scalar_functions.md
@@ -2085,6 +2085,7 @@ to_unixtime(expression[, ..., format_n])
 - [string_to_array](#string_to_array)
 - [string_to_list](#string_to_list)
 - [trim_array](#trim_array)
+- [unnest](#unnest)
 - [range](#range)
 
 ### `array_append`
@@ -3346,6 +3347,48 @@ trim_array(array, n)
   Can be a constant, column, or function, and any combination of array operators.
 - **n**: Element to trim the array.
 
+### `unnest`
+
+Transforms an array into rows.
+
+#### Arguments
+
+- **array**: Array expression to unnest.
+  Can be a constant, column, or function, and any combination of array operators.
+
+#### Examples
+
+```
+> select unnest(make_array(1, 2, 3, 4, 5));
++------------------------------------------------------------------+
+| unnest(make_array(Int64(1),Int64(2),Int64(3),Int64(4),Int64(5))) |
++------------------------------------------------------------------+
+| 1                                                                |
+| 2                                                                |
+| 3                                                                |
+| 4                                                                |
+| 5                                                                |
++------------------------------------------------------------------+
+```
+
+```
+> select unnest(range(0, 10));
++-----------------------------------+
+| unnest(range(Int64(0),Int64(10))) |
++-----------------------------------+
+| 0                                 |
+| 1                                 |
+| 2                                 |
+| 3                                 |
+| 4                                 |
+| 5                                 |
+| 6                                 |
+| 7                                 |
+| 8                                 |
+| 9                                 |
++-----------------------------------+
+```
+
 ### `range`
 
 Returns an Arrow array between start and stop with step. `SELECT range(2, 10, 3) -> [2, 5, 8]` or `SELECT range(DATE '1992-09-01', DATE '1993-03-01', INTERVAL '1' MONTH);`
@@ -3395,6 +3438,7 @@ are not allowed
 
 - [struct](#struct)
 - [named_struct](#named_struct)
+- [unnest](#unnest-struct)
 
 ### `struct`
 
@@ -3480,6 +3524,33 @@ select named_struct('field_a', a, 'field_b', b) from t;
   Can be a constant, column, or function, and any combination of arithmetic or
   string operators.
 
+### `unnest (struct)`
+
+Unwraps struct fields into columns.
+
+#### Arguments
+
+- **struct**: Object expression to unnest.
+  Can be a constant, column, or function, and any combination of object operators.
+
+#### Examples
+
+```
+> select * from foo;
++---------------------+
+| column1             |
++---------------------+
+| {a: 5, b: a string} |
++---------------------+
+
+> select unnest(column1) from foo;
++-----------------------+-----------------------+
+| unnest(foo.column1).a | unnest(foo.column1).b |
++-----------------------+-----------------------+
+| 5                     | a string              |
++-----------------------+-----------------------+
+```
+
 ## Hashing Functions
 
 - [digest](#digest)