Merge 'master' into ncb/fix-cov-by-broken-exists

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,

docs/en/sql-reference/statements/alter/comment.md

@@ -1,24 +1,28 @@
 ---
-description: 'Documentation for ALTER TABLE ... MODIFY COMMENT'
-sidebar_label: 'COMMENT'
+description: 'Documentation for ALTER TABLE ... MODIFY COMMENT which allow
+adding, modifying, or removing table comments'
+sidebar_label: 'ALTER TABLE ... MODIFY COMMENT'
 sidebar_position: 51
 slug: /sql-reference/statements/alter/comment
 title: 'ALTER TABLE ... MODIFY COMMENT'
+keywords: ['ALTER TABLE', 'MODIFY COMMENT']
 ---
 
 # ALTER TABLE ... MODIFY COMMENT
 
-Adds, modifies, or removes comment to the table, regardless if it was set before or not. Comment change is reflected in both [system.tables](../../../operations/system-tables/tables.md) and `SHOW CREATE TABLE` query.
+Adds, modifies, or removes a table comment, regardless of whether it was set 
+before or not. The comment change is reflected in both [`system.tables`](../../../operations/system-tables/tables.md) 
+and in the `SHOW CREATE TABLE` query.
 
-**Syntax**
+## Syntax {#syntax}
 
 ```sql
 ALTER TABLE [db].name [ON CLUSTER cluster] MODIFY COMMENT 'Comment'
 ```
 
-**Examples**
+## Examples {#examples}
 
-Creating a table with comment (for more information, see the [COMMENT](/sql-reference/statements/create/table#comment-clause) clause):
+To create a table with a comment:
 
 ```sql
 CREATE TABLE table_with_comment
@@ -30,38 +34,56 @@ ENGINE = Memory()
 COMMENT 'The temporary table';
 ```
 
-Modifying the table comment:
+To modify the table comment:
 
 ```sql
-ALTER TABLE table_with_comment MODIFY COMMENT 'new comment on a table';
-SELECT comment FROM system.tables WHERE database = currentDatabase() AND name = 'table_with_comment';
+ALTER TABLE table_with_comment 
+MODIFY COMMENT 'new comment on a table';
 ```
 
-Output of a new comment:
+To view the modified comment:
 
-```text
+```sql title="Query"
+SELECT comment 
+FROM system.tables 
+WHERE database = currentDatabase() AND name = 'table_with_comment';
+```
+
+```text title="Response"
 ┌─comment────────────────┐
 │ new comment on a table │
 └────────────────────────┘
 ```
 
-Removing the table comment:
+To remove the table comment:
 
 ```sql
 ALTER TABLE table_with_comment MODIFY COMMENT '';
-SELECT comment FROM system.tables WHERE database = currentDatabase() AND name = 'table_with_comment';
 ```
 
-Output of a removed comment:
+To verify that the comment was removed:
+
+```sql title="Query"
+SELECT comment 
+FROM system.tables 
+WHERE database = currentDatabase() AND name = 'table_with_comment';
+```
 
-```text
+```text title="Response"
 ┌─comment─┐
 │         │
 └─────────┘
 ```
 
-**Caveats**
+## Caveats {#caveats}
+
+For Replicated tables, the comment can be different on different replicas. 
+Modifying the comment applies to a single replica.
+
+The feature is available since version 23.9. It does not work in previous 
+ClickHouse versions.
 
-For Replicated tables, the comment can be different on different replicas. Modifying the comment applies to a single replica.
+## Related content {#related-content}
 
-The feature is available since version 23.9. It does not work in previous ClickHouse versions.
+- [`COMMENT`](/sql-reference/statements/create/table#comment-clause) clause
+- [`ALTER DATABASE ... MODIFY COMMENT`](./database-comment.md)

docs/en/sql-reference/statements/alter/database-comment.md

@@ -1,55 +1,76 @@
 ---
-description: 'Documentation for ALTER DATABASE ... MODIFY COMMENT Statements'
+description: 'Documentation for ALTER DATABASE ... MODIFY COMMENT statements
+which allow adding, modifying, or removing database comments.'
 slug: /sql-reference/statements/alter/database-comment
 sidebar_position: 51
-sidebar_label: 'UPDATE'
+sidebar_label: 'ALTER DATABASE ... MODIFY COMMENT'
 title: 'ALTER DATABASE ... MODIFY COMMENT Statements'
+keywords: ['ALTER DATABASE', 'MODIFY COMMENT']
 ---
 
 # ALTER DATABASE ... MODIFY COMMENT
 
-Adds, modifies, or removes comment to the database, regardless of whether it was set before. Comment change is reflected in both [system.databases](/operations/system-tables/databases.md) and `SHOW CREATE DATABASE` query.
+Adds, modifies, or removes a database comment, regardless of whether it was set
+before or not. The comment change is reflected in both [`system.databases`](/operations/system-tables/databases.md) 
+and the `SHOW CREATE DATABASE` query.
 
-**Syntax**
+## Syntax {#syntax}
 
 ``` sql
 ALTER DATABASE [db].name [ON CLUSTER cluster] MODIFY COMMENT 'Comment'
 ```
 
-**Examples**
+## Examples {#examples}
 
-Creating a DATABASE with comment (for more information, see the [COMMENT](/sql-reference/statements/create/table#comment-clause) clause):
+To create a `DATABASE` with a comment:
 
 ``` sql
 CREATE DATABASE database_with_comment ENGINE = Memory COMMENT 'The temporary database';
 ```
 
-Modifying the table comment:
+To modify the comment:
 
 ``` sql
-ALTER DATABASE database_with_comment MODIFY COMMENT 'new comment on a database';
-SELECT comment FROM system.databases WHERE name = 'database_with_comment';
+ALTER DATABASE database_with_comment 
+MODIFY COMMENT 'new comment on a database';
 ```
 
-Output of a new comment:
+To view the modified comment:
+
+```sql
+SELECT comment 
+FROM system.databases 
+WHERE name = 'database_with_comment';
+```
 
 ```text
 ┌─comment─────────────────┐
 │ new comment on database │
 └─────────────────────────┘
 ```
 
-Removing the database comment:
+To remove the database comment:
 
 ``` sql
-ALTER DATABASE database_with_comment MODIFY COMMENT '';
-SELECT comment FROM system.databases WHERE  name = 'database_with_comment';
+ALTER DATABASE database_with_comment 
+MODIFY COMMENT '';
 ```
 
-Output of a removed comment:
+To verify that the comment was removed:
 
-```text
+```sql title="Query"
+SELECT comment 
+FROM system.databases 
+WHERE  name = 'database_with_comment';
+```
+
+```text title="Response"
 ┌─comment─┐
 │         │
 └─────────┘
 ```
+
+## Related content {#related-content}
+
+- [`COMMENT`](/sql-reference/statements/create/table#comment-clause) clause
+- [`ALTER TABLE ... MODIFY COMMENT`](./comment.md)

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"; };