fix: arrays_zip/list_zip allow single array argument (apache#21047)

## Which issue does this PR close?

<!--
We generally require a GitHub issue to be filed for all bug fixes and
enhancements and this helps us generate change logs for our releases.
You can link an issue to this PR using the GitHub syntax. For example
`Closes apache#123` indicates that this PR will close issue apache#123.
-->

- Closes apache#21046

## Rationale for this change

<!--
Why are you proposing this change? If this is already explained clearly
in the issue then this section is not needed.
Explaining clearly why changes are proposed helps reviewers understand
your changes and offer better suggestions for fixes.
-->

Align DataFusion's `arrays_zip` implementation w/ DuckDB and Spark

## What changes are included in this PR?

<!--
There is no need to duplicate the description in the issue here but it
is sometimes worth providing a summary of the individual changes in this
PR.
-->

- Allow single array argument
- Update user doc and fix a few examples

## Are these changes tested?

<!--
We typically require tests for all PRs in order to:
1. Prevent the code from being accidentally broken by subsequent changes
2. Serve as another way to document the expected behavior of the code

If tests are not included in your PR, please explain why (for example,
are they covered by existing tests)?
-->

Yes, by sqllogictest

## Are there any user-facing changes?

<!--
If there are user-facing changes then we may require documentation to be
updated before approving the PR.
-->

Yes, I modified user doc.

<!--
If there are any breaking changes to public APIs, please add the `api
change` label.
-->

---------

Co-authored-by: Martin Grigorov <martin-g@users.noreply.github.com>

Author: hsiang-c

datafusion/functions-nested/src/arrays_zip.rs

@@ -50,31 +50,33 @@ struct ListColumnView {
 make_udf_expr_and_func!(
     ArraysZip,
     arrays_zip,
-    "combines multiple arrays into a single array of structs.",
+    "combines one or multiple arrays into a single array of structs.",
     arrays_zip_udf
 );
 
 #[user_doc(
     doc_section(label = "Array Functions"),
     description = "Returns an array of structs created by combining the elements of each input array at the same index. If the arrays have different lengths, shorter arrays are padded with NULLs.",
-    syntax_example = "arrays_zip(array1, array2[, ..., array_n])",
+    syntax_example = "arrays_zip(array1[, ..., array_n])",
     sql_example = r#"```sql
-> select arrays_zip([1, 2, 3], ['a', 'b', 'c']);
+> select arrays_zip([1, 2, 3]);
 +---------------------------------------------------+
-| arrays_zip([1, 2, 3], ['a', 'b', 'c'])             |
+| arrays_zip([1, 2, 3])                             |
 +---------------------------------------------------+
-| [{c0: 1, c1: a}, {c0: 2, c1: b}, {c0: 3, c1: c}] |
+| [{1: 1}, {1: 2}, {1: 3}]                          |
 +---------------------------------------------------+
 > select arrays_zip([1, 2], [3, 4, 5]);
 +---------------------------------------------------+
-| arrays_zip([1, 2], [3, 4, 5])                       |
+| arrays_zip([1, 2], [3, 4, 5])                     |
 +---------------------------------------------------+
-| [{c0: 1, c1: 3}, {c0: 2, c1: 4}, {c0: , c1: 5}]  |
+| [{1: 1, 2: 3}, {1: 2, 2: 4}, {1: NULL, 2: 5}]     |
 +---------------------------------------------------+
 ```"#,
     argument(name = "array1", description = "First array expression."),
-    argument(name = "array2", description = "Second array expression."),
-    argument(name = "array_n", description = "Subsequent array expressions.")
+    argument(
+        name = "array_n",
+        description = "Optional additional array expressions."
+    )
 )]
 #[derive(Debug, PartialEq, Eq, Hash)]
 pub struct ArraysZip {
@@ -112,7 +114,7 @@ impl ScalarUDFImpl for ArraysZip {
 
     fn return_type(&self, arg_types: &[DataType]) -> Result<DataType> {
         if arg_types.is_empty() {
-            return exec_err!("arrays_zip requires at least two arguments");
+            return exec_err!("arrays_zip requires at least one argument");
         }
 
         let mut fields = Vec::with_capacity(arg_types.len());
@@ -155,8 +157,8 @@ impl ScalarUDFImpl for ArraysZip {
 /// lengths, shorter arrays are padded with NULLs.
 /// Supports List, LargeList, and Null input types.
 fn arrays_zip_inner(args: &[ArrayRef]) -> Result<ArrayRef> {
-    if args.len() < 2 {
-        return exec_err!("arrays_zip requires at least two arguments");
+    if args.is_empty() {
+        return exec_err!("arrays_zip requires at least one argument");
     }
 
     let num_rows = args[0].len();

datafusion/sqllogictest/test_files/array.slt

@@ -7324,6 +7324,58 @@ select arrays_zip(a, b) from (values ([1, 2], [10, 20]), (null, [30, 40]), ([5,
 [{1: NULL, 2: 30}, {1: NULL, 2: 40}]
 [{1: 5, 2: NULL}, {1: 6, 2: NULL}]
 
+# column-level test with single argument
+query ?
+select arrays_zip(a) from (values ([1, 2], [10, 20]), (null, [30, 40]), ([5, 6], null)) as t(a, b);
+----
+[{1: 1}, {1: 2}]
+NULL
+[{1: 5}, {1: 6}]
+
+query ?
+select arrays_zip(b) from (values ([1, 2], [10, 20]), (null, [30, 40]), ([5, 6], null)) as t(a, b);
+----
+[{1: 10}, {1: 20}]
+[{1: 30}, {1: 40}]
+NULL
+
+# No input
+query error Error during planning: 'arrays_zip' does not support zero arguments
+select arrays_zip();
+
+# Non-array input
+query error DataFusion error: Execution error: arrays_zip expects array arguments, got Int64
+select arrays_zip(1, 2);
+
+# null input
+query ?
+select arrays_zip(null)
+----
+NULL
+
+# single empty array
+query ?
+select arrays_zip([])
+----
+[]
+
+
+# single array of null
+query ?
+select arrays_zip([null])
+----
+[{1: NULL}]
+
+query ?
+select arrays_zip([NULL::int])
+----
+[{1: NULL}]
+
+query ?
+select arrays_zip([NULL::int[]])
+----
+[{1: NULL}]
+
 # alias: list_zip
 query ?
 select list_zip([1, 2], [3, 4]);
@@ -7346,9 +7398,11 @@ select arrays_zip([42], ['hello']);
 ----
 [{1: 42, 2: hello}]
 
-# error: too few arguments
-statement error
+# single argument
+query ?
 select arrays_zip([1, 2, 3]);
+----
+[{1: 1}, {1: 2}, {1: 3}]
 
 # arrays_zip with LargeList inputs
 query ?
@@ -7368,6 +7422,12 @@ select arrays_zip(
 ----
 [{1: 1, 2: 10}, {1: 2, 2: 20}, {1: NULL, 2: 30}]
 
+# single argument from LargeList
+query ?
+select arrays_zip(arrow_cast(make_array(1, 2, 3), 'LargeList(Int64)'));
+----
+[{1: 1}, {1: 2}, {1: 3}]
+
 # arrays_zip with FixedSizeList inputs
 query ?
 select arrays_zip(
@@ -7377,6 +7437,12 @@ select arrays_zip(
 ----
 [{1: 1, 2: 10}, {1: 2, 2: 20}, {1: 3, 2: 30}]
 
+# single argument from FixedSizeList
+query ?
+select arrays_zip(arrow_cast(make_array(1, 2, 3), 'FixedSizeList(3, Int64)'));
+----
+[{1: 1}, {1: 2}, {1: 3}]
+
 # arrays_zip mixing List and LargeList
 query ?
 select arrays_zip(

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

@@ -4274,29 +4274,28 @@ _Alias of [array_has_any](#array_has_any)._
 Returns an array of structs created by combining the elements of each input array at the same index. If the arrays have different lengths, shorter arrays are padded with NULLs.
 
 ```sql
-arrays_zip(array1, array2[, ..., array_n])
+arrays_zip(array1[, ..., array_n])
 ```
 
 #### Arguments
 
 - **array1**: First array expression.
-- **array2**: Second array expression.
-- **array_n**: Subsequent array expressions.
+- **array_n**: Optional additional array expressions.
 
 #### Example
 
 ```sql
-> select arrays_zip([1, 2, 3], ['a', 'b', 'c']);
+> select arrays_zip([1, 2, 3]);
 +---------------------------------------------------+
-| arrays_zip([1, 2, 3], ['a', 'b', 'c'])             |
+| arrays_zip([1, 2, 3])                             |
 +---------------------------------------------------+
-| [{c0: 1, c1: a}, {c0: 2, c1: b}, {c0: 3, c1: c}] |
+| [{1: 1}, {1: 2}, {1: 3}]                          |
 +---------------------------------------------------+
 > select arrays_zip([1, 2], [3, 4, 5]);
 +---------------------------------------------------+
-| arrays_zip([1, 2], [3, 4, 5])                       |
+| arrays_zip([1, 2], [3, 4, 5])                     |
 +---------------------------------------------------+
-| [{c0: 1, c1: 3}, {c0: 2, c1: 4}, {c0: , c1: 5}]  |
+| [{1: 1, 2: 3}, {1: 2, 2: 4}, {1: NULL, 2: 5}]     |
 +---------------------------------------------------+
 ```