Merge pull request ClickHouse#80124 from Blargian/array_functions_part_2

Docs: Array functions source code documentation - part 2

Author: rschu1ze

src/Functions/array/arrayCount.cpp

@@ -81,6 +81,23 @@ using FunctionArrayCount = FunctionArrayMapped<ArrayCountImpl, NameArrayCount>;
 
 REGISTER_FUNCTION(ArrayCount)
 {
+    FunctionDocumentation::Description description = R"(
+Returns the number of elements for which `func(arr1[i], ..., arrN[i])` returns something other than `0`.
+If `func` is not specified, it returns the number of non-zero elements in the array.
+
+`arrayCount` is a [higher-order function](/sql-reference/functions/overview#higher-order-functions).
+    )";
+    FunctionDocumentation::Syntax syntax = "arrayCount([func, ] arr1, ...)";
+    FunctionDocumentation::Arguments arguments = {
+        {"func", "Function to apply to each element of the array(s). Optional. [Lambda function](/sql-reference/functions/overview#arrow-operator-and-lambda)"},
+        {"arr1, ..., arrN", "N arrays. [Array(T)](/sql-reference/data-types/array)."},
+    };
+    FunctionDocumentation::ReturnedValue returned_value = "Returns the number of elements for which `func` returns something other than `0`. Otherwise, returns the number of non-zero elements in the array.";
+    FunctionDocumentation::Examples example = {{"Usage example", "SELECT arrayCount(x -> (x % 2), groupArray(number) FROM numbers(10)", "5"}};
+    FunctionDocumentation::IntroducedIn introduced_in = {1, 1};
+    FunctionDocumentation::Category category = FunctionDocumentation::Category::Array;
+    FunctionDocumentation documentation = {description, syntax, arguments, returned_value, example, introduced_in, category};
+
     factory.registerFunction<FunctionArrayCount>();
 }
 

src/Functions/array/arrayDotProduct.cpp

@@ -385,6 +385,33 @@ using FunctionArrayDotProduct = FunctionArrayScalarProduct<DotProduct>;
 
 REGISTER_FUNCTION(ArrayDotProduct)
 {
+    FunctionDocumentation::Description description = R"(
+Returns the dot product of two arrays.
+
+:::note
+The sizes of the two vectors must be equal. Arrays and Tuples may also contain mixed element types.
+:::
+)";
+    FunctionDocumentation::Syntax syntax = "arrayDotProduct(v1, v2)";
+    FunctionDocumentation::Arguments arguments = {
+        {"v1", "First vector. [Array(T)](/sql-reference/data-types/array) or [Tuple(T1, T2, ...)](../data-types/tuple.md) of numeric values."},
+        {"v2", "Second vector. [Array(T)](/sql-reference/data-types/array) or [Tuple(T1, T2, ...)](../data-types/tuple.md) of numeric values."},
+    };
+    FunctionDocumentation::ReturnedValue returned_value = R"(
+The dot product of the two vectors. [Numeric](/native-protocol/columns#numeric-types).
+
+:::note
+The return type is determined by the type of the arguments. If Arrays or Tuples contain mixed element types then the result type is the supertype.
+:::
+)";
+    FunctionDocumentation::Examples examples = {
+        {"Array example", "SELECT arrayDotProduct([1, 2, 3], [4, 5, 6]) AS res, toTypeName(res);", "32    UInt16"},
+        {"Tuple example", "SELECT dotProduct((1::UInt16, 2::UInt8, 3::Float32),(4::Int16, 5::Float32, 6::UInt8)) AS res, toTypeName(res);", "32    Float64"}
+    };
+    FunctionDocumentation::IntroducedIn introduced_in = {23, 5};
+    FunctionDocumentation::Category category = FunctionDocumentation::Category::Array;
+    FunctionDocumentation documentation = {description, syntax, arguments, returned_value, examples, introduced_in, category};
+
     factory.registerFunction<FunctionArrayDotProduct>();
 }
 

src/Functions/array/arrayEnumerate.cpp

