Merge pull request ClickHouse#80115 from Blargian/array_functions_part_1

Docs: Array functions source code documentation - part 1

Author: Blargian

src/Functions/array/array.cpp

@@ -287,7 +287,42 @@ class FunctionArray : public IFunction
 
 REGISTER_FUNCTION(Array)
 {
-    factory.registerFunction<FunctionArray>();
+    FunctionDocumentation::Description description = R"(
+Creates an array from the function arguments.
+
+The arguments should be constants and have types that share a common supertype.
+At least one argument must be passed, because otherwise it isn't clear which type of array to create.
+This means that you can't use this function to create an empty array. To do so, use the `emptyArray*` function.
+
+Use the `[ ]` operator for the same functionality.
+    )";
+    FunctionDocumentation::Syntax syntax = "array(x1 [, x2, ..., xN])";
+    FunctionDocumentation::Arguments arguments = {
+        {"x1", "Constant value of any type T. If only this argument is provided, the array will be of type T."},
+        {"[, x2, ..., xN]", "Additional N constant values sharing a common supertype with `x1`"},
+    };
+    FunctionDocumentation::ReturnedValue returned_value = "Returns an 'Array(T)' type result, where 'T' is the smallest common type out of the passed arguments.";
+    FunctionDocumentation::Examples examples = {{"Valid usage", R"(
+SELECT array(toInt32(1), toUInt16(2), toInt8(3)) AS a, toTypeName(a)
+    )",
+    R"(
+┌─a───────┬─toTypeName(a)─┐
+│ [1,2,3] │ Array(Int32)  │
+└─────────┴───────────────┘
+    )"},
+    {"Invalid usage", R"(
+SELECT array(toInt32(5), toDateTime('1998-06-16'), toInt8(5)) AS a, toTypeName(a)
+    )",
+R"(
+Received exception from server (version 25.4.3):
+Code: 386. DB::Exception: Received from localhost:9000. DB::Exception:
+There is no supertype for types Int32, DateTime, Int8 ...
+    )"}};
+    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<FunctionArray>(documentation);
 }
 
 }

src/Functions/array/arrayConcat.cpp

