Merge pull request ClickHouse#80194 from Blargian/array_functions_part_5

Docs: array functions source code documentation - part 5

Author: Blargian

src/Functions/array/arrayCompact.cpp

@@ -161,7 +161,18 @@ using FunctionArrayCompact = FunctionArrayMapped<ArrayCompactImpl, NameArrayComp
 
 REGISTER_FUNCTION(ArrayCompact)
 {
-    factory.registerFunction<FunctionArrayCompact>();
+    FunctionDocumentation::Description description = "Removes consecutive duplicate elements from an array, including `null` values. The order of values in the resulting array is determined by the order in the source array.";
+    FunctionDocumentation::Syntax syntax = "arrayCompact(arr)";
+    FunctionDocumentation::Arguments arguments = {
+        {"arr", "An array to remove duplicates from. [`Array(T)`](/sql-reference/data-types/array)"}
+    };
+    FunctionDocumentation::ReturnedValue returned_value = "Returns an array without duplicate values. [`Array(T)`](/sql-reference/data-types/array).";
+    FunctionDocumentation::Examples examples = {{"Usage example", "SELECT arrayCompact([1, 1, nan, nan, 2, 3, 3, 3]);", "[1,nan,2,3]"}};
+    FunctionDocumentation::IntroducedIn introduced_in = {20, 1};
+    FunctionDocumentation::Category category = FunctionDocumentation::Category::Array;
+    FunctionDocumentation documentation = {description, syntax, arguments, returned_value, examples, introduced_in, category};
+
+    factory.registerFunction<FunctionArrayCompact>(documentation);
 }
 
 }

src/Functions/array/arrayFlatten.cpp

@@ -122,7 +122,27 @@ result: Row 1: [1, 2, 3], Row2: [4]
 
 REGISTER_FUNCTION(ArrayFlatten)
 {
-    factory.registerFunction<ArrayFlatten>();
+    FunctionDocumentation::Description description = R"(
+Converts an array of arrays to a flat array.
+
+Function:
+
+- Applies to any depth of nested arrays.
+- Does not change arrays that are already flat.
+
+The flattened array contains all the elements from all source arrays.
+)";
+    FunctionDocumentation::Syntax syntax = "arrayFlatten(arr)";
+    FunctionDocumentation::Arguments arguments = {
+        {"arr", "A multidimensional array. [`Array(T)`](/sql-reference/data-types/array)(`Array`)"}
+    };
+    FunctionDocumentation::ReturnedValue returned_value = "Returns a flattened array from the multidimensional array. [`Array(T)`](/sql-reference/data-types/array).";
+    FunctionDocumentation::Examples examples = {{"Usage example", "SELECT arrayFlatten([[[1]], [[2], [3]]]);", "[1,2,3]"}};
+    FunctionDocumentation::IntroducedIn introduced_in = {20, 1};
+    FunctionDocumentation::Category category = FunctionDocumentation::Category::Array;
+    FunctionDocumentation documentation = {description, syntax, arguments, returned_value, examples, introduced_in, category};
+
+    factory.registerFunction<ArrayFlatten>(documentation);
     factory.registerAlias("flatten", "arrayFlatten", FunctionFactory::Case::Insensitive);
 }
 

src/Functions/array/arrayFold.cpp