@@ -76,7 +76,52 @@ class FunctionArrayEnumerate : public IFunction
 
 REGISTER_FUNCTION(ArrayEnumerate)
 {
-    factory.registerFunction<FunctionArrayEnumerate>();
+    FunctionDocumentation::Description description = R"(
+Returns the array `[1, 2, 3, ..., length (arr)]`
+
+This function is normally used with the [`ARRAY JOIN`](/sql-reference/statements/select/array-join) clause. It allows counting something just
+once for each array after applying `ARRAY JOIN`.
+This function can also be used in higher-order functions. For example, you can use it to get array indexes for elements that match a condition.
+)";
+    FunctionDocumentation::Syntax syntax = "arrayEnumerate(arr)";
+    FunctionDocumentation::Arguments arguments = {
+        {"arr", "The array to enumerate. [`Array`](/sql-reference/data-types/array)."}
+    };
+    FunctionDocumentation::ReturnedValue returned_value = "Returns the array `[1, 2, 3, ..., length (arr)]`. Array(UInt32)";
+    FunctionDocumentation::Examples examples = {{"Basic example with ARRAY JOIN", R"(
+CREATE TABLE test
+(
+    `id` UInt8,
+    `tag` Array(String),
+    `version` Array(String)
+)
+ENGINE = MergeTree
+ORDER BY id;
+
+INSERT INTO test VALUES (1, ['release-stable', 'dev', 'security'], ['2.4.0', '2.6.0-alpha', '2.4.0-sec1']);
+
+SELECT
+    id,
+    tag,
+    version,
+    seq
+FROM test
+ARRAY JOIN
+    tag,
+    version,
+    arrayEnumerate(tag) AS seq
+    )", R"(
+┌─id─┬─tag────────────┬─version─────┬─seq─┐
+│  1 │ release-stable │ 2.4.0       │   1 │
+│  1 │ dev            │ 2.6.0-alpha │   2 │
+│  1 │ security       │ 2.4.0-sec1  │   3 │
+└────┴────────────────┴─────────────┴─────┘
+    )"}};
+    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<FunctionArrayEnumerate>(documentation);
 }
 
 }

src/Functions/array/arrayEnumerateUniqRanked.cpp

@@ -16,7 +16,57 @@ class FunctionArrayEnumerateUniqRanked : public FunctionArrayEnumerateRankedExte
 
 REGISTER_FUNCTION(ArrayEnumerateUniqRanked)
 {
-    factory.registerFunction<FunctionArrayEnumerateUniqRanked>();
+    FunctionDocumentation::Description description = R"(
+Returns an array (or multi-dimensional array) with the same dimensions as the source array,
+indicating for each element what it's position is among elements with the same value.
+It allows for enumeration of a multi-dimensional array with the ability to specify how deep to look inside the array.
+)";
+    FunctionDocumentation::Syntax syntax = "arrayEnumerateUniqRanked(clear_depth, arr, max_array_depth)";
+    FunctionDocumentation::Arguments arguments = {
+        {"clear_depth", "Enumerate elements at the specified level separately. Positive [Integer](../data-types/int-uint.md) less than or equal to `max_arr_depth`."},
+        {"arr", "N-dimensional array to enumerate. [Array](/sql-reference/data-types/array)."},
+        {"max_array_depth", "The maximum effective depth. Positive [Integer](../data-types/int-uint.md) less than or equal to the depth of `arr`."}
+    };
+    FunctionDocumentation::ReturnedValue returned_value = "Returns an N-dimensional array the same size as `arr` with each element showing the position of that element in relation to other elements of the same value.";
+    FunctionDocumentation::Examples examples = {
+        {"Example 1", R"(
+With `clear_depth=1` and `max_array_depth=1`, the result of `arrayEnumerateUniqRanked` is identical to that which [`arrayEnumerateUniq`](#arrayenumerateuniq) would give for the same array.
+
+```sql
+SELECT arrayEnumerateUniqRanked(1, [1,2,1], 1);
+```
+        )", "[1,1,2]"},
+        {"Example 2", R"(
+
+With `clear_depth=1` and `max_array_depth=1`, the result of `arrayEnumerateUniqRanked` is identical to that which [`arrayEnumerateUniq`](#arrayenumerateuniq) would give for the same array.
+
+```sql
+SELECT arrayEnumerateUniqRanked(1, [[1,2,3],[2,2,1],[3]], 2);", "[[1,1,1],[2,3,2],[2]]
+```
+)", "[1,1,2]"},
+        {"Example 3", R"(
+
+In this example, `arrayEnumerateUniqRanked` is used to obtain an array indicating, for each element of the multidimensional array, what its position is among elements of the same value. For the first row of the passed array,`[1,2,3]`, the corresponding result is `[1,1,1]`, indicating that this is the first time `1`,`2` and `3` are encountered. For the second row of the provided array,`[2,2,1]`, the corresponding result is `[2,3,3]`, indicating that `2` is encountered for a second and third time, and `1` is encountered for the second time. Likewise, for the third row of the provided array `[3]` the corresponding result is `[2]` indicating that `3` is encountered for the second time.
+
+```sql
+SELECT arrayEnumerateUniqRanked(1, [[1,2,3],[2,2,1],[3]], 2);
+```
+        )", "[[1,1,1],[2,3,2],[2]]"
+    },
+    {"Example 4", R"(
+
+Changing `clear_depth=2`, results in elements being enumerated separately for each row.
+
+```sql
+SELECT arrayEnumerateUniqRanked(2, [[1,2,3],[2,2,1],[3]], 2);
+```
+        )", "[[1,1,1],[1,2,1],[1]]"},
+};
+    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<FunctionArrayEnumerateUniqRanked>(documentation);
 }
 
 }