@@ -80,6 +80,17 @@ ColumnPtr FunctionArrayConcat::executeImpl(const ColumnsWithTypeAndName & argume
 
 REGISTER_FUNCTION(ArrayConcat)
 {
+    FunctionDocumentation::Description description = "Combines arrays passed as arguments.";
+    FunctionDocumentation::Syntax syntax = "arrayConcat(arr1 [, arr2, ... , arrN])";
+    FunctionDocumentation::Arguments arguments = {
+        {"arr1 [, arr2, ... , arrN]", "N number of arrays to concatenate. [`Array(T)`](/sql-reference/data-types/array)."}
+    };
+    FunctionDocumentation::ReturnedValue returned_value = "Returns a single combined array from the provided array arguments.";
+    FunctionDocumentation::Examples example = {{"Usage example", "SELECT arrayConcat([1, 2], [3, 4], [5, 6]) AS res", "[1,2,3,4,5,6]"}};
+    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<FunctionArrayConcat>();
 }
 

src/Functions/array/arrayElement.cpp

@@ -2202,23 +2202,61 @@ ColumnPtr FunctionArrayElement<mode>::perform(
 
 REGISTER_FUNCTION(ArrayElement)
 {
-    factory.registerFunction<FunctionArrayElement<ArrayElementExceptionMode::Zero>>(FunctionDocumentation{
-        .description = R"(
-Get the element with the index `n` from the array `arr`. `n` must be any integer type. Indexes in an array begin from one.
+    FunctionDocumentation::Description description = R"(
+Gets the element of the provided array with index `n` where `n` can be any integer type.
+If the index falls outside of the bounds of an array, it returns a default value (0 for numbers, an empty string for strings, etc.),
+except for arguments of a non-constant array and a constant index 0. In this case there will be an error `Array indices are 1-based`.
+
+:::note
+Arrays in ClickHouse are one-indexed.
+:::
+
+Negative indexes are supported. In this case, the corresponding element is selected, numbered from the end. For example, `arr[-1]` is the last item in the array.
+
+Operator `[n]` provides the same functionality.
+    )";
+    FunctionDocumentation::Syntax syntax = "arrayElement(arr, n)";
+    FunctionDocumentation::Arguments arguments = {
+        {"arr", "The array to search. [`Array(T)`](/sql-reference/data-types/array)."},
+        {"n", "Position of the element to get. [`(U)Int*`](/sql-reference/data-types/int-uint)."}
+    };
+    FunctionDocumentation::ReturnedValue returned_value = "Returns a single combined array from the provided array arguments. [`Array(T)`](/sql-reference/data-types/array).";
+    FunctionDocumentation::Examples examples = {
+        {"Usage example", "SELECT arrayElement(arr, 2) FROM (SELECT [1, 2, 3] AS arr)", "2"},
+        {"Negative indexing", "SELECT arrayElement(arr, -1) FROM (SELECT [1, 2, 3] AS arr)", "3"},
+        {"Using [n] notation", "SELECT arr[2] FROM (SELECT [1, 2, 3] AS arr)", "2"},
+        {"Index out of array bounds", "SELECT arrayElement(arr, 4) FROM (SELECT [1, 2, 3] AS arr)", "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<FunctionArrayElement<ArrayElementExceptionMode::Zero>>(documentation);
+
+    FunctionDocumentation::Description description_null = R"(
+Gets the element of the provided array with index `n` where `n` can be any integer type.
+If the index falls outside of the bounds of an array, `NULL` is returned instead of a default value.
+
+:::note
+Arrays in ClickHouse are one-indexed.
+:::
 
 Negative indexes are supported. In this case, it selects the corresponding element numbered from the end. For example, `arr[-1]` is the last item in the array.
-
-If the index falls outside of the bounds of an array, it returns some default value (0 for numbers, an empty string for strings, etc.), except for the case with a non-constant array and a constant index 0 (in this case there will be an error `Array indices are 1-based`).
-        )",
-        .category = FunctionDocumentation::Category::Array});
-    factory.registerFunction<FunctionArrayElement<ArrayElementExceptionMode::Null>>(FunctionDocumentation{
-        .description = R"(
-Get the element with the index `n`from the array `arr`. `n` must be any integer type. Indexes in an array begin from one.
-
-Negative indexes are supported. In this case, it selects the corresponding element numbered from the end. For example, `arr[-1]` is the last item in the array.
-
-If the index falls outside of the bounds of an array, it returns `NULL` instead of a default value.
-        )",
-        .category = FunctionDocumentation::Category::Array});
+)";
+    FunctionDocumentation::Syntax syntax_null = "arrayElementOrNull(arrays)";
+    FunctionDocumentation::Arguments arguments_null = {
+        {"arrays", "Arbitrary number of arguments of [`Array`](/sql-reference/data-types/array) type."}
+    };
+    FunctionDocumentation::ReturnedValue returned_value_null = "Returns a single combined array from the provided array arguments.";
+    FunctionDocumentation::Examples examples_null = {
+        {"Usage example", "SELECT arrayElementOrNull(arr, 2) FROM (SELECT [1, 2, 3] AS arr)", "2"},
+        {"Negative indexing", "SELECT arrayElementOrNull(arr, -1) FROM (SELECT [1, 2, 3] AS arr)", "3"},
+        {"Index out of array bounds", "SELECT arrayElementOrNull(arr, 4) FROM (SELECT [1, 2, 3] AS arr)", "NULL"}
+    };
+    FunctionDocumentation::IntroducedIn introduced_in_null = {1, 1};
+    FunctionDocumentation::Category category_null = FunctionDocumentation::Category::Array;
+    FunctionDocumentation documentation_null = {description_null, syntax_null, arguments_null, returned_value_null, examples_null, introduced_in_null, category_null};
+
+    factory.registerFunction<FunctionArrayElement<ArrayElementExceptionMode::Null>>(documentation_null);
 }
 }

src/Functions/array/arrayWithConstant.cpp

@@ -88,7 +88,21 @@ class FunctionArrayWithConstant : public IFunction
 
 REGISTER_FUNCTION(ArrayWithConstant)
 {
-    factory.registerFunction<FunctionArrayWithConstant>();
+    FunctionDocumentation::Description description = R"(
+Creates an array of length `length` filled with the constant `x`.
+    )";
+    FunctionDocumentation::Syntax syntax = "arrayWithConstant(N, x)";
+    FunctionDocumentation::Arguments arguments = {
+        {"length", "Number of elements in the array. [`(U)Int*`](/sql-reference/data-types/int-uint)."},
+        {"x", "The value of the `N` elements in the array, of any type."},
+    };
+    FunctionDocumentation::ReturnedValue returned_value = "Returns an Array with `N` elements of value `x`.";
+    FunctionDocumentation::Examples example = {{"Usage example", "SELECT arrayWithConstant(3, 1)", "[1,1,1]"}};
+    FunctionDocumentation::IntroducedIn introduced_in = {20, 1};
+    FunctionDocumentation::Category category = FunctionDocumentation::Category::Array;
+    FunctionDocumentation documentation = {description, syntax, arguments, returned_value, example, introduced_in, category};
+
+    factory.registerFunction<FunctionArrayWithConstant>(documentation);
 }
 
 }