@@ -289,9 +289,56 @@ class FunctionArrayFold : public IFunction
 
 REGISTER_FUNCTION(ArrayFold)
 {
-    factory.registerFunction<FunctionArrayFold>(FunctionDocumentation{.description=R"(
-        Function arrayFold(acc,a1,...,aN->expr, arr1, ..., arrN, acc_initial) applies a lambda function to each element
-        in each (equally-sized) array and collects the result in an accumulator.
-        )", .examples{{"sum", "SELECT arrayFold(acc,x->acc+x, [1,2,3,4], toInt64(1));", "11"}}, .category = FunctionDocumentation::Category::Array});
+    FunctionDocumentation::Description description = "Applies a lambda function to one or more equally-sized arrays and collects the result in an accumulator.";
+    FunctionDocumentation::Syntax syntax = "arrayFold(λ(acc, x1 [, x2, x3, ... xN]), arr1 [, arr2, arr3, ... arrN], acc)";
+    FunctionDocumentation::Arguments arguments = {
+        {"λ(x, x1 [, x2, x3, ... xN])", "A lambda function `λ(acc, x1 [, x2, x3, ... xN]) → F(acc, x1 [, x2, x3, ... xN])` where `F` is an operation applied to `acc` and array values from `x` with the result of `acc` re-used. [Lambda function](/sql-reference/functions/overview#arrow-operator-and-lambda)."},
+        {"arr1 [, arr2, arr3, ... arrN]", "N arrays over which to operate. [`Array(T)`](/sql-reference/data-types/array)"},
+        {"acc", "Accumulator value with the same type as the return type of the Lambda function."}
+    };
+    FunctionDocumentation::ReturnedValue returned_value = "Returns the final `acc` value.";
+    FunctionDocumentation::Examples examples = {
+{
+"Usage example",
+"SELECT arrayFold(acc,x -> acc + x*2, [1, 2, 3, 4], 3::Int64) AS res;",
+"23"
+},
+{
+"Fibonacci sequence",
+R"(
+SELECT arrayFold(acc, x -> (acc.2, acc.2 + acc.1),range(number),(1::Int64, 0::Int64)).1 AS fibonacci FROM numbers(1,10);)",
+R"(
+┌─fibonacci─┐
+│         0 │
+│         1 │
+│         1 │
+│         2 │
+│         3 │
+│         5 │
+│         8 │
+│        13 │
+│        21 │
+│        34 │
+└───────────┘
+)"
+},
+{
+"Example using multiple arrays",
+R"(
+SELECT arrayFold(
+(acc, x, y) -> acc + (x * y),
+[1, 2, 3, 4],
+[10, 20, 30, 40],
+0::Int64
+) AS res;
+)",
+"300"
+}
+};
+    FunctionDocumentation::IntroducedIn introduced_in = {23, 10};
+    FunctionDocumentation::Category category = FunctionDocumentation::Category::Array;
+    FunctionDocumentation documentation = {description, syntax, arguments, returned_value, examples, introduced_in, category};
+
+    factory.registerFunction<FunctionArrayFold>(documentation);
 }
 }

src/Functions/array/arrayJaccardIndex.cpp

@@ -151,7 +151,19 @@ class FunctionArrayJaccardIndex : public IFunction
 
 REGISTER_FUNCTION(ArrayJaccardIndex)
 {
-    factory.registerFunction<FunctionArrayJaccardIndex>();
+    FunctionDocumentation::Description description = "Returns the [Jaccard index](https://en.wikipedia.org/wiki/Jaccard_index) of two arrays.";
+    FunctionDocumentation::Syntax syntax = "arrayJaccardIndex(arr_x, arr_y)";
+    FunctionDocumentation::Arguments arguments = {
+        {"arr_x", "First array. [`Array(T)`](/sql-reference/data-types/array)."},
+        {"arr_y", "Second array. [`Array(T)`](/sql-reference/data-types/array)."},
+    };
+    FunctionDocumentation::ReturnedValue returned_value = "Returns the Jaccard index of `arr_x` and `arr_y`.[Float64](/sql-reference/data-types/float)";
+    FunctionDocumentation::Examples examples = {{"Usage example", "SELECT arrayJaccardIndex([1, 2], [2, 3]) AS res", "0.3333333333333333"}};
+    FunctionDocumentation::IntroducedIn introduced_in = {23, 7};
+    FunctionDocumentation::Category category = FunctionDocumentation::Category::Array;
+    FunctionDocumentation documentation = {description, syntax, arguments, returned_value, examples, introduced_in, category};
+
+    factory.registerFunction<FunctionArrayJaccardIndex>(documentation);
 }
 
 }

src/Functions/array/arrayReduce.cpp