src/Functions/array/arrayPopBack.cpp

@@ -15,7 +15,16 @@ class FunctionArrayPopBack : public FunctionArrayPop
 
 REGISTER_FUNCTION(ArrayPopBack)
 {
-    factory.registerFunction<FunctionArrayPopBack>();
+    FunctionDocumentation::Description description = "Removes the last element from the array.";
+    FunctionDocumentation::Syntax syntax = "arrayPopBack(arr)";
+    FunctionDocumentation::Arguments arguments = {{"arr", "The array for which to remove the last element from. [`Array(T)`](/sql-reference/data-types/array)."}};
+    FunctionDocumentation::ReturnedValue returned_value = "Returns an array identical to `arr` but without the last element of `arr`. [`Array(T)`](/sql-reference/data-types/array).";
+    FunctionDocumentation::Examples examples = {{"Usage example", "SELECT arrayPopBack([1, 2, 3]) AS res;", "[1,2]"}};
+    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<FunctionArrayPopBack>(documentation);
 }
 
 }

src/Functions/array/arrayPopFront.cpp

@@ -15,7 +15,16 @@ class FunctionArrayPopFront : public FunctionArrayPop
 
 REGISTER_FUNCTION(ArrayPopFront)
 {
-    factory.registerFunction<FunctionArrayPopFront>();
+    FunctionDocumentation::Description description = "Removes the first item from the array.";
+    FunctionDocumentation::Syntax syntax = "arrayPopFront(arr)";
+    FunctionDocumentation::Arguments arguments = {{"arr", "The array for which to remove the first element from. [`Array(T)`](/sql-reference/data-types/array)."}};
+    FunctionDocumentation::ReturnedValue returned_value = "Returns an array identical to `arr` but without the first element of `arr`. [`Array(T)`](/sql-reference/data-types/array).";
+    FunctionDocumentation::Examples examples = {{"Usage example", "SELECT arrayPopFront([1, 2, 3]) AS res;", "[2,3]"}};
+    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<FunctionArrayPopFront>(documentation);
 }
 
 }

src/Functions/array/arrayPushBack.cpp

@@ -15,7 +15,29 @@ class FunctionArrayPushBack : public FunctionArrayPush
 
 REGISTER_FUNCTION(ArrayPushBack)
 {
-    factory.registerFunction<FunctionArrayPushBack>();
+    FunctionDocumentation::Description description = "Adds one item to the end of the array.";
+    FunctionDocumentation::Syntax syntax = "arrayPushBack(arr, x)";
+    FunctionDocumentation::Arguments arguments = {
+        {"arr", "The array for which to add value `x` to the end of. [`Array(T)`](/sql-reference/data-types/array)."},
+        {"x", R"(
+- Single value to add to the end of the array. [`Array(T)`](/sql-reference/data-types/array).
+
+:::note
+- Only numbers can be added to an array with numbers, and only strings can be added to an array of strings.
+- When adding numbers, ClickHouse automatically sets the type of `x` for the data type of the array.
+- Can be `NULL`. The function adds a `NULL` element to an array, and the type of array elements converts to `Nullable`.
+
+For more information about the types of data in ClickHouse, see [Data types](/sql-reference/data-types).
+:::
+    )"},
+    };
+    FunctionDocumentation::ReturnedValue returned_value = "Returns an array identical to `arr` but with an additional value `x` at the end of the array. [`Array(T)`](/sql-reference/data-types/array).";
+    FunctionDocumentation::Examples examples = {{"Usage example", "SELECT arrayPushBack(['a'], 'b') AS res;", "['a','b']"}};
+    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<FunctionArrayPushBack>(documentation);
 }
 
 }

src/Functions/array/arrayPushFront.cpp

