docs: Added Special Functions Page (#13102)

* Added special function page * Add index entry, tweak wording * Improve example * Update docs/source/user-guide/sql/special_functions.md --------- Co-authored-by: Andrew Lamb <[email protected]> Co-authored-by: Oleks V <[email protected]>
apache · Oct 26, 2024 · 22a242c · 22a242c
1 parent 73cfa6c
commit 22a242c
Show file tree

Hide file tree

Showing 3 changed files with 101 additions and 77 deletions.
diff --git a/docs/source/user-guide/sql/index.rst b/docs/source/user-guide/sql/index.rst
@@ -35,5 +35,6 @@ SQL Reference
    window_functions_new
    scalar_functions
    scalar_functions_new
+   special_functions
    sql_status
    write_options
diff --git a/docs/source/user-guide/sql/scalar_functions.md b/docs/source/user-guide/sql/scalar_functions.md
@@ -72,51 +72,8 @@ See [date_part](#date_part).
 
 ## Array Functions
 
-- [unnest](#unnest)
 - [range](#range)
 
-### `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
@@ -165,40 +122,6 @@ are not allowed
 
 - generate_series
 
-## Struct Functions
-
-- [unnest](#unnest-struct)
-
-For more struct functions see the new documentation [
-`here`](https://datafusion.apache.org/user-guide/sql/scalar_functions_new.html)
-
-### `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              |
-+-----------------------+-----------------------+
-```
-
 ## Other Functions
 
 See the new documentation [`here`](https://datafusion.apache.org/user-guide/sql/scalar_functions_new.html)
diff --git a/docs/source/user-guide/sql/special_functions.md b/docs/source/user-guide/sql/special_functions.md
@@ -0,0 +1,100 @@
+<!---
+  Licensed to the Apache Software Foundation (ASF) under one
+  or more contributor license agreements.  See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership.  The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the
+  "License"); you may not use this file except in compliance
+  with the License.  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing,
+  software distributed under the License is distributed on an
+  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  KIND, either express or implied.  See the License for the
+  specific language governing permissions and limitations
+  under the License.
+-->
+
+# Special Functions
+
+## Expansion Functions
+
+- [unnest](#unnest)
+- [unnest(struct)](#unnest-struct)
+
+### `unnest`
+
+Expands an array or map into rows.
+
+#### Arguments
+
+- **array**: Array expression to unnest.
+  Can be a constant, column, or function, and any combination of array operators.
+
+#### Examples
+
+```sql
+> select unnest(make_array(1, 2, 3, 4, 5)) as unnested;
++----------+
+| unnested |
++----------+
+| 1        |
+| 2        |
+| 3        |
+| 4        |
+| 5        |
++----------+
+```
+
+```sql
+> select unnest(range(0, 10)) as unnested_range;
++----------------+
+| unnested_range |
++----------------+
+| 0              |
+| 1              |
+| 2              |
+| 3              |
+| 4              |
+| 5              |
+| 6              |
+| 7              |
+| 8              |
+| 9              |
++----------------+
+```
+
+### `unnest (struct)`
+
+Expand a struct fields into individual columns.
+
+#### Arguments
+
+- **struct**: Object expression to unnest.
+  Can be a constant, column, or function, and any combination of object operators.
+
+#### Examples
+
+```sql
+> create table foo as values ({a: 5, b: 'a string'}), ({a:6, b: 'another string'});
+
+> create view foov as select column1 as struct_column from foo;
+
+> select * from foov;
++---------------------------+
+| struct_column             |
++---------------------------+
+| {a: 5, b: a string}       |
+| {a: 6, b: another string} |
++---------------------------+
+
+> select unnest(struct_column) from foov;
++------------------------------------------+------------------------------------------+
+| unnest_placeholder(foov.struct_column).a | unnest_placeholder(foov.struct_column).b |
++------------------------------------------+------------------------------------------+
+| 5                                        | a string                                 |
+| 6                                        | another string                           |
++------------------------------------------+------------------------------------------+
+```