Merge 'master' into ncb/fix-flake-02935

Author: bharatnc

docs/en/engines/table-engines/mergetree-family/invertedindexes.md

@@ -60,10 +60,6 @@ ENGINE = MergeTree
 ORDER BY key
 ```
 
-:::note
-In earlier versions of ClickHouse, the corresponding index type name was `inverted`.
-:::
-
 where `N` specifies the tokenizer:
 
 - `gin(0)` (or shorter: `gin()`) set the tokenizer to "tokens", i.e. split strings along spaces,

src/Client/ClientBase.cpp

@@ -71,6 +71,7 @@
 
 #include <Access/AccessControl.h>
 #include <Storages/ColumnsDescription.h>
+#include <TableFunctions/ITableFunction.h>
 
 #include <filesystem>
 #include <iostream>
@@ -1706,13 +1707,21 @@ bool ClientBase::receiveSampleBlock(Block & out, ColumnsDescription & columns_de
 
 void ClientBase::setInsertionTable(const ASTInsertQuery & insert_query)
 {
-    if (!client_context->hasInsertionTable() && insert_query.table)
+    if (!client_context->hasInsertionTable())
     {
-        String table = insert_query.table->as<ASTIdentifier &>().shortName();
-        if (!table.empty())
+        if  (insert_query.table)
         {
-            String database = insert_query.database ? insert_query.database->as<ASTIdentifier &>().shortName() : "";
-            client_context->setInsertionTable(StorageID(database, table));
+            String table = insert_query.table->as<ASTIdentifier &>().shortName();
+            if (!table.empty())
+            {
+                String database = insert_query.database ? insert_query.database->as<ASTIdentifier &>().shortName() : "";
+                client_context->setInsertionTable(StorageID(database, table));
+            }
+        }
+        else if (insert_query.table_function)
+        {
+            String table_function = insert_query.table_function->as<ASTFunction &>().name;
+            client_context->setInsertionTable(StorageID(ITableFunction::getDatabaseName(), table_function));
         }
     }
 }
@@ -2160,6 +2169,7 @@ void ClientBase::processParsedSingleQuery(
     cancelled_printed = false;
     client_exception.reset();
     server_exception.reset();
+    client_context->setInsertionTable(StorageID::createEmpty());
 
     if (is_interactive)
     {

src/Functions/abs.cpp

@@ -51,7 +51,15 @@ template <> struct FunctionUnaryArithmeticMonotonicity<NameAbs>
 
 REGISTER_FUNCTION(Abs)
 {
-    factory.registerFunction<FunctionAbs>({}, FunctionFactory::Case::Insensitive);
+    FunctionDocumentation::Description description = "Calculates the absolute value of `x`. Has no effect if `x` is of an unsigned type. If `x` is of a signed type, it returns an unsigned number.";
+    FunctionDocumentation::Syntax syntax = "abs(x)";
+    FunctionDocumentation::Arguments argument = {{"x", "Value to get the absolute value of"}};
+    FunctionDocumentation::ReturnedValue returned_value = "The absolute value of `x`";
+    FunctionDocumentation::Examples examples = {{"", "SELECT abs(-0.5)", "0.5"}};
+    FunctionDocumentation::Category categories = FunctionDocumentation::Category::Arithmetic;
+    FunctionDocumentation documentation = {description, syntax, argument, returned_value, examples, categories};
+
+    factory.registerFunction<FunctionAbs>(documentation, FunctionFactory::Case::Insensitive);
 }
 
 }

src/Functions/byteSwap.cpp

@@ -62,46 +62,35 @@ struct FunctionUnaryArithmeticMonotonicity<NameByteSwap>
 
 REGISTER_FUNCTION(ByteSwap)
 {
-    factory.registerFunction<FunctionByteSwap>(
-        FunctionDocumentation{
-            .description = R"(
+    FunctionDocumentation::Description description = R"(
 Reverses the bytes of an integer, i.e. changes its [endianness](https://en.wikipedia.org/wiki/Endianness).
 
-**Example**
+The below example can be worked out in the following manner:
 
-```sql
-byteSwap(3351772109)
-```
-
-Result:
-
-```result
-┌─byteSwap(3351772109)─┐
-│           3455829959 │
-└──────────────────────┘
-```
-
-The above example can be worked out in the following manner:
 1. Convert the base-10 integer to its equivalent hexadecimal format in big-endian format, i.e. 3351772109 -> C7 C7 FB CD (4 bytes)
 2. Reverse the bytes, i.e. C7 C7 FB CD -> CD FB C7 C7
-3. Convert the result back to an integer assuming big-endian, i.e. CD FB C7 C7  -> 3455829959
-
-One use-case of this function is reversing IPv4s:
+3. Convert the result back to an integer assuming big-endian, i.e. CD FB C7 C7 -> 3455829959
+One use case of this function is reversing IPv4s:
 
 ```result
 ┌─toIPv4(byteSwap(toUInt32(toIPv4('205.251.199.199'))))─┐
 │ 199.199.251.205                                       │
 └───────────────────────────────────────────────────────┘
 ```
-)",
-            .examples{
-                {"8-bit", "SELECT byteSwap(54)", "54"},
-                {"16-bit", "SELECT byteSwap(4135)", "10000"},
-                {"32-bit", "SELECT byteSwap(3351772109)", "3455829959"},
-                {"64-bit", "SELECT byteSwap(123294967295)", "18439412204227788800"},
-            },
-            .category = FunctionDocumentation::Category::Arithmetic},
-        FunctionFactory::Case::Insensitive);
+    )";
+    FunctionDocumentation::Syntax syntax = "byteSwap(x)";
+    FunctionDocumentation::Argument argument1 = {"x", "An integer value."};
+    FunctionDocumentation::Arguments arguments = {argument1};
+    FunctionDocumentation::ReturnedValue returned_value = "x with bytes reversed";
+    FunctionDocumentation::Example example1 = {"", "SELECT byteSwap(3351772109)", "3455829959"};
+    FunctionDocumentation::Example example2 = {"8-bit", "SELECT byteSwap(54)", "54"};
+    FunctionDocumentation::Example example3 = {"16-bit", "SELECT byteSwap(4135)", "10000"};
+    FunctionDocumentation::Example example4 = {"32-bit", "SELECT byteSwap(3351772109)", "3455829959"};
+    FunctionDocumentation::Example example5 = {"64-bit", "SELECT byteSwap(123294967295)", "18439412204227788800"};
+    FunctionDocumentation::Examples examples = {example1, example2, example3, example4, example5};
+    FunctionDocumentation::Category categories = FunctionDocumentation::Category::Arithmetic;
+    FunctionDocumentation documentation = {description, syntax, arguments, returned_value, examples, categories};
+    factory.registerFunction<FunctionByteSwap>(documentation,FunctionFactory::Case::Insensitive);
 }
 
 }

src/Functions/caseWithExpression.cpp

@@ -11,6 +11,7 @@ namespace DB
 namespace ErrorCodes
 {
     extern const int TOO_FEW_ARGUMENTS_FOR_FUNCTION;
+    extern const int BAD_ARGUMENTS;
 }
 
 namespace
@@ -38,6 +39,11 @@ class FunctionCaseWithExpression : public IFunction
         if (args.empty())
             throw Exception(ErrorCodes::TOO_FEW_ARGUMENTS_FOR_FUNCTION, "Function {} expects at least 1 arguments", getName());
 
+        /// We expect an even number of arguments, with the first argument being the expression,
+        /// and the last argument being the ELSE branch, with the rest being pairs of WHEN and THEN branches.
+        if (args.size() < 4 || args.size() % 2 != 0)
+            throw Exception(ErrorCodes::BAD_ARGUMENTS, "Function {} expects an even number of arguments: (expr, when1, then1, ..., else)", getName());
+
         /// See the comments in executeImpl() to understand why we actually have to
         /// get the return type of a transform function.
 

src/Functions/divide.cpp

@@ -41,7 +41,26 @@ using FunctionDivide = BinaryArithmeticOverloadResolver<DivideFloatingImpl, Name
 
 REGISTER_FUNCTION(Divide)
 {
-    factory.registerFunction<FunctionDivide>();
+    FunctionDocumentation::Description description = R"(
+    Calculates the quotient of two values `a` and `b`. The result type is always [Float64](/sql-reference/data-types/float).
+    Integer division is provided by the `intDiv` function.
+
+    :::note
+    Division by `0` returns `inf`, `-inf`, or `nan`.
+    :::
+    )";
+    FunctionDocumentation::Syntax syntax = "divide(x, y)";
+    FunctionDocumentation::Argument argument1 = {"x", "Dividend"};
+    FunctionDocumentation::Argument argument2 = {"y", "Divisor"};
+    FunctionDocumentation::Arguments arguments = {argument1, argument2};
+    FunctionDocumentation::ReturnedValue returned_value = "The quotient of x and y";
+    FunctionDocumentation::Example example1 = {"Dividing two numbers", "SELECT divide(25,5) AS quotient, toTypeName(quotient)", "5 Float64"};
+    FunctionDocumentation::Example example2 = {"Dividing by zero", "SELECT divide(25,0)", "inf"};
+    FunctionDocumentation::Examples examples = {example1, example2};
+    FunctionDocumentation::Category categories = FunctionDocumentation::Category::Arithmetic;
+    FunctionDocumentation documentation = {description, syntax, arguments, returned_value, examples, categories};
+
+    factory.registerFunction<FunctionDivide>(documentation);
 }
 
 struct NameDivideOrNull { static constexpr auto name = "divideOrNull"; };

src/Functions/divideDecimal.cpp

@@ -59,57 +59,43 @@ struct DivideDecimalsImpl
 
 REGISTER_FUNCTION(DivideDecimals)
 {
-    factory.registerFunction<FunctionsDecimalArithmetics<DivideDecimalsImpl>>(FunctionDocumentation{
-            .description = R"(
-Performs division on two decimals. Result value will be of type [Decimal256](../../sql-reference/data-types/decimal.md).
+    FunctionDocumentation::Description description = R"(
+Performs division on two decimals. Result value will be of type [Decimal256](/sql-reference/data-types/decimal).
 Result scale can be explicitly specified by `result_scale` argument (const Integer in range `[0, 76]`). If not specified, the result scale is the max scale of given arguments.
 
 :::note
 These function work significantly slower than usual `divide`.
 In case you don't really need controlled precision and/or need fast computation, consider using [divide](#divide).
-:::)",
-            .syntax = "divideDecimal(a, b[, result_scale])",
-            .arguments = {
-                {"a", "First value: [Decimal](../../sql-reference/data-types/decimal.md)"},
-                {"b", "Second value: [Decimal](../../sql-reference/data-types/decimal.md)."}
-            },
-            .returned_value = "The result of division with given scale. Type: [Decimal256](../../sql-reference/data-types/decimal.md).",
-            .examples = {
-                {"", "divideDecimal(toDecimal256(-12, 0), toDecimal32(2.1, 1), 10)",
-R"(
+:::
+    )";
+    FunctionDocumentation::Syntax syntax = "divideDecimal(x, y[, result_scale])";
+    FunctionDocumentation::Argument argument1 = {"x", "First value: [Decimal](/sql-reference/data-types/decimal)."};
+    FunctionDocumentation::Argument argument2 =   {"y", "Second value: [Decimal](/sql-reference/data-types/decimal)."};
+    FunctionDocumentation::Argument argument3 = {"result_scale", "Scale of result. Type [Int/UInt](/sql-reference/data-types/int-uint)."};
+    FunctionDocumentation::Arguments arguments = {argument1, argument2, argument3};
+    FunctionDocumentation::ReturnedValue returned_value = "The result of division with given scale. Type: [Decimal256](/sql-reference/data-types/decimal.md).";
+    FunctionDocumentation::Example example1 = {"", "divideDecimal(toDecimal256(-12, 0), toDecimal32(2.1, 1), 10)", R"(
 ┌─divideDecimal(toDecimal256(-12, 0), toDecimal32(2.1, 1), 10)─┐
 │                                                -5.7142857142 │
 └──────────────────────────────────────────────────────────────┘
-)"}, {"Difference to regular division",
-
-R"(
+    )"};
+    FunctionDocumentation::Example example2 = {"",
+    R"(
 SELECT toDecimal64(-12, 1) / toDecimal32(2.1, 1);
 SELECT toDecimal64(-12, 1) as a, toDecimal32(2.1, 1) as b, divideDecimal(a, b, 1), divideDecimal(a, b, 5);
-)",
-R"(
+    )",
+    R"(
 ┌─divide(toDecimal64(-12, 1), toDecimal32(2.1, 1))─┐
 │                                             -5.7 │
 └──────────────────────────────────────────────────┘
 ┌───a─┬───b─┬─divideDecimal(toDecimal64(-12, 1), toDecimal32(2.1, 1), 1)─┬─divideDecimal(toDecimal64(-12, 1), toDecimal32(2.1, 1), 5)─┐
 │ -12 │ 2.1 │                                                       -5.7 │                                                   -5.71428 │
 └─────┴─────┴────────────────────────────────────────────────────────────┴────────────────────────────────────────────────────────────┘
-)"
-},
-                {"",
-R"(
-SELECT toDecimal64(-12, 0) / toDecimal32(2.1, 1);
-SELECT toDecimal64(-12, 0) as a, toDecimal32(2.1, 1) as b, divideDecimal(a, b, 1), divideDecimal(a, b, 5);
-)",
-R"(
-DB::Exception: Decimal result's scale is less than argument's one: While processing toDecimal64(-12, 0) / toDecimal32(2.1, 1). (ARGUMENT_OUT_OF_BOUND)
-┌───a─┬───b─┬─divideDecimal(toDecimal64(-12, 0), toDecimal32(2.1, 1), 1)─┬─divideDecimal(toDecimal64(-12, 0), toDecimal32(2.1, 1), 5)─┐
-│ -12 │ 2.1 │                                                       -5.7 │                                                   -5.71428 │
-└─────┴─────┴────────────────────────────────────────────────────────────┴────────────────────────────────────────────────────────────┘
-)"}
-    },
-    .category = FunctionDocumentation::Category::TypeConversion
-    }
-    );
+    )"};
+    FunctionDocumentation::Examples examples = {example1, example2};
+    FunctionDocumentation::Category categories = FunctionDocumentation::Category::Arithmetic;
+    FunctionDocumentation documentation = {description, syntax, arguments, returned_value, examples, categories};
+    factory.registerFunction<FunctionsDecimalArithmetics<DivideDecimalsImpl>>(documentation);
 }
 
 }

src/Functions/gcd.cpp

@@ -31,7 +31,23 @@ using FunctionGCD = BinaryArithmeticOverloadResolver<GCDImpl, NameGCD, false, fa
 
 REGISTER_FUNCTION(GCD)
 {
-    factory.registerFunction<FunctionGCD>();
+    FunctionDocumentation::Description description = R"(
+    Returns the greatest common divisor of two values a and b.
+
+    An exception is thrown when dividing by zero or when dividing a minimal
+    negative number by minus one.
+    )";
+    FunctionDocumentation::Syntax syntax = "gcd(x, y)";
+    FunctionDocumentation::Argument argument1 = {"x", "First integer"};
+    FunctionDocumentation::Argument argument2 = {"y", "Second integer"};
+    FunctionDocumentation::Arguments arguments = {argument1, argument2};
+    FunctionDocumentation::ReturnedValue returned_value = "The greatest common divisor of `x` and `y`.";
+    FunctionDocumentation::Example example1 = {"", "SELECT gcd(12, 18)", "6"};
+    FunctionDocumentation::Examples examples = {example1};
+    FunctionDocumentation::Category categories = FunctionDocumentation::Category::Arithmetic;
+    FunctionDocumentation documentation = {description, syntax, arguments, returned_value, examples, categories};
+
+    factory.registerFunction<FunctionGCD>(documentation);
 }
 
 }

src/Functions/ifNotFinite.cpp

@@ -66,7 +66,24 @@ class FunctionIfNotFinite : public IFunction
 
 REGISTER_FUNCTION(IfNotFinite)
 {
-    factory.registerFunction<FunctionIfNotFinite>();
+    FunctionDocumentation::Description description = R"(
+Checks whether a floating point value is finite.
+
+You can get a similar result by using the [ternary operator](/sql-reference/functions/conditional-functions#if): `isFinite(x) ? x : y`.
+    )";
+    FunctionDocumentation::Syntax syntax = "ifNotFinite(x,y)";
+    FunctionDocumentation::Argument argument1 = {"x", "Value to check if infinite. Float32/Float64"};
+    FunctionDocumentation::Argument argument2 = {"y", "Fallback value. Float32/Float64"};
+    FunctionDocumentation::Arguments arguments = {argument1, argument2};
+    FunctionDocumentation::ReturnedValue returned_value = R"(
+- `x` if `x` is finite.
+- `y` if `x` is not finite.
+    )";
+    FunctionDocumentation::Examples examples = {{"","SELECT 1/0 AS infimum, ifNotFinite(infimum,42)","inf  42"}};
+    FunctionDocumentation::Category categories = FunctionDocumentation::Category::Arithmetic;
+    FunctionDocumentation documentation = {description, syntax, arguments, returned_value, examples, categories};
+
+    factory.registerFunction<FunctionIfNotFinite>(documentation);
 }
 
 }

src/Functions/intDiv.cpp

@@ -123,7 +123,45 @@ using FunctionIntDiv = BinaryArithmeticOverloadResolver<DivideIntegralImpl, Name
 
 REGISTER_FUNCTION(IntDiv)
 {
-    factory.registerFunction<FunctionIntDiv>();
+    FunctionDocumentation::Description description = R"(
+Performs an integer division of two values `x` by `y`. In other words it
+computes the quotient rounded down to the next smallest integer.
+
+The result has the same width as the dividend (the first parameter).
+
+An exception is thrown when dividing by zero, when the quotient does not fit
+in the range of the dividend, or when dividing a minimal negative number by minus one.
+    )";
+    FunctionDocumentation::Syntax syntax = "intDiv(x, y)";
+    FunctionDocumentation::Argument argument1 = {"x", "Left hand operand."};
+    FunctionDocumentation::Argument argument2 = {"y", "Right hand operand."};
+    FunctionDocumentation::Arguments arguments = {argument1, argument2};
+    FunctionDocumentation::ReturnedValue returned_value = "Result of integer division of `x` and `y`";
+    FunctionDocumentation::Example example1 = {"Integer division of two floats", "SELECT intDiv(toFloat64(1), 0.001) AS res, toTypeName(res)", R"(
+┌──res─┬─toTypeName(intDiv(toFloat64(1), 0.001))─┐
+│ 1000 │ Int64                                   │
+└──────┴─────────────────────────────────────────┘
+    )"};
+    FunctionDocumentation::Example example2 = {
+        "Quotient does not fit in the range of the dividend",
+        R"(
+SELECT
+intDiv(1, 0.001) AS res,
+toTypeName(res)
+        )",
+        R"(
+Received exception from server (version 23.2.1):
+Code: 153. DB::Exception: Received from localhost:9000. DB::Exception:
+Cannot perform integer division, because it will produce infinite or too
+large number: While processing intDiv(1, 0.001) AS res, toTypeName(res).
+(ILLEGAL_DIVISION)
+        )"
+    };
+    FunctionDocumentation::Examples examples = {example1, example2};
+    FunctionDocumentation::Category categories = FunctionDocumentation::Category::Arithmetic;
+    FunctionDocumentation documentation = {description, syntax, arguments, returned_value, examples, categories};
+
+    factory.registerFunction<FunctionIntDiv>(documentation);
 }
 
 struct NameIntDivOrNull { static constexpr auto name = "intDivOrNull"; };