@@ -216,7 +216,42 @@ ColumnPtr FunctionArrayReduce::executeImpl(const ColumnsWithTypeAndName & argume
 
 REGISTER_FUNCTION(ArrayReduce)
 {
-    factory.registerFunction<FunctionArrayReduce>();
+    FunctionDocumentation::Description description = R"(
+Applies an aggregate function to array elements and returns its result.
+The name of the aggregation function is passed as a string in single quotes `'max'`, `'sum'`.
+When using parametric aggregate functions, the parameter is indicated after the function name in parentheses `'uniqUpTo(6)'`.
+)";
+    FunctionDocumentation::Syntax syntax = "arrayReduce(agg_f, arr1 [, arr2, ... , arrN)]";
+    FunctionDocumentation::Arguments arguments = {
+        {"agg_f", "The name of an aggregate function which should be a constant [String](/sql-reference/data-types/string)."},
+        {"arr1 [, arr2, ... , arrN)]", "N arrays corresponding to the arguments of `agg_f`. [`Array(T)`](/sql-reference/data-types/array)."},
+    };
+    FunctionDocumentation::ReturnedValue returned_value = "Returns the result of the aggregate function";
+    FunctionDocumentation::Examples examples = {{"Usage example", "SELECT arrayReduce('max', [1, 2, 3]);", R"(
+┌─arrayReduce('max', [1, 2, 3])─┐
+│                             3 │
+└───────────────────────────────┘
+)"},{"Example with aggregate function using multiple arguments", R"(If an aggregate function takes multiple arguments, then this function must be applied to multiple arrays of the same size.
+
+```sql
+SELECT arrayReduce('maxIf', [3, 5], [1, 0]);
+```
+)", R"(
+┌─arrayReduce('maxIf', [3, 5], [1, 0])─┐
+│                                    3 │
+└──────────────────────────────────────┘
+)"},{"Example with a parametric aggregate function", R"(
+SELECT arrayReduce('uniqUpTo(3)', [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
+)", R"(
+┌─arrayReduce('uniqUpTo(3)', [1, 2, 3, 4, 5, 6, 7, 8, 9, 10])─┐
+│                                                           4 │
+└─────────────────────────────────────────────────────────────┘
+)"}};
+    FunctionDocumentation::IntroducedIn introduced_in = {1, 1};
+    FunctionDocumentation::Category category = FunctionDocumentation::Category::Array;
+    FunctionDocumentation documentation = {description, syntax, arguments, returned_value, examples, introduced_in, category};
+
+    factory.registerFunction<FunctionArrayReduce>(documentation);
 }
 
 }

src/Functions/array/arrayReduceInRanges.cpp

@@ -387,7 +387,33 @@ ColumnPtr FunctionArrayReduceInRanges::executeImpl(
 
 REGISTER_FUNCTION(ArrayReduceInRanges)
 {
-    factory.registerFunction<FunctionArrayReduceInRanges>();
+    FunctionDocumentation::Description description = R"(
+Applies an aggregate function to array elements in the given ranges and returns an array containing the result corresponding to each range.
+The function will return the same result as multiple `arrayReduce(agg_func, arraySlice(arr1, index, length), ...)`.
+)";
+    FunctionDocumentation::Syntax syntax = "arrayReduceInRanges(agg_f, ranges, arr1 [, arr2, ... ,arrN)]";
+    FunctionDocumentation::Arguments arguments = {
+        {"agg_f", "The name of the aggregate function to use. [String](/sql-reference/data-types/string)"},
+        {"ranges", "The range over which to aggregate. An array of tuples, `(i, r)` containing the index `i` from which to begin from and the range `r` over which to aggregate [`Array(T)`](/sql-reference/data-types/array)([`Tuple(T1, T2, ...)`](/sql-reference/data-types/tuple))"},
+        {"arr1 [, arr2, ... ,arrN)]", "N arrays as arguments to the aggregate function. [`Array(T)`](/sql-reference/data-types/array)."},
+    };
+    FunctionDocumentation::ReturnedValue returned_value = "Returns an array containing results of the aggregate function over the specified ranges. [`Array(T)`](/sql-reference/data-types/array).";
+    FunctionDocumentation::Examples examples = {{"Usage example", R"(
+SELECT arrayReduceInRanges(
+    'sum',
+    [(1, 5), (2, 3), (3, 4), (4, 4)],
+    [1000000, 200000, 30000, 4000, 500, 60, 7]
+) AS res)", R"(
+┌─res─────────────────────────┐
+│ [1234500,234000,34560,4567] │
+└─────────────────────────────┘
+)"}
+    };
+    FunctionDocumentation::IntroducedIn introduced_in = {20, 4};
+    FunctionDocumentation::Category category = FunctionDocumentation::Category::Array;
+    FunctionDocumentation documentation = {description, syntax, arguments, returned_value, examples, introduced_in, category};
+
+    factory.registerFunction<FunctionArrayReduceInRanges>(documentation);
 }
 
 }

src/Functions/array/arrayReverse.cpp

@@ -246,7 +246,25 @@ bool FunctionArrayReverse::executeString(const IColumn & src_data, const ColumnA
 
 REGISTER_FUNCTION(ArrayReverse)
 {
-    factory.registerFunction<FunctionArrayReverse>();
+    FunctionDocumentation::Description description = R"(
+Reverses the order of elements of a given array.
+
+:::note
+Function `reverse(arr)` performs the same functionality but works on other data-types
+in addition to Arrays.
+:::
+)";
+    FunctionDocumentation::Syntax syntax = "arrayReverse(arr)";
+    FunctionDocumentation::Arguments arguments = {
+        {"arr", "The array to reverse. [`Array(T)`](/sql-reference/data-types/array)."}
+    };
+    FunctionDocumentation::ReturnedValue returned_value = "Returns an array of the same size as the original array containing the elements in reverse order. [`Array(T)`](/sql-reference/data-types/array).";
+    FunctionDocumentation::Examples examples = {{"Usage example", "SELECT arrayReverse([1, 2, 3])", "[3,2,1]"}};
+    FunctionDocumentation::IntroducedIn introduced_in = {1, 1};
+    FunctionDocumentation::Category category = FunctionDocumentation::Category::Array;
+    FunctionDocumentation documentation = {description, syntax, arguments, returned_value, examples, introduced_in, category};
+
+    factory.registerFunction<FunctionArrayReverse>(documentation);
 }
 
 }