src/Functions/array/emptyArray.cpp

@@ -48,8 +48,20 @@ class FunctionEmptyArray : public IFunction
 
 void registerFunction(FunctionFactory & factory, const String & element_type)
 {
-    factory.registerFunction(FunctionEmptyArray::getNameImpl(element_type),
-        [element_type](ContextPtr){ return std::make_shared<FunctionEmptyArray>(element_type); });
+    FunctionDocumentation::Description description = fmt::format("Returns an empty {} array", element_type);
+    FunctionDocumentation::Syntax syntax = fmt::format("emptyArray{}()", element_type);
+    FunctionDocumentation::Arguments arguments = {{"", ""}};
+    FunctionDocumentation::ReturnedValue returned_value = fmt::format("An empty {} array. [`Array(T)`](/sql-reference/data-types/array).", element_type);
+    FunctionDocumentation::Examples examples = {{"Usage example", fmt::format("SELECT emptyArray{}", element_type), "[]"}};
+    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(
+        FunctionEmptyArray::getNameImpl(element_type),
+        [element_type](ContextPtr){ return std::make_shared<FunctionEmptyArray>(element_type); },
+        documentation
+    );
 }
 
 }

src/Functions/array/emptyArrayToSingle.cpp

@@ -392,7 +392,34 @@ ColumnPtr FunctionEmptyArrayToSingle::executeImpl(const ColumnsWithTypeAndName &
 
 REGISTER_FUNCTION(EmptyArrayToSingle)
 {
-    factory.registerFunction<FunctionEmptyArrayToSingle>();
+    FunctionDocumentation::Description description = R"(
+Accepts an empty array and returns a one-element array that is equal to the default value.
+    )";
+    FunctionDocumentation::Syntax syntax = "emptyArrayToSingle(arr)";
+    FunctionDocumentation::Arguments arguments = {{"arr", "An empty array. [`Array(T)`](/sql-reference/data-types/array)"}};
+    FunctionDocumentation::ReturnedValue returned_value = "An array with a single value of the Array's default type.";
+    FunctionDocumentation::Examples examples = {{"Basic example", R"(
+CREATE TABLE test (
+  a Array(Int32),
+  b Array(String),
+  c Array(DateTime)
+)
+ENGINE = MergeTree
+ORDER BY tuple();
+
+INSERT INTO test VALUES ([], [], []);
+
+SELECT emptyArrayToSingle(a), emptyArrayToSingle(b), emptyArrayToSingle(c) FROM test;
+)", R"(
+┌─emptyArrayToSingle(a)─┬─emptyArrayToSingle(b)─┬─emptyArrayToSingle(c)───┐
+│ [0]                   │ ['']                  │ ['1970-01-01 01:00:00'] │
+└───────────────────────┴───────────────────────┴─────────────────────────┘
+    )"}};
+    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<FunctionEmptyArrayToSingle>(documentation);
 }
 
 }

src/Functions/array/length.cpp

