Merge pull request #42779 from Avogar/add-format-func-doc

Add documentation for 'format' table function

docs/en/sql-reference/table-functions/format.md

@@ -0,0 +1,75 @@
+---
+slug: /en/sql-reference/table-functions/format
+sidebar_position: 56
+sidebar_label: format
+---
+
+# format
+
+Extracts table structure from data and parses it according to specified input format.
+
+**Syntax**
+
+``` sql
+format(format_name, data)
+```
+
+**Parameters**
+
+-   `format_name` — The [format](../../interfaces/formats.md#formats) of the data.
+-   `data` — String literal or constant expression that returns a string containing data in specified format
+
+**Returned value**
+
+A table with data parsed from `data` argument according specified format and extracted schema.
+
+**Examples**
+
+**Query:**
+``` sql
+:) select * from format(JSONEachRow, 
+$$
+{"a": "Hello", "b": 111}
+{"a": "World", "b": 123}
+{"a": "Hello", "b": 112}
+{"a": "World", "b": 124}
+$$)
+```
+
+**Result:**
+
+```text
+┌───b─┬─a─────┐
+│ 111 │ Hello │
+│ 123 │ World │
+│ 112 │ Hello │
+│ 124 │ World │
+└─────┴───────┘
+```
+
+**Query:**
+```sql
+
+:) desc format(JSONEachRow,
+$$
+{"a": "Hello", "b": 111}
+{"a": "World", "b": 123}
+{"a": "Hello", "b": 112}
+{"a": "World", "b": 124}
+$$)
+```
+
+**Result:**
+
+```text
+┌─name─┬─type──────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐
+│ b    │ Nullable(Float64) │              │                    │         │                  │                │
+│ a    │ Nullable(String)  │              │                    │         │                  │                │
+└──────┴───────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘
+```
+
+**See Also**
+
+-   [Formats](../../interfaces/formats.md)
+
+[Original article](https://clickhouse.com/docs/en/sql-reference/table-functions/format) <!--hide-->

docs/ru/sql-reference/table-functions/format.md

@@ -0,0 +1 @@
+../../../en/sql-reference/table-functions/format.md

docs/zh/sql-reference/table-functions/format.md

@@ -0,0 +1 @@
+../../../en/sql-reference/table-functions/format.md

src/TableFunctions/TableFunctionFormat.cpp

@@ -89,9 +89,72 @@ StoragePtr TableFunctionFormat::executeImpl(const ASTPtr & /*ast_function*/, Con
     return res;
 }
 
+static const Documentation format_table_function_documentation =
+{
+    R"(
+Extracts table structure from data and parses it according to specified input format.
+Syntax: `format(format_name, data)`.
+Parameters:
+    - `format_name` - the format of the data.
+    - `data ` - String literal or constant expression that returns a string containing data in specified format.
+Returned value: A table with data parsed from `data` argument according specified format and extracted schema.
+)",
+    Documentation::Examples
+    {
+        {
+            "First example",
+            R"(
+Query:
+```
+:) select * from format(JSONEachRow,
+$$
+{"a": "Hello", "b": 111}
+{"a": "World", "b": 123}
+{"a": "Hello", "b": 112}
+{"a": "World", "b": 124}
+$$)
+```
+
+Result:
+```
+┌───b─┬─a─────┐
+│ 111 │ Hello │
+│ 123 │ World │
+│ 112 │ Hello │
+│ 124 │ World │
+└─────┴───────┘
+```
+)"
+        },
+        {
+            "Second example",
+            R"(
+Query:
+```
+:) desc format(JSONEachRow,
+$$
+{"a": "Hello", "b": 111}
+{"a": "World", "b": 123}
+{"a": "Hello", "b": 112}
+{"a": "World", "b": 124}
+$$)
+```
+
+Result:
+```
+┌─name─┬─type──────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐
+│ b    │ Nullable(Float64) │              │                    │         │                  │                │
+│ a    │ Nullable(String)  │              │                    │         │                  │                │
+└──────┴───────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘
+```
+)"
+        },
+    },
+    Documentation::Categories{"format", "table-functions"}
+};
+
 void registerTableFunctionFormat(TableFunctionFactory & factory)
 {
-    factory.registerFunction<TableFunctionFormat>({}, TableFunctionFactory::CaseInsensitive);
+    factory.registerFunction<TableFunctionFormat>({format_table_function_documentation, false}, TableFunctionFactory::CaseInsensitive);
 }
-
 }

tests/queries/0_stateless/02414_all_new_table_functions_must_be_documented.reference

@@ -3,7 +3,6 @@ clusterAllReplicas
 dictionary
 executable
 file
-format
 generateRandom
 input
 jdbc