src/Functions/array/arrayZip.cpp

@@ -171,21 +171,27 @@ class FunctionArrayZip : public IFunction
 
 REGISTER_FUNCTION(ArrayZip)
 {
-    factory.registerFunction<FunctionArrayZip<false>>(
-        {.description = R"(
-Combines multiple arrays into a single array. The resulting array contains the corresponding elements of the source arrays grouped into tuples in the listed order of arguments.
-)",
-         .category = FunctionDocumentation::Category::Array});
-
-    factory.registerFunction<FunctionArrayZip<true>>(
-        {.description = R"(
-Combines multiple arrays into a single array, allowing for unaligned arrays. The resulting array contains the corresponding elements of the source arrays grouped into tuples in the listed order of arguments.
-
-If the arrays have different sizes, the shorter arrays will be padded with `null` values.
-)",
-         .category = FunctionDocumentation::Category::Array}
-
-    );
+    FunctionDocumentation::Description description = "Combines multiple arrays into a single array. The resulting array contains the corresponding elements of the source arrays grouped into tuples in the listed order of arguments.";
+    FunctionDocumentation::Syntax syntax = "arrayZip(arr1, arr2, ... , arrN)";
+    FunctionDocumentation::Arguments argument = {{"arr1, arr2, ... , arrN", "N arrays to combine into a single array. [`Array(T)`](/sql-reference/data-types/array)"}};
+    FunctionDocumentation::ReturnedValue returned_value = "Returns an array with elements from the source arrays grouped in tuples. Data types in the tuple are the same as types of the input arrays and in the same order as arrays are passed. [`Array(T)`](/sql-reference/data-types/array)([`Tuple`](/sql-reference/data-types/tuple)).";
+    FunctionDocumentation::Examples example = {{"Usage example", "SELECT arrayZip(['a', 'b', 'c'], [5, 2, 1]);", "[('a', 5), ('b', 2), ('c', 1)]"}};
+    FunctionDocumentation::IntroducedIn introduced_in = {20, 1};
+    FunctionDocumentation::Category category = FunctionDocumentation::Category::Array;
+    FunctionDocumentation documentation = {description, syntax, argument, returned_value, example, introduced_in, category};
+
+    factory.registerFunction<FunctionArrayZip<false>>(documentation);
+
+    FunctionDocumentation::Description description_unaligned = "Combines multiple arrays into a single array, allowing for unaligned arrays (arrays of differing lengths). The resulting array contains the corresponding elements of the source arrays grouped into tuples in the listed order of arguments.";
+    FunctionDocumentation::Syntax syntax_unaligned = "arrayZipUnaligned(arr1, arr2, ..., arrN)";
+    FunctionDocumentation::Arguments argument_unaligned = {{"arr1, arr2, ..., arrN", "N arrays to combine into a single array. [`Array(T)`](/sql-reference/data-types/array)."}};
+    FunctionDocumentation::ReturnedValue returned_value_unaligned = "Returns an array with elements from the source arrays grouped in tuples. Data types in the tuple are the same as types of the input arrays and in the same order as arrays are passed. [`Array(T)`](/sql-reference/data-types/array)([`Tuple(T1, T2, ...)`](/sql-reference/data-types/tuple)).";
+    FunctionDocumentation::Examples example_unaligned = {{"Usage example", "SELECT arrayZipUnaligned(['a'], [1, 2, 3]);", "[('a', 1),(NULL, 2),(NULL, 3)]"}};
+    FunctionDocumentation::IntroducedIn introduced_in_unaligned = {20, 1};
+    FunctionDocumentation::Category category_unaligned = FunctionDocumentation::Category::Array;
+    FunctionDocumentation documentation_unaligned = {description_unaligned, syntax_unaligned, argument_unaligned, returned_value_unaligned, example_unaligned, introduced_in_unaligned, category_unaligned};
+
+    factory.registerFunction<FunctionArrayZip<true>>(documentation_unaligned);
 }
 
 }