@@ -17,7 +17,29 @@ class FunctionArrayPushFront : public FunctionArrayPush
 
 REGISTER_FUNCTION(ArrayPushFront)
 {
-    factory.registerFunction<FunctionArrayPushFront>();
+    FunctionDocumentation::Description description = "Adds one element to the beginning of the array.";
+    FunctionDocumentation::Syntax syntax = "arrayPushFront(arr, x)";
+    FunctionDocumentation::Arguments arguments = {
+        {"arr", "The array for which to add value `x` to the end of. [`Array(T)`](/sql-reference/data-types/array)."},
+        {"x", R"(
+- Single value to add to the start of the array. [`Array(T)`](/sql-reference/data-types/array).
+
+:::note
+- Only numbers can be added to an array with numbers, and only strings can be added to an array of strings.
+- When adding numbers, ClickHouse automatically sets the type of `x` for the data type of the array.
+- Can be `NULL`. The function adds a `NULL` element to an array, and the type of array elements converts to `Nullable`.
+
+For more information about the types of data in ClickHouse, see [Data types](/sql-reference/data-types).
+:::
+    )"},
+    };
+    FunctionDocumentation::ReturnedValue returned_value = "Returns an array identical to `arr` but with an additional value `x` at the beginning of the array. [`Array(T)`](/sql-reference/data-types/array).";
+    FunctionDocumentation::Examples examples = {{"Usage example", "SELECT arrayPushFront(['b'], 'a') AS res;", "['a','b']"}};
+    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<FunctionArrayPushFront>(documentation);
 }
 
 }

src/Functions/array/countEqual.cpp

@@ -9,6 +9,22 @@ using FunctionCountEqual = FunctionArrayIndex<CountEqualAction, NameCountEqual>;
 
 REGISTER_FUNCTION(CountEqual)
 {
-    factory.registerFunction<FunctionCountEqual>();
+    FunctionDocumentation::Description description = R"(
+Returns the number of elements in the array equal to `x`. Equivalent to `arrayCount(elem -> elem = x, arr)`.
+
+`NULL` elements are handled as separate values.
+)";
+    FunctionDocumentation::Syntax syntax = "countEqual(arr, x)";
+    FunctionDocumentation::Arguments arguments = {
+        {"arr", "Array to search. [`Array(T)`](/sql-reference/data-types/array)."},
+        {"x", "Value in the array to count. Any type."}
+    };
+    FunctionDocumentation::ReturnedValue returned_value = "Returns the number of elements in the array equal to `x`. [UInt64](/sql-reference/data-types/int-uint).";
+    FunctionDocumentation::Examples example = {{"Usage example", "SELECT countEqual([1, 2, NULL, NULL], NULL)", "2"}};
+    FunctionDocumentation::IntroducedIn introduced_in = {1, 1};
+    FunctionDocumentation::Category category = FunctionDocumentation::Category::Array;
+    FunctionDocumentation documentation = {description, syntax, arguments, returned_value, example, introduced_in, category};
+
+    factory.registerFunction<FunctionCountEqual>(documentation);
 }
 }

src/Functions/array/hasAll.cpp

@@ -16,7 +16,37 @@ class FunctionArrayHasAll : public FunctionArrayHasAllAny
 
 REGISTER_FUNCTION(HasAll)
 {
-    factory.registerFunction<FunctionArrayHasAll>();
+    FunctionDocumentation::Description description = R"(
+Checks whether one array is a subset of another.
+
+- An empty array is a subset of any array.
+- `Null` is processed as a value.
+- The order of values in both the arrays does not matter.
+)";
+    FunctionDocumentation::Syntax syntax = "hasAll(set, subset)";
+    FunctionDocumentation::Arguments arguments = {
+        {"set", "Array of any type with a set of elements. [`Array`](/sql-reference/data-types/array)."},
+        {"subset", "Array of any type that shares a common supertype with `set` containing elements that should be tested to be a subset of `set`. [`Array`](/sql-reference/data-types/array)."},
+    };
+    FunctionDocumentation::ReturnedValue returned_value = R"(
+- `1`, if `set` contains all of the elements from `subset`.
+- `0`, otherwise.
+
+Raises a `NO_COMMON_TYPE` exception if the set and subset elements do not share a common supertype.
+)";
+    FunctionDocumentation::Examples examples = {
+        {"Empty arrays", "SELECT hasAll([], [])", "1"},
+        {"Arrays containing NULL values", "SELECT hasAll([1, Null], [Null])", "1"},
+        {"Arrays containing values of a different type", "SELECT hasAll([1.0, 2, 3, 4], [1, 3])", "1"},
+        {"Arrays containing String values", "SELECT hasAll(['a', 'b'], ['a'])", "1"},
+        {"Arrays without a common type", "SELECT hasAll([1], ['a'])", "Raises a NO_COMMON_TYPE exception"},
+        {"Array of arrays", "SELECT hasAll([[1, 2], [3, 4]], [[1, 2], [3, 5]])", "0"},
+    };
+    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<FunctionArrayHasAll>(documentation);
 }
 
 }