@@ -5,42 +5,54 @@ namespace DB
 
 REGISTER_FUNCTION(Length)
 {
-    factory.registerFunction<FunctionLength>(
-        FunctionDocumentation{
-            .description=R"(
-Calculates the length of the string or array.
+    FunctionDocumentation::Description description = R"(
+Calculates the length of a string or array.
 
-For String or FixedString argument: calculates the number of bytes in string.
-[example:string1]
+- For String or FixedString arguments: calculates the number of bytes in the string.
+- For Array arguments: calculates the number of elements in the array.
+- If applied to a FixedString argument, the function is a constant expression.
 
-For Array argument: calculates the number of elements in the array.
-[example:arr1]
-
-If applied for FixedString argument, the function is a constant expression:
-[example:constexpr]
-
-Please note that the number of bytes in a string is not the same as the number of Unicode "code points"
-and it is not the same as the number of Unicode "grapheme clusters" (what we usually call "characters")
-and it is not the same as the visible string width.
-[example:unicode]
+Please note that the number of bytes in a string is not the same as the number of
+Unicode "code points" and it is not the same as the number of Unicode "grapheme clusters"
+(what we usually call "characters") and it is not the same as the visible string width.
 
 It is ok to have ASCII NUL bytes in strings, and they will be counted as well.
-[example:nul]
-)",
-            .examples{
-                {"string1", "SELECT length('Hello, world!')", ""},
-                {"arr1", "SELECT length(['Hello'], ['world'])", ""},
-                {"constexpr", "WITH 'hello' || toString(number) AS str\n"
-                              "SELECT str, \n"
-                              "       isConstant(length(str)) AS str_length_is_constant, \n"
-                              "       isConstant(length(str::FixedString(6))) AS fixed_str_length_is_constant\n"
-                              "FROM numbers(3)", ""},
-                {"unicode", "SELECT 'ёлка' AS str1, length(str1), lengthUTF8(str1), normalizeUTF8NFKD(str1) AS str2, length(str2), lengthUTF8(str2)", ""},
-                {"nul", R"(SELECT 'abc\0\0\0' AS str, length(str))", ""},
-                },
-            .category = FunctionDocumentation::Category::Array
-        },
-        FunctionFactory::Case::Insensitive);
+    )";
+    FunctionDocumentation::Syntax syntax = "length(x)";
+    FunctionDocumentation::Arguments arguments = {{"x", "String, FixedString or Array for which to calculate the number of bytes (for String/FixedString) or elements (for Array)."}};
+    FunctionDocumentation::ReturnedValue returned_value = "Returns the number of number of bytes in the String/FixedString `x` / the number of elements in array `x`";
+    FunctionDocumentation::Examples examples {
+        {"string1", "SELECT length('Hello, world!')", "13"},
+        {"arr1", "SELECT length(['Hello', 'world'])", "2"},
+        {"constexpr", R"(
+WITH 'hello' || toString(number) AS str
+SELECT str,
+isConstant(length(str)) AS str_length_is_constant,
+isConstant(length(str::FixedString(6))) AS fixed_str_length_is_constant
+FROM numbers(3)
+        )", R"(
+┌─str────┬─str_length_is_constant─┬─fixed_str_length_is_constant─┐
+│ hello0 │                      0 │                            1 │
+│ hello1 │                      0 │                            1 │
+│ hello2 │                      0 │                            1 │
+└────────┴────────────────────────┴──────────────────────────────┘
+        )"},
+        {"unicode", "SELECT 'ёлка' AS str1, length(str1), lengthUTF8(str1), normalizeUTF8NFKD(str1) AS str2, length(str2), lengthUTF8(str2)", R"(
+┌─str1─┬─length(str1)─┬─lengthUTF8(str1)─┬─str2─┬─length(str2)─┬─lengthUTF8(str2)─┐
+│ ёлка │            8 │                4 │ ёлка │           10 │                5 │
+└──────┴──────────────┴──────────────────┴──────┴──────────────┴──────────────────┘
+        )"},
+        {"ascii_vs_utf8", "SELECT 'ábc' AS str, length(str), lengthUTF8(str)", R"(
+┌─str─┬─length(str)──┬─lengthUTF8(str)─┐
+│ ábc │            4 │               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<FunctionLength>(documentation, FunctionFactory::Case::Insensitive);
     factory.registerAlias("OCTET_LENGTH", "length", FunctionFactory::Case::Insensitive);
 }
 

src/Functions/array/range.cpp

@@ -572,7 +572,33 @@ class FunctionRange : public IFunction
 
 REGISTER_FUNCTION(Range)
 {
-    factory.registerFunction<FunctionRange>();
+    FunctionDocumentation::Description description = R"(
+Returns an array of numbers from `start` to `end - 1` by `step`.
+
+The supported types are:
+- `UInt8/16/32/64`
+- `Int8/16/32/64]`
+
+- All arguments `start`, `end`, `step` must be one of the above supported types. Elements of the returned array will be a super type of the arguments.
+- An exception is thrown if the function returns an array with a total length more than the number of elements specified by setting [`function_range_max_elements_in_block`](../../operations/settings/settings.md#function_range_max_elements_in_block).
+- Returns `NULL` if any argument has Nullable(nothing) type. An exception is thrown if any argument has `NULL` value (Nullable(T) type).
+    )";
+    FunctionDocumentation::Syntax syntax = "range([start, ] end [, step])";
+    FunctionDocumentation::Arguments arguments = {
+        {"start", "Optional. The first element of the array. Required if `step` is used. Default value: `0`."},
+        {"end", "Required. The number before which the array is constructed."},
+        {"step", "Optional. Determines the incremental step between each element in the array. Default value: `1`."},};
+    FunctionDocumentation::ReturnedValue returned_value = "Array of numbers from `start` to `end - 1` by `step`.";
+    FunctionDocumentation::Examples examples = {{"Usage example", "SELECT range(5), range(1, 5), range(1, 5, 2), range(-1, 5, 2);", R"(
+┌─range(5)────┬─range(1, 5)─┬─range(1, 5, 2)─┬─range(-1, 5, 2)─┐
+│ [0,1,2,3,4] │ [1,2,3,4]   │ [1,3]          │ [-1,1,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<FunctionRange>(documentation);
 }
 
 }