tests/queries/0_stateless/02415_all_new_functions_must_be_documented.reference

@@ -92,7 +92,6 @@ array
 arrayAUCPR
 arrayAll
 arrayAvg
-arrayCompact
 arrayConcat
 arrayCount
 arrayCumSum
@@ -108,8 +107,6 @@ arrayFilter
 arrayFirst
 arrayFirstIndex
 arrayFirstOrNull
-arrayFlatten
-arrayJaccardIndex
 arrayLast
 arrayLastIndex
 arrayLastOrNull
@@ -119,9 +116,6 @@ arrayMin
 arrayProduct
 arrayROCAUC
 arrayRandomSample
-arrayReduce
-arrayReduceInRanges
-arrayReverse
 arrayReverseFill
 arrayReverseSplit
 arraySplit

tests/queries/0_stateless/02415_all_new_functions_must_have_version_information.reference

@@ -108,7 +108,6 @@ array
 arrayAUCPR
 arrayAll
 arrayAvg
-arrayCompact
 arrayConcat
 arrayCount
 arrayCumSum
@@ -126,9 +125,6 @@ arrayFilter
 arrayFirst
 arrayFirstIndex
 arrayFirstOrNull
-arrayFlatten
-arrayFold
-arrayJaccardIndex
 arrayLast
 arrayLastIndex
 arrayLastOrNull
@@ -140,9 +136,6 @@ arrayMin
 arrayProduct
 arrayROCAUC
 arrayRandomSample
-arrayReduce
-arrayReduceInRanges
-arrayReverse
 arrayReverseFill
 arrayReverseSplit
 arrayRotateLeft
@@ -154,8 +147,6 @@ arraySplit
 arrayStringConcat
 arraySum
 arrayWithConstant
-arrayZip
-arrayZipUnaligned
 ascii
 asin
 asinh