Project: ClickHouse (App Definition and Development / Database)
File: formats.md

slug: /en/interfaces/formats sidebar_position: 21 sidebar_label: View all formats... title: Formats for Input and Output Data ClickHouse can accept and return data in various formats. A format supported for input can be used to parse the data provided to `INSERT`s, to perform `SELECT`s from a file-backed table such as File, URL or HDFS, or to read a dictionary. A format supported for output can be used to arrange the results of a `SELECT`, and to perform `INSERT`s into a file-backed table. All format names are case insensitive. The supported formats are: | Format | Input | Output | |-||-| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | You can control some format processing parameters with the ClickHouse settings. For more information read the section. In TabSeparated format, data is written by row. Each row contains values separated by tabs. Each value is followed by a tab, except the last value in the row, which is followed by a line feed. Strictly Unix line feeds are assumed everywhere. The last row also must contain a line feed at the end. Values are written in text format, without enclosing quotation marks, and with special characters escaped. This format is also available under the name `TSV`. The `TabSeparated` format is convenient for processing data using custom programs and scripts. It is used by default in the HTTP interface, and in the command-line clients batch mode. This format also allows transferring data between different DBMSs. For example, you can get a dump from MySQL and upload it to ClickHouse, or vice

The `TabSeparated` format supports outputting total values (when using WITH TOTALS) and extreme values (when extremes is set to 1). In these cases, the total values and extremes are output after the main data. The main result, total values, and extremes are separated from each other by an empty line. Example: ``` sql SELECT EventDate, count() AS c FROM test.hits GROUP BY EventDate WITH TOTALS ORDER BY EventDate FORMAT TabSeparated ``` ``` response 2014-03-17 1406958 2014-03-18 1383658 2014-03-19 1405797 2014-03-20 1353623 2014-03-21 1245779 2014-03-22 1031592 2014-03-23 1046491 1970-01-01 8873898 2014-03-17 1031592 2014-03-23 1406958 ``` Integer numbers are written in decimal form. Numbers can contain an extra + character at the beginning (ignored when parsing, and not recorded when formatting). Non-negative numbers cant contain the negative sign. When reading, it is allowed to parse an empty string as a zero, or (for signed types) a string consisting of just a minus sign as a zero. Numbers that do not fit into the corresponding data type may be parsed as a different number, without an error message. Floating-point numbers are written in decimal form. The dot is used as the decimal separator. Exponential entries are supported, as are inf, +inf, -inf, and nan. An entry of floating-point numbers may begin or end with a decimal point. During formatting, accuracy may be lost on floating-point numbers. During parsing, it is not strictly required to read the nearest machine-representable number. Dates are written in YYYY-MM-DD format and parsed in the same format, but with any characters as separators. Dates with times are written in the format `YYYY-MM-DD hh:mm:ss` and parsed in the same format, but with any characters as separators. This all occurs in the system time zone at the time the client or server starts (depending on which of them formats data). For dates with times, daylight saving time is not specified. So if a dump has times during daylight saving time, the dump does not unequivocally match the data, and parsing will select one of the two times. During a read operation, incorrect dates and dates with times can be parsed with natural overflow or as null dates and times, without an error message. As an exception, parsing dates with times is also supported in Unix timestamp format, if it consists of exactly 10 decimal digits. The result is not time zone-dependent. The formats `YYYY-MM-DD hh:mm:ss` and `NNNNNNNNNN` are differentiated automatically. Strings are output with backslash-escaped special characters. The following escape sequences are used for output: `\b`, `\f`, `\r`, `\n`, `\t`, `\0`, `\'`, `\\`. Parsing also supports the sequences `\a`, `\v`, and `\xHH` (hex escape sequences) and any `\c` sequences, where `c` is any character (these sequences are converted to `c`). Thus, reading data supports formats where a line feed can be written as `\n` or `\`, or as a line feed. For example, the string `Hello world` with a line feed between the words instead of space can be parsed in any of the following variations: ``` text Hello\nworld Hello\ world ``` The second variant is supported because MySQL uses it when writing tab-separated dumps. The minimum set of characters that you need to escape when passing data in TabSeparated format: tab, line feed (LF) and backslash. Only a small set of symbols are escaped. You can easily stumble onto a string value that your terminal will ruin in output. Arrays are written as a list of comma-separated values in square brackets. Number items in the array are formatted as normally. `Date` and `DateTime` types are written in single

Strings are written in single quotes with the same escaping rules as above. is formatted according to setting (default value is `\N`). In input data, ENUM values can be represented as names or as ids. First, we try to match the input value to the ENUM name. If we fail and the input value is a number, we try to match this number to ENUM id. If input data contains only ENUM ids, it's recommended to enable the setting to optimize ENUM parsing. Each element of structures is represented as an array. For example: ``` sql CREATE TABLE nestedt ( `id` UInt8, `aux` Nested( a UInt8, b String ) ) ENGINE = TinyLog ``` ``` sql INSERT INTO nestedt Values ( 1, [1], ['a']) ``` ``` sql SELECT * FROM nestedt FORMAT TSV ``` ``` response 1 [1] ['a'] ``` - custom NULL representation in TSV format. Default value - `\N`. - treat empty fields in TSV input as default values. Default value - `false`. For complex default expressions must be enabled too. - treat inserted enum values in TSV formats as enum indices. Default value - `false`. - use some tweaks and heuristics to infer schema in TSV format. If disabled, all fields will be inferred as Strings. Default value - `true`. - if it is set true, end of line in TSV output format will be `\r\n` instead of `\n`. Default value - `false`. - skip specified number of lines at the beginning of data. Default value - `0`. - automatically detect header with names and types in TSV format. Default value - `true`. - skip trailing empty lines at the end of data. Default value - `false`. - allow variable number of columns in TSV format, ignore extra columns and use default values on missing columns. Default value - `false`. Differs from `TabSeparated` format in that the rows are written without escaping. When parsing with this format, tabs or linefeeds are not allowed in each field. This format is also available under the names `TSVRaw`, `Raw`. Differs from the `TabSeparated` format in that the column names are written in the first row. During parsing, the first row is expected to contain the column names. You can use column names to determine their position and to check their correctness. :::note If setting is set to 1, the columns from the input data will be mapped to the columns of the table by their names, columns with unknown names will be skipped if setting is set to 1. Otherwise, the first row will be skipped. ::: This format is also available under the name `TSVWithNames`. Differs from the `TabSeparated` format in that the column names are written to the first row, while the column types are in the second row. :::note If setting is set to 1, the columns from the input data will be mapped to the columns in the table by their names, columns with unknown names will be skipped if setting is set to 1. Otherwise, the first row will be skipped. If setting is set to 1, the types from input data will be compared with the types of the corresponding columns from the table. Otherwise, the second row will be skipped. ::: This format is also available under the name `TSVWithNamesAndTypes`. Differs from `TabSeparatedWithNames` format in that the rows are written without escaping. When parsing with this format, tabs or linefeeds are not allowed in each field. This format is also available under the names `TSVRawWithNames`,

Differs from `TabSeparatedWithNamesAndTypes` format in that the rows are written without escaping. When parsing with this format, tabs or linefeeds are not allowed in each field. This format is also available under the names `TSVRawWithNamesAndNames`, `RawWithNamesAndNames`. This format allows specifying a custom format string with placeholders for values with a specified escaping rule. It uses settings `formattemplateresultset`, `formattemplaterow` (`formattemplaterowformat`), `formattemplaterowsbetweendelimiter` and some settings of other formats (e.g.`outputformatjsonquote64bitintegers` when using `JSON` escaping, see further) Setting `formattemplaterow` specifies the path to the file containing format strings for rows with the following syntax: `delimiter1${column1:serializeAs1}delimiter2${column2:serializeAs2} ... delimiter_N`, where `delimiter_i` is a delimiter between values (`$` symbol can be escaped as `$$`), `column_i` is a name or index of a column whose values are to be selected or inserted (if empty, then column will be skipped), `serializeAs_i` is an escaping rule for the column values. The following escaping rules are supported: `CSV`, `JSON`, `XML` (similar to the formats of the same names) `Escaped` (similar to `TSV`) `Quoted` (similar to `Values`) `Raw` (without escaping, similar to `TSVRaw`) `None` (no escaping rule, see further) If an escaping rule is omitted, then `None` will be used. `XML` is suitable only for output. So, for the following format string: `Search phrase: ${SearchPhrase:Quoted}, count: ${c:Escaped}, ad price: $$${price:JSON};` the values of `SearchPhrase`, `c` and `price` columns, which are escaped as `Quoted`, `Escaped` and `JSON` will be printed (for select) or will be expected (for insert) between `Search phrase:`, `, count:`, `, ad price: $` and `;` delimiters respectively. For example: `Search phrase: 'bathroom interior design', count: 2166, ad price: $3;` In cases where it is challenging or not possible to deploy format output configuration for the template format to a directory on all nodes in a cluster, or if the format is trivial then `formattemplaterow_format` can be used to set the template string directly in the query, rather than a path to the file which contains it. The `formattemplaterowsbetweendelimiter` setting specifies the delimiter between rows, which is printed (or expected) after every row except the last one (`\n` by default) Setting `formattemplateresultset` specifies the path to the file, which contains a format string for resultset. Setting `formattemplateresultset_format` can be used to set the template string for the result set directly in the query itself. Format string for resultset has the same syntax as a format string for row and allows to specify a prefix, a suffix and a way to print some additional information. It contains the following placeholders instead of column names: `data` is the rows with data in `formattemplaterow` format, separated by `formattemplaterowsbetweendelimiter`. This placeholder must be the first placeholder in the format string. `totals` is the row with total values in `formattemplaterow` format (when using WITH TOTALS) `min` is the row with minimum values in `formattemplaterow` format (when extremes are set to 1) `max` is the row with maximum values in `formattemplaterow` format (when extremes are set to 1) `rows` is the total number of output rows `rowsbeforelimit` is the minimal number of rows there would have been without LIMIT. Output only if the query contains LIMIT. If the query contains GROUP BY, rowsbeforelimitatleast is the exact number of rows there would have been without a LIMIT. `time` is the request execution time in seconds `rows_read` is the number of rows has been read `bytes_read` is the number of bytes (uncompressed) has been read The placeholders `data`, `totals`, `min` and `max` must not have escaping rule specified (or `None` must be specified explicitly). The remaining placeholders may have any escaping rule

If the `formattemplateresultset` setting is an empty string, `${data}` is used as the default value. For insert queries format allows skipping some columns or fields if prefix or suffix (see example). Select example: ``` sql SELECT SearchPhrase, count() AS c FROM test.hits GROUP BY SearchPhrase ORDER BY c DESC LIMIT 5 FORMAT Template SETTINGS formattemplateresultset = '/some/path/resultset.format', formattemplaterow = '/some/path/row.format', formattemplaterowsbetweendelimiter = '\n ' ``` `/some/path/resultset.format`: ``` text <!DOCTYPE HTML> <html> <head> <title>Search phrases</title> </head> <body> <table border="1"> <caption>Search phrases</caption> <tr> <th>Search phrase</th> <th>Count</th> </tr> ${data} </table> <table border="1"> <caption>Max</caption> ${max} </table> <b>Processed ${rows_read:XML} rows in ${time:XML} sec</b> </body> </html> ``` `/some/path/row.format`: ``` text <tr> <td>${0:XML}</td> <td>${1:XML}</td> </tr> ``` Result: ``` html <!DOCTYPE HTML> <html> <head> <title>Search phrases</title> </head> <body> <table border="1"> <caption>Search phrases</caption> <tr> <th>Search phrase</th> <th>Count</th> </tr> <tr> <td></td> <td>8267016</td> </tr> <tr> <td>bathroom interior design</td> <td>2166</td> </tr> <tr> <td>clickhouse</td> <td>1655</td> </tr> <tr> <td>spring 2014 fashion</td> <td>1549</td> </tr> <tr> <td>freeform photos</td> <td>1480</td> </tr> </table> <table border="1"> <caption>Max</caption> <tr> <td></td> <td>8873898</td> </tr> </table> <b>Processed 3095973 rows in 0.1569913 sec</b> </body> </html> ``` Insert example: ``` text Some header Page views: 5, User id: 4324182021466249494, Useless field: hello, Duration: 146, Sign: -1 Page views: 6, User id: 4324182021466249494, Useless field: world, Duration: 185, Sign: 1 Total rows: 2 ``` ``` sql INSERT INTO UserActivity SETTINGS formattemplateresultset = '/some/path/resultset.format', formattemplaterow = '/some/path/row.format' FORMAT Template ``` `/some/path/resultset.format`: ``` text Some header\n${data}\nTotal rows: ${:CSV}\n ``` `/some/path/row.format`: ``` text Page views: ${PageViews:CSV}, User id: ${UserID:CSV}, Useless field: ${:CSV}, Duration: ${Duration:CSV}, Sign: ${Sign:CSV} ``` `PageViews`, `UserID`, `Duration` and `Sign` inside placeholders are names of columns in the table. Values after `Useless field` in rows and after `\nTotal rows:` in suffix will be ignored. All delimiters in the input data must be strictly equal to delimiters in specified format strings. This format is suitable only for input. Similar to `Template`, but skips whitespace characters between delimiters and values in the input stream. However, if format strings contain whitespace characters, these characters will be expected in the input stream. Also allows specifying empty placeholders (`${}` or `${:None}`) to split some delimiter into separate parts to ignore spaces between them. Such placeholders are used only for skipping whitespace characters. Its possible to read `JSON` using this format if the values of columns have the same order in all rows. For example, the following request can be used for inserting data from its output example of format : ``` sql INSERT INTO table_name SETTINGS formattemplateresultset = '/some/path/resultset.format', formattemplaterow = '/some/path/row.format', formattemplaterowsbetweendelimiter = ',' FORMAT TemplateIgnoreSpaces ``` `/some/path/resultset.format`: ``` text {${}"meta"${}:${:JSON},${}"data"${}:${}[${data}]${},${}"totals"${}:${:JSON},${}"extremes"${}:${:JSON},${}"rows"${}:${:JSON},${}"rowsbeforelimitatleast"${}:${:JSON}${}} ``` `/some/path/row.format`: ``` text {${}"SearchPhrase"${}:${}${phrase:JSON}${},${}"c"${}:${}${cnt:JSON}${}} ``` Similar to TabSeparated, but outputs a value in name=value format. Names are escaped the same way as in TabSeparated format, and the = symbol is also escaped. ``` text SearchPhrase= count()=8267016 SearchPhrase=bathroom interior design count()=2166 SearchPhrase=clickhouse count()=1655 SearchPhrase=2014 spring fashion count()=1549 SearchPhrase=freeform photos count()=1480 SearchPhrase=angelina jolie count()=1245 SearchPhrase=omsk count()=1112 SearchPhrase=photos of dog breeds count()=1091 SearchPhrase=curtain designs count()=1064 SearchPhrase=baku count()=1000 ``` is formatted as `\N`. ``` sql SELECT * FROM t_null FORMAT TSKV ``` ``` text x=1 y=\N ``` When there is a large number of small columns, this format is ineffective, and there is generally no reason to use it. Nevertheless, it is no worse than JSONEachRow in terms of efficiency. Both data output and parsing are supported in this format. For parsing, any order is supported for the values of different columns. It is acceptable for some values to be omitted they are treated as equal to their default values. In this case, zeros and blank rows are used as default

Complex values that could be specified in the table are not supported as defaults. Parsing allows the presence of the additional field `tskv` without the equal sign or a value. This field is ignored. During import, columns with unknown names will be skipped if setting is set to 1. Comma Separated Values format (). When formatting, rows are enclosed in double quotes. A double quote inside a string is output as two double quotes in a row. There are no other rules for escaping characters. Date and date-time are enclosed in double quotes. Numbers are output without quotes. Values are separated by a delimiter character, which is `,` by default. The delimiter character is defined in the setting . Rows are separated using the Unix line feed (LF). Arrays are serialized in CSV as follows: first, the array is serialized to a string as in TabSeparated format, and then the resulting string is output to CSV in double quotes. Tuples in CSV format are serialized as separate columns (that is, their nesting in the tuple is lost). ``` bash $ clickhouse-client --formatcsvdelimiter="|" --query="INSERT INTO test.csv FORMAT CSV" < data.csv ``` \*By default, the delimiter is `,`. See the setting for more information. When parsing, all values can be parsed either with or without quotes. Both double and single quotes are supported. Rows can also be arranged without quotes. In this case, they are parsed up to the delimiter character or line feed (CR or LF). In violation of the RFC, when parsing rows without quotes, the leading and trailing spaces and tabs are ignored. For the line feed, Unix (LF), Windows (CR LF) and Mac OS Classic (CR LF) types are all supported. `NULL` is formatted according to setting (default value is `\N`). In input data, ENUM values can be represented as names or as ids. First, we try to match the input value to the ENUM name. If we fail and the input value is a number, we try to match this number to the ENUM id. If input data contains only ENUM ids, it's recommended to enable the setting to optimize ENUM parsing. The CSV format supports the output of totals and extremes the same way as `TabSeparated`. - the character to be considered as a delimiter in CSV data. Default value - `,`. - allow strings in single quotes. Default value - `true`. - allow strings in double quotes. Default value - `true`. - custom NULL representation in CSV format. Default value - `\N`. - treat empty fields in CSV input as default values. Default value - `true`. For complex default expressions, must be enabled too. - treat inserted enum values in CSV formats as enum indices. Default value - `false`. - use some tweaks and heuristics to infer schema in CSV format. If disabled, all fields will be inferred as Strings. Default value - `true`. - when reading Array from CSV, expect that its elements were serialized in nested CSV and then put into string. Default value - `false`. - if it is set to true, end of line in CSV output format will be `\r\n` instead of `\n`. Default value - `false`. - skip the specified number of lines at the beginning of data. Default value - `0`. - automatically detect header with names and types in CSV format. Default value - `true`. - skip trailing empty lines at the end of data. Default value - `false`. - trim spaces and tabs in non-quoted CSV

Default value - `true`. - Allow to use whitespace or tab as field delimiter in CSV strings. Default value - `false`. - allow variable number of columns in CSV format, ignore extra columns and use default values on missing columns. Default value - `false`. - Allow to set default value to column when CSV field deserialization failed on bad value. Default value - `false`. - Try to infer numbers from string fields while schema inference. Default value - `false`. Also prints the header row with column names, similar to . :::note If setting is set to 1, the columns from input data will be mapped to the columns from the table by their names, columns with unknown names will be skipped if setting is set to 1. Otherwise, the first row will be skipped. ::: Also prints two header rows with column names and types, similar to . :::note If setting is set to 1, the columns from input data will be mapped to the columns from the table by their names, columns with unknown names will be skipped if setting is set to 1. Otherwise, the first row will be skipped. If setting is set to 1, the types from input data will be compared with the types of the corresponding columns from the table. Otherwise, the second row will be skipped. ::: Similar to , but it prints or reads all names and types of columns and uses escaping rule from setting and delimiters from , , , , and settings, not from format strings. Additional settings: - enables automatic detection of header with names and types if any. Default value - `true`. - skip trailing empty lines at the end of file . Default value - `false`. - allow variable number of columns in CustomSeparated format, ignore extra columns and use default values on missing columns. Default value - `false`. There is also `CustomSeparatedIgnoreSpaces` format, which is similar to . Also prints the header row with column names, similar to . :::note If setting is set to 1, the columns from input data will be mapped to the columns from the table by their names, columns with unknown names will be skipped if setting is set to 1. Otherwise, the first row will be skipped. ::: Also prints two header rows with column names and types, similar to . :::note If setting is set to 1, the columns from input data will be mapped to the columns from the table by their names, columns with unknown names will be skipped if setting is set to 1. Otherwise, the first row will be skipped. If setting is set to 1, the types from input data will be compared with the types of the corresponding columns from the table. Otherwise, the second row will be skipped. ::: Outputs data as a sequence of `INSERT INTO table (columns...) VALUES (...), (...) ...;`

Example: ```sql SELECT number AS x, number + 1 AS y, 'Hello' AS z FROM numbers(10) FORMAT SQLInsert SETTINGS outputformatsqlinsertmaxbatchsize = 2 ``` ```sql INSERT INTO table (x, y, z) VALUES (0, 1, 'Hello'), (1, 2, 'Hello'); INSERT INTO table (x, y, z) VALUES (2, 3, 'Hello'), (3, 4, 'Hello'); INSERT INTO table (x, y, z) VALUES (4, 5, 'Hello'), (5, 6, 'Hello'); INSERT INTO table (x, y, z) VALUES (6, 7, 'Hello'), (7, 8, 'Hello'); INSERT INTO table (x, y, z) VALUES (8, 9, 'Hello'), (9, 10, 'Hello'); ``` To read data output by this format you can use input format. - The maximum number of rows in one INSERT statement. Default value - `65505`. - The name of the table in the output INSERT query. Default value - `'table'`. - Include column names in INSERT query. Default value - `true`. - Use REPLACE statement instead of INSERT. Default value - `false`. - Quote column names with "\`" characters. Default value - `true`. Outputs data in JSON format. Besides data tables, it also outputs column names and types, along with some additional information: the total number of output rows, and the number of rows that could have been output if there werent a LIMIT. Example: ``` sql SELECT SearchPhrase, count() AS c FROM test.hits GROUP BY SearchPhrase WITH TOTALS ORDER BY c DESC LIMIT 5 FORMAT JSON ``` ``` json { "meta": [ { "name": "num", "type": "Int32" }, { "name": "str", "type": "String" }, { "name": "arr", "type": "Array(UInt8)" } ], "data": [ { "num": 42, "str": "hello", "arr": [0,1] }, { "num": 43, "str": "hello", "arr": [0,1,2] }, { "num": 44, "str": "hello", "arr": [0,1,2,3] } ], "rows": 3, "rowsbeforelimitatleast": 3, "statistics": { "elapsed": 0.001137687, "rows_read": 3, "bytes_read": 24 } } ``` The JSON is compatible with JavaScript. To ensure this, some characters are additionally escaped: the slash `/` is escaped as `\/`; alternative line breaks `U+2028` and `U+2029`, which break some browsers, are escaped as `\uXXXX`. ASCII control characters are escaped: backspace, form feed, line feed, carriage return, and horizontal tab are replaced with `\b`, `\f`, `\n`, `\r`, `\t` , as well as the remaining bytes in the 00-1F range using `\uXXXX` sequences. Invalid UTF-8 sequences are changed to the replacement character so the output text will consist of valid UTF-8 sequences. For compatibility with JavaScript, Int64 and UInt64 integers are enclosed in double quotes by default. To remove the quotes, you can set the configuration parameter to 0. `rows` The total number of output rows. `rowsbeforelimitatleast` The minimal number of rows there would have been without LIMIT. Output only if the query contains LIMIT. If the query contains GROUP BY, rowsbeforelimitatleast is the exact number of rows there would have been without a LIMIT. `totals` Total values (when using WITH TOTALS). `extremes` Extreme values (when extremes are set to 1). ClickHouse supports , which is displayed as `null` in the JSON output. To enable `+nan`, `-nan`, `+inf`, `-inf` values in output, set the to 1. See Also format setting For JSON input format, if setting is set to 1, the types from metadata in input data will be compared with the types of the corresponding columns from the table. Differs from JSON only in that data fields are output in strings, not in typed JSON values. Example: ```json { "meta": [ { "name": "num", "type": "Int32" }, { "name": "str", "type": "String" }, { "name": "arr", "type": "Array(UInt8)" } ], "data": [ { "num": "42", "str": "hello", "arr": "[0,1]" }, { "num": "43", "str": "hello", "arr": "[0,1,2]" }, { "num": "44", "str": "hello", "arr": "[0,1,2,3]" } ], "rows": 3, "rowsbeforelimitatleast": 3, "statistics": { "elapsed": 0.001403233, "rows_read": 3, "bytes_read": 24 } } ``` :::tip The output of the JSONColumns* formats provides the ClickHouse field name and then the content of each row of the table for that field; visually, the data is rotated 90 degrees to the left. ::: In this format, all data is represented as a single JSON

Note that JSONColumns output format buffers all data in memory to output it as a single block and it can lead to high memory consumption. Example: ```json { "num": [42, 43, 44], "str": ["hello", "hello", "hello"], "arr": [[0,1], [0,1,2], [0,1,2,3]] } ``` During import, columns with unknown names will be skipped if setting is set to 1. Columns that are not present in the block will be filled with default values (you can use the setting here) Differs from JSONColumns format in that it also contains some metadata and statistics (similar to JSON format). Output format buffers all data in memory and then outputs them as a single block, so, it can lead to high memory consumption. Example: ```json { "meta": [ { "name": "num", "type": "Int32" }, { "name": "str", "type": "String" }, { "name": "arr", "type": "Array(UInt8)" } ], "data": { "num": [42, 43, 44], "str": ["hello", "hello", "hello"], "arr": [[0,1], [0,1,2], [0,1,2,3]] }, "rows": 3, "rowsbeforelimitatleast": 3, "statistics": { "elapsed": 0.000272376, "rows_read": 3, "bytes_read": 24 } } ``` For JSONColumnsWithMetadata input format, if setting is set to 1, the types from metadata in input data will be compared with the types of the corresponding columns from the table. In this format, a single JSON object is interpreted as a single value. If the input has several JSON objects (comma separated), they are interpreted as separate rows. If the input data is enclosed in square brackets, it is interpreted as an array of JSONs. This format can only be parsed for a table with a single field of type . The remaining columns must be set to or , or omitted. Once you collect the whole JSON object to string you can use to process it. Examples Query: ``` sql DROP TABLE IF EXISTS jsonasstring; CREATE TABLE jsonasstring (json String) ENGINE = Memory; INSERT INTO jsonasstring (json) FORMAT JSONAsString {"foo":{"bar":{"x":"y"},"baz":1}},{},{"any json stucture":1} SELECT * FROM jsonasstring; ``` Result: ``` response json {"foo":{"bar":{"x":"y"},"baz":1}} {} {"any json stucture":1} ``` An array of JSON objects Query: ``` sql CREATE TABLE jsonsquarebrackets (field String) ENGINE = Memory; INSERT INTO jsonsquarebrackets FORMAT JSONAsString [{"id": 1, "name": "name1"}, {"id": 2, "name": "name2"}]; SELECT * FROM jsonsquarebrackets; ``` Result: ```response field {"id": 1, "name": "name1"} {"id": 2, "name": "name2"} ``` Differs from JSON only in that data rows are output in arrays, not in objects. Example: ```json { "meta": [ { "name": "num", "type": "Int32" }, { "name": "str", "type": "String" }, { "name": "arr", "type": "Array(UInt8)" } ], "data": [ [42, "hello", [0,1]], [43, "hello", [0,1,2]], [44, "hello", [0,1,2,3]] ], "rows": 3, "rowsbeforelimitatleast": 3, "statistics": { "elapsed": 0.001222069, "rows_read": 3, "bytes_read": 24 } } ``` Differs from JSONStrings only in that data rows are output in arrays, not in objects. Example: f ```json { "meta": [ { "name": "num", "type": "Int32" }, { "name": "str", "type": "String" }, { "name": "arr", "type": "Array(UInt8)" } ], "data": [ ["42", "hello", "[0,1]"], ["43", "hello", "[0,1,2]"], ["44", "hello", "[0,1,2,3]"] ], "rows": 3, "rowsbeforelimitatleast": 3, "statistics": { "elapsed": 0.001572097, "rows_read": 3, "bytes_read": 24 } } ``` In this format, all data is represented as a single JSON Array. Note that JSONCompactColumns output format buffers all data in memory to output it as a single block and it can lead to high memory consumption Example: ```json [ [42, 43, 44], ["hello", "hello", "hello"], [[0,1], [0,1,2], [0,1,2,3]] ] ``` Columns that are not present in the block will be filled with default values (you can use setting here) In this format, ClickHouse outputs each row as a separated, newline-delimited JSON

Example: ```json {"num":42,"str":"hello","arr":[0,1]} {"num":43,"str":"hello","arr":[0,1,2]} {"num":44,"str":"hello","arr":[0,1,2,3]} ``` While importing data columns with unknown names will be skipped if setting is set to 1. Differs from JSONEachRow only in that JSON is pretty formatted with new line delimiters and 4 space indents. Suitable only for output. Example ```json { "num": "42", "str": "hello", "arr": [ "0", "1" ], "tuple": { "num": 42, "str": "world" } } { "num": "43", "str": "hello", "arr": [ "0", "1", "2" ], "tuple": { "num": 43, "str": "world" } } ``` Differs from JSONEachRow only in that data fields are output in strings, not in typed JSON values. Example: ```json {"num":"42","str":"hello","arr":"[0,1]"} {"num":"43","str":"hello","arr":"[0,1,2]"} {"num":"44","str":"hello","arr":"[0,1,2,3]"} ``` Differs from JSONEachRow only in that data rows are output in arrays, not in objects. Example: ```json [42, "hello", [0,1]] [43, "hello", [0,1,2]] [44, "hello", [0,1,2,3]] ``` Differs from JSONCompactEachRow only in that data fields are output in strings, not in typed JSON values. Example: ```json ["42", "hello", "[0,1]"] ["43", "hello", "[0,1,2]"] ["44", "hello", "[0,1,2,3]"] ``` Differs from `JSONEachRow`/`JSONStringsEachRow` in that ClickHouse will also yield progress information as JSON values. ```json {"row":{"num":42,"str":"hello","arr":[0,1]}} {"row":{"num":43,"str":"hello","arr":[0,1,2]}} {"row":{"num":44,"str":"hello","arr":[0,1,2,3]}} {"progress":{"readrows":"3","readbytes":"24","writtenrows":"0","writtenbytes":"0","totalrowsto_read":"3"}} ``` Differs from `JSONCompactEachRow` format in that it also prints the header row with column names, similar to . :::note If setting is set to 1, the columns from input data will be mapped to the columns from the table by their names, columns with unknown names will be skipped if setting is set to 1. Otherwise, the first row will be skipped. ::: Differs from `JSONCompactEachRow` format in that it also prints two header rows with column names and types, similar to . :::note If setting is set to 1, the columns from input data will be mapped to the columns from the table by their names, columns with unknown names will be skipped if setting is set to 1. Otherwise, the first row will be skipped. If setting is set to 1, the types from input data will be compared with the types of the corresponding columns from the table. Otherwise, the second row will be skipped. ::: Differs from `JSONCompactStringsEachRow` in that in that it also prints the header row with column names, similar to . :::note If setting is set to 1, the columns from input data will be mapped to the columns from the table by their names, columns with unknown names will be skipped if setting is set to 1. Otherwise, the first row will be skipped. ::: Differs from `JSONCompactStringsEachRow` in that it also prints two header rows with column names and types, similar to . :::note If setting is set to 1, the columns from input data will be mapped to the columns from the table by their names, columns with unknown names will be skipped if setting is set to 1. Otherwise, the first row will be skipped. If setting is set to 1, the types from input data will be compared with the types of the corresponding columns from the table. Otherwise, the second row will be skipped. ::: ```json ["num", "str", "arr"] ["Int32", "String", "Array(UInt8)"] [42, "hello", [0,1]] [43, "hello", [0,1,2]] [44, "hello", [0,1,2,3]] ``` In this format, all data is represented as a single JSON Object, each row is represented as a separate field of this object similar to JSONEachRow format. Example: ```json { "row_1": {"num": 42, "str": "hello", "arr": [0,1]}, "row_2": {"num": 43, "str": "hello", "arr": [0,1,2]}, "row_3": {"num": 44, "str": "hello", "arr": [0,1,2,3]} } ``` To use an object name as a column value you can use the special setting

The value of this setting is set to the name of a column, that is used as JSON key for a row in the resulting object. Examples: For output: Let's say we have the table `test` with two columns: ``` object_namenumber first_obj 1 second_obj 2 third_obj 3 ``` Let's output it in `JSONObjectEachRow` format and use `formatjsonobjecteachrowcolumnforobjectname` setting: ```sql select * from test settings formatjsonobjecteachrowcolumnforobjectname='object_name' ``` The output: ```json { "first_obj": {"number": 1}, "second_obj": {"number": 2}, "third_obj": {"number": 3} } ``` For input: Let's say we stored output from the previous example in a file named `data.json`: ```sql select * from file('data.json', JSONObjectEachRow, 'objectname String, number UInt64') settings formatjsonobjecteachrowcolumnforobjectname='objectname' ``` ``` object_namenumber first_obj 1 second_obj 2 third_obj 3 ``` It also works in schema inference: ```sql desc file('data.json', JSONObjectEachRow) settings formatjsonobjecteachrowcolumnforobjectname='object_name' ``` ``` nametype object_name String number Nullable(Int64) ``` ``` sql INSERT INTO UserActivity FORMAT JSONEachRow {"PageViews":5, "UserID":"4324182021466249494", "Duration":146,"Sign":-1} {"UserID":"4324182021466249494","PageViews":6,"Duration":185,"Sign":1} ``` ClickHouse allows: Any order of key-value pairs in the object. Omitting some values. ClickHouse ignores spaces between elements and commas after the objects. You can pass all the objects in one line. You do not have to separate them with line breaks. Omitted values processing ClickHouse substitutes omitted values with the default values for the corresponding . If `DEFAULT expr` is specified, ClickHouse uses different substitution rules depending on the setting. Consider the following table: ``` sql CREATE TABLE IF NOT EXISTS example_table ( x UInt32, a DEFAULT x * 2 ) ENGINE = Memory; ``` If `inputformatdefaultsforomitted_fields = 0`, then the default value for `x` and `a` equals `0` (as the default value for the `UInt32` data type). If `inputformatdefaultsforomitted_fields = 1`, then the default value for `x` equals `0`, but the default value of `a` equals `x * 2`. :::note When inserting data with `inputformatdefaultsforomittedfields = 1`, ClickHouse consumes more computational resources, compared to insertion with `inputformatdefaultsforomittedfields = 0`. ::: Consider the `UserActivity` table as an example: ``` response UserIDPageViewsDurationSign 4324182021466249494 5 146 -1 4324182021466249494 6 185 1 ``` The query `SELECT * FROM UserActivity FORMAT JSONEachRow` returns: ``` response {"UserID":"4324182021466249494","PageViews":5,"Duration":146,"Sign":-1} {"UserID":"4324182021466249494","PageViews":6,"Duration":185,"Sign":1} ``` Unlike the format, there is no substitution of invalid UTF-8 sequences. Values are escaped in the same way as for `JSON`. :::info Any set of bytes can be output in the strings. Use the `JSONEachRow` format if you are sure that the data in the table can be formatted as JSON without losing any information. ::: If you have a table with data type columns, you can insert JSON data with the same structure. Enable this feature with the setting. For example, consider the following table: ``` sql CREATE TABLE jsoneachrow_nested (n Nested (s String, i Int32) ) ENGINE = Memory ``` As you can see in the `Nested` data type description, ClickHouse treats each component of the nested structure as a separate column (`n.s` and `n.i` for our table). You can insert data in the following way: ``` sql INSERT INTO jsoneachrow_nested FORMAT JSONEachRow {"n.s": ["abc", "def"], "n.i": [1, 23]} ``` To insert data as a hierarchical JSON object, set . ``` json { "n": { "s": ["abc", "def"], "i": [1, 23] } } ``` Without this setting, ClickHouse throws an exception. ``` sql SELECT name, value FROM system.settings WHERE name = 'inputformatimportnestedjson' ``` ``` response namevalue inputformatimportnestedjson 0 ``` ``` sql INSERT INTO jsoneachrow_nested FORMAT JSONEachRow {"n": {"s": ["abc", "def"], "i": [1, 23]}} ``` ``` response Code:

DB::Exception: Unknown field found while parsing JSONEachRow format: n: (at row 1) ``` ``` sql SET inputformatimportnestedjson=1 INSERT INTO jsoneachrow_nested FORMAT JSONEachRow {"n": {"s": ["abc", "def"], "i": [1, 23]}} SELECT * FROM jsoneachrow_nested ``` ``` response n.sn.i ['abc','def'] [1,23] ``` - map nested JSON data to nested tables (it works for JSONEachRow format). Default value - `false`. - allow to parse bools as numbers in JSON input formats. Default value - `true`. - allow to parse bools as strings in JSON input formats. Default value - `true`. - allow to parse numbers as strings in JSON input formats. Default value - `true`. - allow to parse JSON arrays as strings in JSON input formats. Default value - `true`. - allow to parse JSON objects as strings in JSON input formats. Default value - `true`. - parse named tuple columns as JSON objects. Default value - `true`. - try to infer numbers from string fields while schema inference. Default value - `false`. - try to infer named tuple from JSON objects during schema inference. Default value - `true`. - use type String for keys that contains only Nulls or empty objects/arrays during schema inference in JSON input formats. Default value - `true`. - insert default values for missing elements in JSON object while parsing named tuple. Default value - `true`. - ignore unknown keys in json object for named tuples. Default value - `false`. - allow variable number of columns in JSONCompact/JSONCompactEachRow format, ignore extra columns and use default values on missing columns. Default value - `false`. - throw an exception if JSON string contains bad escape sequence. If disabled, bad escape sequences will remain as is in the data. Default value - `true`. - controls quoting of 64-bit integers in JSON output format. Default value - `true`. - controls quoting of 64-bit floats in JSON output format. Default value - `false`. - enables '+nan', '-nan', '+inf', '-inf' outputs in JSON output format. Default value - `false`. - controls quoting of decimals in JSON output format. Default value - `false`. - controls escaping forward slashes for string outputs in JSON output format. Default value - `true`. - serialize named tuple columns as JSON objects. Default value - `true`. - output a JSON array of all rows in JSONEachRow(Compact) format. Default value - `false`. - enables validation of UTF-8 sequences in JSON output formats (note that it doesn't impact formats JSON/JSONCompact/JSONColumnsWithMetadata, they always validate utf8). Default value - `false`. In this format, ClickHouse formats/parses data as a sequence of BSON documents without any separator between them. Each row is formatted as a single document and each column is formatted as a single BSON document field with column name as a

For output it uses the following correspondence between ClickHouse types and BSON types: | ClickHouse type | BSON Type | |--|| | | `\x08` boolean | | / | `\x10` int32 | | / | `\x10` int32 | | | `\x10` int32 | | | `\x12` int64 | | | `\x12` int64 | | | `\x01` double | | / | `\x10` int32 | | | `\x12` int64 | | | `\x09` datetime | | | `\x10` int32 | | | `\x12` int64 | | | `\x05` binary, `\x00` binary subtype, size = 16 | | | `\x05` binary, `\x00` binary subtype, size = 32 | | | `\x05` binary, `\x00` binary subtype, size = 16 | | | `\x05` binary, `\x00` binary subtype, size = 32 | | / | `\x05` binary, `\x00` binary subtype or \x02 string if setting outputformatbsonstringas_string is enabled | | | `\x05` binary, `\x04` uuid subtype, size = 16 | | | `\x04` array | | | `\x04` array | | | `\x03` document | | | `\x03` document | | | `\x10` int32 | | | `\x05` binary, `\x00` binary subtype | For input it uses the following correspondence between BSON types and ClickHouse types: | BSON Type | ClickHouse Type | ||| | `\x01` double | | | `\x02` string | / | | `\x03` document | / | | `\x04` array | / | | `\x05` binary, `\x00` binary subtype | // | | `\x05` binary, `\x02` old binary subtype | / | | `\x05` binary, `\x03` old uuid subtype | | | `\x05` binary, `\x04` uuid subtype | | | `\x07` ObjectId | / | | `\x08` boolean | | | `\x09` datetime | | | `\x0A` null value | | | `\x0D` JavaScript code | / | | `\x0E` symbol | / | | `\x10` int32 | /// | | `\x12` int64 | // | Other BSON types are not supported. Also, it performs conversion between different integer types (for example, you can insert BSON int32 value into ClickHouse UInt8). Big integers and decimals (Int128/UInt128/Int256/UInt256/Decimal128/Decimal256) can be parsed from BSON Binary value with `\x00` binary subtype. In this case this format will validate that the size of binary data equals the size of expected value. Note: this format don't work properly on Big-Endian platforms. - use BSON String type instead of Binary for String columns. Default value - `false`. - allow skipping columns with unsupported types while schema inference for format BSONEachRow. Default value - `false`. The most efficient format. Data is written and read by blocks in binary format. For each block, the number of rows, number of columns, column names and types, and parts of columns in this block are recorded one after another. In other words, this format is columnar it does not convert columns to rows. This is the format used in the native interface for interaction between servers, for using the command-line client, and for C++ clients. You can use this format to quickly generate dumps that can only be read by the ClickHouse DBMS. It does not make sense to work with this format yourself. Nothing is output. However, the query is processed, and when using the command-line client, data is transmitted to the client. This is used for tests, including performance testing. Obviously, this format is only appropriate for output, not for parsing. Outputs data as Unicode-art tables, also using ANSI-escape sequences for setting colours in the terminal. A full grid of the table is drawn, and each row occupies two lines in the terminal. Each result block is output as a separate table. This is necessary so that blocks can be output without buffering results (buffering would be necessary in order to pre-calculate the visible width of all the values). is output as ``. Example (shown for the format): ``` sql SELECT * FROM t_null ``` ``` response xy 1 ``` Rows are not escaped in Pretty\* formats. Example is shown for the format: ``` sql SELECT 'String with \'quotes\' and \t character' AS Escaping_test ``` ``` response Escaping_test String with 'quotes' and character ``` To avoid dumping too much data to the terminal, only the first 10,000 rows are printed. If the number of rows is greater than or equal to 10,000, the message Showed first 10 000 is

This format is only appropriate for outputting a query result, but not for parsing (retrieving data to insert in a table). The Pretty format supports outputting total values (when using WITH TOTALS) and extremes (when extremes is set to 1). In these cases, total values and extreme values are output after the main data, in separate tables. Example (shown for the format): ``` sql SELECT EventDate, count() AS c FROM test.hits GROUP BY EventDate WITH TOTALS ORDER BY EventDate FORMAT PrettyCompact ``` ``` response EventDatec 2014-03-17 1406958 2014-03-18 1383658 2014-03-19 1405797 2014-03-20 1353623 2014-03-21 1245779 2014-03-22 1031592 2014-03-23 1046491 Totals: EventDatec 1970-01-01 8873898 Extremes: EventDatec 2014-03-17 1031592 2014-03-23 1406958 ``` Differs from in that ANSI-escape sequences arent used. This is necessary for displaying this format in a browser, as well as for using the watch command-line utility. Example: ``` bash $ watch -n1 "clickhouse-client --query='SELECT event, value FROM system.events FORMAT PrettyCompactNoEscapes'" ``` You can use the HTTP interface for displaying in the browser. Differs from in that up to 10,000 rows are buffered, then output as a single table, not by blocks. Differs from in that up to 10,000 rows are buffered, then output as a single table, not by blocks. Differs from in that the grid is drawn between rows and the result is more compact. This format is used by default in the command-line client in interactive mode. Differs from in that ANSI-escape sequences arent used. This is necessary for displaying this format in a browser, as well as for using the watch command-line utility. Differs from in that up to 10,000 rows are buffered, then output as a single table, not by blocks. Differs from in that up to 10,000 rows are buffered, then output as a single table, not by blocks. Differs from in that whitespace (space characters) is used instead of the grid. Differs from in that ANSI-escape sequences arent used. This is necessary for displaying this format in a browser, as well as for using the watch command-line utility. Differs from in that up to 10,000 rows are buffered, then output as a single table, not by blocks. Differs from in that up to 10,000 rows are buffered, then output as a single table, not by blocks. - rows limit for Pretty formats. Default value - `10000`. - maximum width to pad all values in a column in Pretty formats. Default value - `250`. - Maximum width of value to display in Pretty formats. If greater - it will be cut. Default value - `10000`. - use ANSI escape sequences to paint colors in Pretty formats. Default value - `true`. - Charset for printing grid borders. Available charsets: ASCII, UTF-8. Default value - `UTF-8`. - Add row numbers before each row for pretty output format. Default value - `true`. Formats and parses data by row in binary format. Rows and values are listed consecutively, without separators. Because data is in the binary format the delimiter after `FORMAT RowBinary` is strictly specified as next: any number of whitespaces (`' '` - space, code `0x20`; `'\t'` - tab, code `0x09`; `'\f'` - form feed, code `0x0C`) followed by exactly one new line sequence (Windows style `"\r\n"` or Unix style `'\n'`), immediately followed by binary data. This format is less efficient than the Native format since it is row-based. Integers use fixed-length little-endian representation. For example, UInt64 uses 8 bytes. DateTime is represented as UInt32 containing the Unix timestamp as the value. Date is represented as a UInt16 object that contains the number of days since 1970-01-01 as the

String is represented as a varint length (unsigned ), followed by the bytes of the string. FixedString is represented simply as a sequence of bytes. Array is represented as a varint length (unsigned ), followed by successive elements of the array. For support, an additional byte containing 1 or 0 is added before each value. If 1, then the value is `NULL` and this byte is interpreted as a separate value. If 0, the value after the byte is not `NULL`. Similar to , but with added header: -encoded number of columns (N) N `String`s specifying column names :::note If setting is set to 1, the columns from input data will be mapped to the columns from the table by their names, columns with unknown names will be skipped if setting is set to 1. Otherwise, the first row will be skipped. ::: Similar to , but with added header: -encoded number of columns (N) N `String`s specifying column names N `String`s specifying column types :::note If setting is set to 1, the columns from input data will be mapped to the columns from the table by their names, columns with unknown names will be skipped if setting is set to 1. Otherwise, the first row will be skipped. If setting is set to 1, the types from input data will be compared with the types of the corresponding columns from the table. Otherwise, the second row will be skipped. ::: Similar to , but with an extra byte before each column that indicates if default value should be used. Examples: ```sql :) select * from format('RowBinaryWithDefaults', 'x UInt32 default 42, y UInt32', x'010001000000') xy 42 1 ``` For column `x` there is only one byte `01` that indicates that default value should be used and no other data after this byte is provided. For column `y` data starts with byte `00` that indicates that column has actual value that should be read from the subsequent data `01000000`. - The maximum allowed size for String in RowBinary format. Default value - `1GiB`. Prints every row in brackets. Rows are separated by commas. There is no comma after the last row. The values inside the brackets are also comma-separated. Numbers are output in a decimal format without quotes. Arrays are output in square brackets. Strings, dates, and dates with times are output in quotes. Escaping rules and parsing are similar to the format. During formatting, extra spaces arent inserted, but during parsing, they are allowed and skipped (except for spaces inside array values, which are not allowed). is represented as `NULL`. The minimum set of characters that you need to escape when passing data in Values format: single quotes and backslashes. This is the format that is used in `INSERT INTO t VALUES ...`, but you can also use it for formatting query results. - if the field could not be parsed by streaming parser, run SQL parser and try to interpret it as SQL expression. Default value - `true`. -if the field could not be parsed by streaming parser, run SQL parser, deduce template of the SQL expression, try to parse all rows using template and then interpret expression for all rows. Default value - `true`. - when parsing and interpreting expressions using template, check actual type of literal to avoid possible overflow and precision issues. Default value - `true`. Prints each value on a separate line with the column name

This format is convenient for printing just one or a few rows if each row consists of a large number of columns. is output as ``. Example: ``` sql SELECT * FROM t_null FORMAT Vertical ``` ``` response Row 1: x: 1 y: ``` Rows are not escaped in Vertical format: ``` sql SELECT 'string with \'quotes\' and \t with some special \n characters' AS test FORMAT Vertical ``` ``` response Row 1: test: string with 'quotes' and with some special characters ``` This format is only appropriate for outputting a query result, but not for parsing (retrieving data to insert in a table). XML format is suitable only for output, not for parsing. Example: ``` xml <?xml version='1.0' encoding='UTF-8' ?> <result> <meta> <columns> <column> <name>SearchPhrase</name> <type>String</type> </column> <column> <name>count()</name> <type>UInt64</type> </column> </columns> </meta> <data> <row> <SearchPhrase></SearchPhrase> <field>8267016</field> </row> <row> <SearchPhrase>bathroom interior design</SearchPhrase> <field>2166</field> </row> <row> <SearchPhrase>clickhouse</SearchPhrase> <field>1655</field> </row> <row> <SearchPhrase>2014 spring fashion</SearchPhrase> <field>1549</field> </row> <row> <SearchPhrase>freeform photos</SearchPhrase> <field>1480</field> </row> <row> <SearchPhrase>angelina jolie</SearchPhrase> <field>1245</field> </row> <row> <SearchPhrase>omsk</SearchPhrase> <field>1112</field> </row> <row> <SearchPhrase>photos of dog breeds</SearchPhrase> <field>1091</field> </row> <row> <SearchPhrase>curtain designs</SearchPhrase> <field>1064</field> </row> <row> <SearchPhrase>baku</SearchPhrase> <field>1000</field> </row> </data> <rows>10</rows> <rowsbeforelimitatleast>141137</rowsbeforelimitatleast> </result> ``` If the column name does not have an acceptable format, just field is used as the element name. In general, the XML structure follows the JSON structure. Just as for JSON, invalid UTF-8 sequences are changed to the replacement character so the output text will consist of valid UTF-8 sequences. In string values, the characters `<` and `&` are escaped as `<` and `&`. Arrays are output as `<array><elem>Hello</elem><elem>World</elem>...</array>`,and tuples as `<tuple><elem>Hello</elem><elem>World</elem>...</tuple>`. CapnProto is a binary message format similar to and , but not like or . CapnProto messages are strictly typed and not self-describing, meaning they need an external schema description. The schema is applied on the fly and cached for each query. See also . The table below shows supported data types and how they match ClickHouse in `INSERT` and `SELECT` queries. | CapnProto data type (`INSERT`) | ClickHouse data type | CapnProto data type (`SELECT`) | ||--|| | `UINT8`, `BOOL` | | `UINT8` | | `INT8` | | `INT8` | | `UINT16` | , | `UINT16` | | `INT16` | | `INT16` | | `UINT32` | , | `UINT32` | | `INT32` | , | `INT32` | | `UINT64` | | `UINT64` | | `INT64` | , , | `INT64` | | `FLOAT32` | | `FLOAT32` | | `FLOAT64` | | `FLOAT64` | | `TEXT, DATA` | , | `TEXT, DATA` | | `union(T, Void), union(Void, T)` | | `union(T, Void), union(Void, T)` | | `ENUM` | | `ENUM` | | `LIST` | | `LIST` | | `STRUCT` | | `STRUCT` | | `UINT32` | | `UINT32` | | `DATA` | | `DATA` | | `DATA` | | `DATA` | | `DATA` | | `DATA` | | `STRUCT(entries LIST(STRUCT(key Key, value Value)))` | | `STRUCT(entries LIST(STRUCT(key Key, value Value)))` | Integer types can be converted into each other during input/output. For working with `Enum` in CapnProto format use the setting. Arrays can be nested and can have a value of the `Nullable` type as an argument. `Tuple` and `Map` types also can be nested. You can insert CapnProto data from a file into ClickHouse table by the following command: ``` bash $ cat capnprotomessages.bin | clickhouse-client --query "INSERT INTO test.hits SETTINGS formatschema = 'schema:Message' FORMAT CapnProto" ``` Where

looks like this: ``` capnp struct Message { SearchPhrase @0 :Text; c @1 :Uint64; } ``` You can select data from a ClickHouse table and save them into some file in the CapnProto format by the following command: ``` bash $ clickhouse-client --query = "SELECT * FROM test.hits FORMAT CapnProto SETTINGS format_schema = 'schema:Message'" ``` If you don't have an external CapnProto schema for your data, you can still output/input data in CapnProto format using autogenerated schema. For example: ```sql SELECT * FROM test.hits format CapnProto SETTINGS formatcapnprotouseautogenerated_schema=1 ``` In this case ClickHouse will autogenerate CapnProto schema according to the table structure using function and will use this schema to serialize data in CapnProto format. You can also read CapnProto file with autogenerated schema (in this case the file must be created using the same schema): ```bash $ cat hits.bin | clickhouse-client --query "INSERT INTO test.hits SETTINGS formatcapnprotouseautogenerated_schema=1 FORMAT CapnProto" ``` The setting is enabled by default and applies if is not set. You can also save autogenerated schema in the file during input/output using setting . For example: ```sql SELECT * FROM test.hits format CapnProto SETTINGS formatcapnprotouseautogeneratedschema=1, outputformat_schema='path/to/schema/schema.capnp' ``` In this case autogenerated CapnProto schema will be saved in file `path/to/schema/schema.capnp`. Expose metrics in . The output table should have a proper structure. Columns `name` () and `value` (number) are required. Rows may optionally contain `help` () and `timestamp` (number). Column `type` () is either `counter`, `gauge`, `histogram`, `summary`, `untyped` or empty. Each metric value may also have some `labels` (). Several consequent rows may refer to the one metric with different labels. The table should be sorted by metric name (e.g., with `ORDER BY name`). There's special requirements for labels for `histogram` and `summary`, see for the details. Special rules applied to row with labels `{'count':''}` and `{'sum':''}`, they'll be converted to `<metricname>count` and `<metricname>sum` respectively. Example: ``` nametypehelplabelsvaluetimestamp httprequestduration_seconds histogram A histogram of the request duration. {'le':'0.05'} 24054 0 httprequestduration_seconds histogram {'le':'0.1'} 33444 0 httprequestduration_seconds histogram {'le':'0.2'} 100392 0 httprequestduration_seconds histogram {'le':'0.5'} 129389 0 httprequestduration_seconds histogram {'le':'1'} 133988 0 httprequestduration_seconds histogram {'le':'+Inf'} 144320 0 httprequestduration_seconds histogram {'sum':''} 53423 0 httprequeststotal counter Total number of HTTP requests {'method':'post','code':'200'} 1027 1395066363000 httprequeststotal counter {'method':'post','code':'400'} 3 1395066363000 metricwithouttimestampandlabels {} 12.47 0 rpcdurationseconds summary A summary of the RPC duration in seconds. {'quantile':'0.01'} 3102 0 rpcdurationseconds summary {'quantile':'0.05'} 3272 0 rpcdurationseconds summary {'quantile':'0.5'} 4773 0 rpcdurationseconds summary {'quantile':'0.9'} 9001 0 rpcdurationseconds summary {'quantile':'0.99'} 76656 0 rpcdurationseconds summary {'count':''} 2693 0 rpcdurationseconds summary {'sum':''} 17560473 0 something_weird {'problem':'division by zero'} inf -3982045 ``` Will be formatted as: ``` httprequestdurationsecondsbucket{le="0.05"} 24054 httprequestdurationsecondsbucket{le="0.1"} 33444 httprequestdurationsecondsbucket{le="0.5"} 129389 httprequestdurationsecondsbucket{le="1"} 133988 httprequestdurationsecondsbucket{le="+Inf"} 144320 httprequestdurationsecondssum 53423 httprequestdurationsecondscount 144320 httprequeststotal{code="200",method="post"} 1027 1395066363000 httprequeststotal{code="400",method="post"} 3 1395066363000 metricwithouttimestampandlabels 12.47 rpcdurationseconds{quantile="0.01"} 3102 rpcdurationseconds{quantile="0.05"} 3272 rpcdurationseconds{quantile="0.5"} 4773 rpcdurationseconds{quantile="0.9"} 9001 rpcdurationseconds{quantile="0.99"} 76656 rpcdurationseconds_sum 17560473 rpcdurationseconds_count 2693 something_weird{problem="division by zero"} +Inf -3982045 ``` Protobuf - is a format. This format requires an external format schema. The schema is cached between queries. ClickHouse supports both `proto2` and `proto3` syntaxes. Repeated/optional/required fields are supported. Usage examples: ``` sql SELECT * FROM test.table FORMAT Protobuf SETTINGS format_schema = 'schemafile:MessageType' ``` ``` bash cat protobufmessages.bin | clickhouse-client --query "INSERT INTO test.table SETTINGS formatschema='schemafile:MessageType' FORMAT Protobuf" ``` where the file `schemafile.proto` looks like this: ``` capnp syntax = "proto3"; message MessageType { string name = 1; string surname = 2; uint32 birthDate = 3; repeated string phoneNumbers = 4; }; ``` To find the correspondence between table columns and fields of Protocol Buffers message type ClickHouse compares their names. This comparison is case-insensitive and the characters `_` (underscore) and `.` (dot) are considered as equal. If types of a column and a field of Protocol Buffers message are different the necessary conversion is

Nested messages are supported. For example, for the field `z` in the following message type ``` capnp message MessageType { message XType { message YType { int32 z; }; repeated YType y; }; XType x; }; ``` ClickHouse tries to find a column named `x.y.z` (or `xyz` or `X.y_Z` and so on). Nested messages are suitable to input or output a . Default values defined in a protobuf schema like this ``` capnp syntax = "proto2"; message MessageType { optional int32 resultperpage = 3 [default = 10]; } ``` are not applied; the are used instead of them. ClickHouse inputs and outputs protobuf messages in the `length-delimited` format. It means before every message should be written its length as a . See also . If you don't have an external Protobuf schema for your data, you can still output/input data in Protobuf format using autogenerated schema. For example: ```sql SELECT * FROM test.hits format Protobuf SETTINGS formatprotobufuseautogeneratedschema=1 ``` In this case ClickHouse will autogenerate Protobuf schema according to the table structure using function and will use this schema to serialize data in Protobuf format. You can also read Protobuf file with autogenerated schema (in this case the file must be created using the same schema): ```bash $ cat hits.bin | clickhouse-client --query "INSERT INTO test.hits SETTINGS formatprotobufuseautogeneratedschema=1 FORMAT Protobuf" ``` The setting is enabled by default and applies if is not set. You can also save autogenerated schema in the file during input/output using setting . For example: ```sql SELECT * FROM test.hits format Protobuf SETTINGS formatprotobufuseautogeneratedschema=1, outputformatschema='path/to/schema/schema.proto' ``` In this case autogenerated Protobuf schema will be saved in file `path/to/schema/schema.capnp`. To reload Protobuf schema loaded from use statement. ```sql SYSTEM DROP FORMAT SCHEMA CACHE FOR Protobuf ``` Same as but for storing/parsing single Protobuf message without length delimiters. is a row-oriented data serialization framework developed within Apaches Hadoop project. ClickHouse Avro format supports reading and writing . The table below shows supported data types and how they match ClickHouse in `INSERT` and `SELECT` queries. | Avro data type `INSERT` | ClickHouse data type | Avro data type `SELECT` | ||-|-| | `boolean`, `int`, `long`, `float`, `double` | , | `int` | | `boolean`, `int`, `long`, `float`, `double` | , | `long` | | `boolean`, `int`, `long`, `float`, `double` | | `float` | | `boolean`, `int`, `long`, `float`, `double` | | `double` | | `bytes`, `string`, `fixed`, `enum` | | `bytes` or `string` \* | | `bytes`, `string`, `fixed` | | `fixed(N)` | | `enum` | | `enum` | | `array(T)` | | `array(T)` | | `map(V, K)` | | `map(string, K)` | | `union(null, T)`, `union(T, null)` | | `union(null, T)` | | `null` | | `null` | | `int (date)` \ | , | `int (date)` \ | | `long (timestamp-millis)` \ | | `long (timestamp-millis)` \ | | `long (timestamp-micros)` \ | | `long (timestamp-micros)` \ | | `bytes (decimal)` \ | | `bytes (decimal)` \ | | `int` | | `int` | | `fixed(16)` | | `fixed(16)` | | `bytes (decimal)` \ | | `bytes (decimal)` \ | | `string (uuid)` \ | | `string (uuid)` \ | | `fixed(16)` | | `fixed(16)` | | `fixed(32)` | | `fixed(32)` | | `record` | | `record` | \* `bytes` is default, controlled by \ Unsupported Avro logical data types: `time-millis`, `time-micros`, `duration` To insert data from an Avro file into ClickHouse table: ``` bash $ cat

| clickhouse-client --query="INSERT INTO {some_table} FORMAT Avro" ``` The root schema of input Avro file must be of `record` type. To find the correspondence between table columns and fields of Avro schema ClickHouse compares their names. This comparison is case-sensitive. Unused fields are skipped. Data types of ClickHouse table columns can differ from the corresponding fields of the Avro data inserted. When inserting data, ClickHouse interprets data types according to the table above and then the data to corresponding column type. While importing data, when field is not found in schema and setting is enabled, default value will be used instead of error. To select data from ClickHouse table into an Avro file: ``` bash $ clickhouse-client --query="SELECT * FROM {some_table} FORMAT Avro" > file.avro ``` Column names must: start with `[A-Za-z_]` subsequently contain only `[A-Za-z0-9_]` Output Avro file compression and sync interval can be configured with and respectively. Using the ClickHouse function, you can quickly view the inferred format of an Avro file like the following example. This example includes the URL of a publicly accessible Avro file in the ClickHouse S3 public bucket: ``` DESCRIBE url('https://clickhouse-public-datasets.s3.eu-central-1.amazonaws.com/hits.avro','Avro); ``` ``` nametypedefaulttypedefaultexpressioncommentcodecexpressionttlexpression WatchID Int64 JavaEnable Int32 Title String GoodEvent Int32 EventTime Int32 EventDate Date32 CounterID Int32 ClientIP Int32 ClientIP6 FixedString(16) RegionID Int32 ... IslandID FixedString(16) RequestNum Int32 RequestTry Int32 ``` AvroConfluent supports decoding single-object Avro messages commonly used with and . Each Avro message embeds a schema id that can be resolved to the actual schema with help of the Schema Registry. Schemas are cached once resolved. Schema Registry URL is configured with . Same as . To quickly verify schema resolution you can use with : ``` bash $ kafkacat -b kafka-broker -C -t topic1 -o beginning -f '%s' -c 3 | clickhouse-local --input-format AvroConfluent --formatavroschemaregistryurl 'http://schema-registry' -S "field1 Int64, field2 String" -q 'select * from table' 1 a 2 b 3 c ``` To use `AvroConfluent` with : ``` sql CREATE TABLE topic1_stream ( field1 String, field2 String ) ENGINE = Kafka() SETTINGS kafkabrokerlist = 'kafka-broker', kafkatopiclist = 'topic1', kafkagroupname = 'group1', kafka_format = 'AvroConfluent'; -- for debug purposes you can set formatavroschemaregistryurl in a session. -- this way cannot be used in production SET formatavroschemaregistryurl = 'http://schema-registry'; SELECT * FROM topic1_stream; ``` :::note Setting `formatavroschemaregistryurl` needs to be configured in `users.xml` to maintain its value after a restart. Also you can use the `formatavroschemaregistryurl` setting of the `Kafka` table engine. ::: is a columnar storage format widespread in the Hadoop ecosystem. ClickHouse supports read and write operations for this format. The table below shows supported data types and how they match ClickHouse in `INSERT` and `SELECT`

| Parquet data type (`INSERT`) | ClickHouse data type | Parquet data type (`SELECT`) | |--||-| | `BOOL` | | `BOOL` | | `UINT8`, `BOOL` | | `UINT8` | | `INT8` | / | `INT8` | | `UINT16` | | `UINT16` | | `INT16` | / | `INT16` | | `UINT32` | | `UINT32` | | `INT32` | | `INT32` | | `UINT64` | | `UINT64` | | `INT64` | | `INT64` | | `FLOAT` | | `FLOAT` | | `DOUBLE` | | `DOUBLE` | | `DATE` | | `DATE` | | `TIME (ms)` | | `UINT32` | | `TIMESTAMP`, `TIME (us, ns)` | | `TIMESTAMP` | | `STRING`, `BINARY` | | `BINARY` | | `STRING`, `BINARY`, `FIXEDLENGTHBYTEARRAY` | | `FIXEDLENGTHBYTEARRAY` | | `DECIMAL` | | `DECIMAL` | | `LIST` | | `LIST` | | `STRUCT` | | `STRUCT` | | `MAP` | | `MAP` | | `UINT32` | | `UINT32` | | `FIXEDLENGTHBYTEARRAY`, `BINARY` | | `FIXEDLENGTHBYTEARRAY` | | `FIXEDLENGTHBYTEARRAY`, `BINARY` | | `FIXEDLENGTHBYTEARRAY` | Arrays can be nested and can have a value of the `Nullable` type as an argument. `Tuple` and `Map` types also can be nested. Unsupported Parquet data types: `FIXEDSIZEBINARY`, `JSON`, `UUID`, `ENUM`. Data types of ClickHouse table columns can differ from the corresponding fields of the Parquet data inserted. When inserting data, ClickHouse interprets data types according to the table above and then the data to that data type which is set for the ClickHouse table column. You can insert Parquet data from a file into ClickHouse table by the following command: ``` bash $ cat {filename} | clickhouse-client --query="INSERT INTO {some_table} FORMAT Parquet" ``` You can select data from a ClickHouse table and save them into some file in the Parquet format by the following command: ``` bash $ clickhouse-client --query="SELECT * FROM {sometable} FORMAT Parquet" > {somefile.pq} ``` To exchange data with Hadoop, you can use . - row group size in rows while data output. Default value - `1000000`. - use Parquet String type instead of Binary for String columns. Default value - `false`. - allow inserting array of structs into table in Parquet input format. Default value - `false`. - ignore case when matching Parquet columns with ClickHouse columns. Default value - `false`. - allow missing columns while reading Parquet data. Default value - `false`. - allow skipping columns with unsupported types while schema inference for Parquet format. Default value - `false`. - min bytes required for local read (file) to do seek, instead of read with ignore in Parquet input format. Default value - `8192`. - use Parquet FIXEDLENGTHBYTE_ARRAY type instead of Binary/String for FixedString columns. Default value - `true`. - The version of Parquet format used in output format. Default value - `2.latest`. - compression method used in output Parquet format. Default value - `lz4`. Special format for reading Parquet file metadata (https://parquet.apache.org/docs/file-format/metadata/). It always outputs one row with the next structure/content: num_columns - the number of columns num_rows - the total number of rows numrowgroups - the total number of row groups format_version - parquet format version, always 1.0 or 2.6 totaluncompressedsize - total uncompressed bytes size of the data, calculated as the sum of totalbytesize from all row groups totalcompressedsize - total compressed bytes size of the data, calculated as the sum of totalcompressedsize from all row groups columns - the list of columns metadata with the next structure: name - column name path - column path (differs from name for nested column) maxdefinitionlevel - maximum definition level maxrepetitionlevel - maximum repetition level physical_type - column physical type logical_type - column logical type compression - compression used for this column totaluncompressedsize - total uncompressed bytes size of the column, calculated as the sum of totaluncompressedsize of the column from all row groups totalcompressedsize - total compressed bytes size of the column, calculated as the sum of totalcompressedsize of the column from all row groups spacesaved - percent of space saved by compression, calculated as (1 -

encodings - the list of encodings used for this column row_groups - the list of row groups metadata with the next structure: num_columns - the number of columns in the row group num_rows - the number of rows in the row group totaluncompressedsize - total uncompressed bytes size of the row group totalcompressedsize - total compressed bytes size of the row group columns - the list of column chunks metadata with the next structure: name - column name path - column path totalcompressedsize - total compressed bytes size of the column totaluncompressedsize - total uncompressed bytes size of the row group have_statistics - boolean flag that indicates if column chunk metadata contains column statistics statistics - column chunk statistics (all fields are NULL if have_statistics = false) with the next structure: num_values - the number of non-null values in the column chunk null_count - the number of NULL values in the column chunk distinct_count - the number of distinct values in the column chunk min - the minimum value of the column chunk max - the maximum column of the column chunk Example: ```sql SELECT * FROM file(data.parquet, ParquetMetadata) format PrettyJSONEachRow ``` ```json { "num_columns": "2", "num_rows": "100000", "numrowgroups": "2", "format_version": "2.6", "metadata_size": "577", "totaluncompressedsize": "282436", "totalcompressedsize": "26633", "columns": [ { "name": "number", "path": "number", "maxdefinitionlevel": "0", "maxrepetitionlevel": "0", "physical_type": "INT32", "logical_type": "Int(bitWidth=16, isSigned=false)", "compression": "LZ4", "totaluncompressedsize": "133321", "totalcompressedsize": "13293", "space_saved": "90.03%", "encodings": [ "RLE_DICTIONARY", "PLAIN", "RLE" ] }, { "name": "concat('Hello', toString(modulo(number, 1000)))", "path": "concat('Hello', toString(modulo(number, 1000)))", "maxdefinitionlevel": "0", "maxrepetitionlevel": "0", "physicaltype": "BYTEARRAY", "logical_type": "None", "compression": "LZ4", "totaluncompressedsize": "149115", "totalcompressedsize": "13340", "space_saved": "91.05%", "encodings": [ "RLE_DICTIONARY", "PLAIN", "RLE" ] } ], "row_groups": [ { "num_columns": "2", "num_rows": "65409", "totaluncompressedsize": "179809", "totalcompressedsize": "14163", "columns": [ { "name": "number", "path": "number", "totalcompressedsize": "7070", "totaluncompressedsize": "85956", "have_statistics": true, "statistics": { "num_values": "65409", "null_count": "0", "distinct_count": null, "min": "0", "max": "999" } }, { "name": "concat('Hello', toString(modulo(number, 1000)))", "path": "concat('Hello', toString(modulo(number, 1000)))", "totalcompressedsize": "7093", "totaluncompressedsize": "93853", "have_statistics": true, "statistics": { "num_values": "65409", "null_count": "0", "distinct_count": null, "min": "Hello0", "max": "Hello999" } } ] }, ... ] } ``` comes with two built-in columnar storage formats. ClickHouse supports read and write operations for these formats. `Arrow` is Apache Arrows "file mode" format. It is designed for in-memory random access. The table below shows supported data types and how they match ClickHouse in `INSERT` and `SELECT` queries. | Arrow data type (`INSERT`) | ClickHouse data type | Arrow data type (`SELECT`) | |--||-| | `BOOL` | | `BOOL` | | `UINT8`, `BOOL` | | `UINT8` | | `INT8` | / | `INT8` | | `UINT16` | | `UINT16` | | `INT16` | / | `INT16` | | `UINT32` | | `UINT32` | | `INT32` | | `INT32` | | `UINT64` | | `UINT64` | | `INT64` | | `INT64` | | `FLOAT`, `HALF_FLOAT` | | `FLOAT32` | | `DOUBLE` | | `FLOAT64` | | `DATE32` | | `UINT16` | | `DATE64` | | `UINT32` | | `TIMESTAMP`, `TIME32`, `TIME64` | | `UINT32` | | `STRING`, `BINARY` | | `BINARY` | | `STRING`, `BINARY`, `FIXEDSIZEBINARY` | | `FIXEDSIZEBINARY` | | `DECIMAL` | | `DECIMAL` | | `DECIMAL256` | | `DECIMAL256` | | `LIST` | | `LIST` | | `STRUCT` | | `STRUCT` | | `MAP` | | `MAP` | | `UINT32` | | `UINT32` | | `FIXEDSIZEBINARY`, `BINARY` | | `FIXEDSIZEBINARY` | | `FIXEDSIZEBINARY`, `BINARY` | | `FIXEDSIZEBINARY` | Arrays can be nested and can have a value of the `Nullable` type as an argument. `Tuple` and `Map` types also can be nested. The `DICTIONARY` type is supported for `INSERT` queries, and for `SELECT` queries there is an setting that allows to output type as a `DICTIONARY` type. Unsupported Arrow data types: `FIXEDSIZEBINARY`, `JSON`, `UUID`, `ENUM`. The data types of ClickHouse table columns do not have to match the corresponding Arrow data

When inserting data, ClickHouse interprets data types according to the table above and then the data to the data type set for the ClickHouse table column. You can insert Arrow data from a file into ClickHouse table by the following command: ``` bash $ cat filename.arrow | clickhouse-client --query="INSERT INTO some_table FORMAT Arrow" ``` You can select data from a ClickHouse table and save them into some file in the Arrow format by the following command: ``` bash $ clickhouse-client --query="SELECT * FROM {some_table} FORMAT Arrow" > {filename.arrow} ``` - enable output ClickHouse LowCardinality type as Dictionary Arrow type. Default value - `false`. - use 64-bit integer type for Dictionary indexes. Default value - `false`. - use signed integer type for Dictionary indexes. Default value - `true`. - use Arrow String type instead of Binary for String columns. Default value - `false`. - ignore case when matching Arrow columns with ClickHouse columns. Default value - `false`. - allow missing columns while reading Arrow data. Default value - `false`. - allow skipping columns with unsupported types while schema inference for Arrow format. Default value - `false`. - use Arrow FIXEDSIZEBINARY type instead of Binary/String for FixedString columns. Default value - `true`. - compression method used in output Arrow format. Default value - `lz4_frame`. `ArrowStream` is Apache Arrows stream mode format. It is designed for in-memory stream processing. is a columnar storage format widespread in the ecosystem. The table below shows supported data types and how they match ClickHouse in `INSERT` and `SELECT` queries. | ORC data type (`INSERT`) | ClickHouse data type | ORC data type (`SELECT`) | ||-|--| | `Boolean` | | `Boolean` | | `Tinyint` | / | `Tinyint` | | `Smallint` | / | `Smallint` | | `Int` | | `Int` | | `Bigint` | | `Bigint` | | `Float` | | `Float` | | `Double` | | `Double` | | `Decimal` | | `Decimal` | | `Date` | | `Date` | | `Timestamp` | | `Timestamp` | | `String`, `Char`, `Varchar`, `Binary` | | `Binary` | | `List` | | `List` | | `Struct` | | `Struct` | | `Map` | | `Map` | | `Int` | | `Int` | | `Binary` | | `Binary` | | `Binary` | | `Binary` | | `Binary` | | `Binary` | Other types are not supported. Arrays can be nested and can have a value of the `Nullable` type as an argument. `Tuple` and `Map` types also can be nested. The data types of ClickHouse table columns do not have to match the corresponding ORC data fields. When inserting data, ClickHouse interprets data types according to the table above and then the data to the data type set for the ClickHouse table column. You can insert ORC data from a file into ClickHouse table by the following command: ``` bash $ cat filename.orc | clickhouse-client --query="INSERT INTO some_table FORMAT ORC" ``` You can select data from a ClickHouse table and save them into some file in the ORC format by the following command: ``` bash $ clickhouse-client --query="SELECT * FROM {some_table} FORMAT ORC" > {filename.orc} ``` - use Arrow String type instead of Binary for String columns. Default value - `false`. - compression method used in output ORC format. Default value - `none`. - ignore case when matching Arrow columns with ClickHouse columns. Default value - `false`. - allow missing columns while reading Arrow data. Default value - `false`. - allow skipping columns with unsupported types while schema inference for Arrow format. Default value - `false`. To exchange data with Hadoop, you can use

Special input format that doesn't read any data from file and returns only one row with column of type `UInt8`, name `dummy` and value `0` (like `system.one` table). Can be used with virtual columns `file/path` to list all files without reading actual data. Example: Query: ```sql SELECT _file FROM file('path/to/files/data*', One); ``` Result: ```text _file data.csv _file data.jsonl _file data.tsv _file data.parquet ``` This function is designed to load a NumPy array from a .npy file into ClickHouse. The NumPy file format is a binary format used for efficiently storing arrays of numerical data. During import, ClickHouse treats top level dimension as an array of rows with single column. Supported Npy data types and their corresponding type in ClickHouse: | Npy data type (`INSERT`) | ClickHouse data type | Npy data type (`SELECT`) | |--|--|--| | `i1` | | `i1` | | `i2` | | `i2` | | `i4` | | `i4` | | `i8` | | `i8` | | `u1`, `b1` | | `u1` | | `u2` | | `u2` | | `u4` | | `u4` | | `u8` | | `u8` | | `f2`, `f4` | | `f4` | | `f8` | | `f8` | | `S`, `U` | | `S` | | | | `S` | Example of saving an array in .npy format using Python ```Python import numpy as np arr = np.array([[[1],[2],[3]],[[4],[5],[6]]]) np.save('example_array.npy', arr) ``` Example of reading a NumPy file in ClickHouse Query: ```sql SELECT * FROM file('example_array.npy', Npy) ``` Result: ``` array [[1],[2],[3]] [[4],[5],[6]] ``` Selecting Data You can select data from a ClickHouse table and save them into some file in the Npy format by the following command: ```bash $ clickhouse-client --query="SELECT {column} FROM {some_table} FORMAT Npy" > {filename.npy} ``` In this format, every line of input data is interpreted as a single string value. This format can only be parsed for table with a single field of type . The remaining columns must be set to or , or omitted. Example Query: ``` sql DROP TABLE IF EXISTS lineasstring; CREATE TABLE lineasstring (field String) ENGINE = Memory; INSERT INTO lineasstring FORMAT LineAsString "I love apple", "I love banana", "I love orange"; SELECT * FROM lineasstring; ``` Result: ``` text field "I love apple", "I love banana", "I love orange"; ``` Each line of imported data is parsed according to the regular expression. When working with the `Regexp` format, you can use the following settings: `format_regexp` . Contains regular expression in the format. `formatregexpescaping_rule` . The following escaping rules are supported: CSV (similarly to ) JSON (similarly to ) Escaped (similarly to ) Quoted (similarly to ) Raw (extracts subpatterns as a whole, no escaping rules, similarly to ) `formatregexpskipunmatched` . Defines the need to throw an exception in case the `formatregexp` expression does not match the imported data. Can be set to `0` or `1`. Usage The regular expression from setting is applied to every line of imported data. The number of subpatterns in the regular expression must be equal to the number of columns in imported dataset. Lines of the imported data must be separated by newline character `'\n'` or DOS-style newline `"\r\n"`. The content of every matched subpattern is parsed with the method of corresponding data type, according to setting. If the regular expression does not match the line and is set to 1, the line is silently skipped. Otherwise, exception is thrown. Example Consider the file

```text id: 1 array: [1,2,3] string: str1 date: 2020-01-01 id: 2 array: [1,2,3] string: str2 date: 2020-01-02 id: 3 array: [1,2,3] string: str3 date: 2020-01-03 ``` and the table: ```sql CREATE TABLE impregextable (id UInt32, array Array(UInt32), string String, date Date) ENGINE = Memory; ``` Import command: ```bash $ cat data.tsv | clickhouse-client --query "INSERT INTO impregextable SETTINGS formatregexp='id: (.+?) array: (.+?) string: (.+?) date: (.+?)', formatregexpescapingrule='Escaped', formatregexpskip_unmatched=0 FORMAT Regexp;" ``` Query: ```sql SELECT * FROM impregextable; ``` Result: ```text idarraystringdate 1 [1,2,3] str1 2020-01-01 2 [1,2,3] str2 2020-01-02 3 [1,2,3] str3 2020-01-03 ``` The file name containing the format schema is set by the setting `format_schema`. Its required to set this setting when it is used one of the formats `Cap'n Proto` and `Protobuf`. The format schema is a combination of a file name and the name of a message type in this file, delimited by a colon, e.g.`schemafile.proto:MessageType`. If the file has the standard extension for the format (for example, `.proto` for `Protobuf`), it can be omitted and in this case, the format schema looks like `schemafile:MessageType`. If you input or output data via the in the , the file name specified in the format schema can contain an absolute path or a path relative to the current directory on the client. If you use the client in the , the path to the schema must be relative due to security reasons. If you input or output data via the the file name specified in the format schema should be located in the directory specified in in the server configuration. Some formats such as `CSV`, `TabSeparated`, `TSKV`, `JSONEachRow`, `Template`, `CustomSeparated` and `Protobuf` can skip broken row if parsing error occurred and continue parsing from the beginning of next row. See and settings. Limitations: In case of parsing error `JSONEachRow` skips all data until the new line (or EOF), so rows must be delimited by `\n` to count errors correctly. `Template` and `CustomSeparated` use delimiter after the last column and delimiter between rows to find the beginning of next row, so skipping errors works only if at least one of them is not empty. In this format, all input data is read to a single value. It is possible to parse only a table with a single field of type or similar. The result is output in binary format without delimiters and escaping. If more than one value is output, the format is ambiguous, and it will be impossible to read the data back. Below is a comparison of the formats `RawBLOB` and . `RawBLOB`: data is output in binary format, no escaping; there are no delimiters between values; no newline at the end of each value. `TabSeparatedRaw`: data is output without escaping; the rows contain values separated by tabs; there is a line feed after the last value in every row. The following is a comparison of the `RawBLOB` and formats. `RawBLOB`: String fields are output without being prefixed by length. `RowBinary`: String fields are represented as length in varint format (unsigned [LEB128] (https://en.wikipedia.org/wiki/LEB128)), followed by the bytes of the string. When an empty data is passed to the `RawBLOB` input, ClickHouse throws an exception: ``` text Code: 108. DB::Exception: No data to insert ``` Example ``` bash $ clickhouse-client --query "CREATE TABLE {some_table} (a String) ENGINE = Memory;" $ cat {filename} | clickhouse-client --query="INSERT INTO {some_table} FORMAT RawBLOB" $ clickhouse-client --query "SELECT * FROM {some_table} FORMAT RawBLOB" | md5sum ``` Result: ``` text f9725a22f9191e064120d718e26862a9 - ``` ClickHouse supports reading and writing data

| MessagePack data type (`INSERT`) | ClickHouse data type | MessagePack data type (`SELECT`) | |--||-| | `uint N`, `positive fixint` | | `uint N` | | `int N`, `negative fixint` | | `int N` | | `bool` | | `uint 8` | | `fixstr`, `str 8`, `str 16`, `str 32`, `bin 8`, `bin 16`, `bin 32` | | `bin 8`, `bin 16`, `bin 32` | | `fixstr`, `str 8`, `str 16`, `str 32`, `bin 8`, `bin 16`, `bin 32` | | `bin 8`, `bin 16`, `bin 32` | | `float 32` | | `float 32` | | `float 64` | | `float 64` | | `uint 16` | | `uint 16` | | `int 32` | | `int 32` | | `uint 32` | | `uint 32` | | `uint 64` | | `uint 64` | | `fixarray`, `array 16`, `array 32` | / | `fixarray`, `array 16`, `array 32` | | `fixmap`, `map 16`, `map 32` | | `fixmap`, `map 16`, `map 32` | | `uint 32` | | `uint 32` | | `bin 8` | | `bin 8` | | `int 8` | | `int 8` | | `bin 8` | | `bin 8` | | `int 32` | | `int 32` | | `int 64` | | `int 64` | | `bin 8` | | `bin 8 ` | Example: Writing to a file ".msgpk": ```sql $ clickhouse-client --query="CREATE TABLE msgpack (array Array(UInt8)) ENGINE = Memory;" $ clickhouse-client --query="INSERT INTO msgpack VALUES ([0, 1, 2, 3, 42, 253, 254, 255]), ([255, 254, 253, 42, 3, 2, 1, 0])"; $ clickhouse-client --query="SELECT * FROM msgpack FORMAT MsgPack" > tmp_msgpack.msgpk; ``` - the number of columns in inserted MsgPack data. Used for automatic schema inference from data. Default value - `0`. - the way how to output UUID in MsgPack format. Default value - `EXT`. ClickHouse supports reading MySQL . It reads all data from INSERT queries belonging to one table in dump. If there are more than one table, by default it reads data from the first one. You can specify the name of the table from which to read data from using settings. If setting is set to 1 and dump contains CREATE query for specified table or column names in INSERT query the columns from input data will be mapped to the columns from the table by their names, columns with unknown names will be skipped if setting is set to 1. This format supports schema inference: if the dump contains CREATE query for the specified table, the structure is extracted from it, otherwise schema is inferred from the data of INSERT queries. Examples: File dump.sql: ```sql /!40101 SET @saved_cs_client = @@character_set_client /; /!50503 SET character_set_client = utf8mb4 /; CREATE TABLE `test` ( `x` int DEFAULT NULL, `y` int DEFAULT NULL ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb40900ai_ci; /!40101 SET character_set_client = @saved_cs_client /; INSERT INTO `test` VALUES (1,NULL),(2,NULL),(3,NULL),(3,NULL),(4,NULL),(5,NULL),(6,7); /!40101 SET @saved_cs_client = @@character_set_client /; /!50503 SET character_set_client = utf8mb4 /; CREATE TABLE `test 3` ( `y` int DEFAULT NULL ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb40900ai_ci; /!40101 SET character_set_client = @saved_cs_client /; INSERT INTO `test 3` VALUES (1); /!40101 SET @saved_cs_client = @@character_set_client /; /!50503 SET character_set_client = utf8mb4 /; CREATE TABLE `test2` ( `x` int DEFAULT NULL ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb40900ai_ci; /!40101 SET character_set_client = @saved_cs_client /; INSERT INTO `test2` VALUES (1),(2),(3); ``` Queries: ```sql DESCRIBE TABLE file(dump.sql, MySQLDump) SETTINGS inputformatmysqldumptable_name = 'test2' ``` ```text nametypedefaulttypedefaultexpressioncommentcodecexpressionttlexpression x Nullable(Int32) ``` ```sql SELECT * FROM

MySQLDump) SETTINGS inputformatmysqldumptable_name = 'test2' ``` ```text x 1 2 3 ``` Parses DWARF debug symbols from an ELF file (executable, library, or object file). Similar to `dwarfdump`, but much faster (hundreds of MB/s) and with SQL. Produces one row for each Debug Information Entry (DIE) in the `.debug_info` section. Includes "null" entries that the DWARF encoding uses to terminate lists of children in the tree. Quick background: `.debuginfo` consists of *units*, corresponding to compilation units. Each unit is a tree of *DIE*s, with a `compileunit` DIE as its root. Each DIE has a tag and a list of attributes. Each attribute has a name and a value (and also a form, which specifies how the value is encoded). The DIEs represent things from the source code, and their tag tells what kind of thing it is. E.g. there are functions (tag = `subprogram`), classes/structs/enums (`classtype`/`structuretype`/`enumerationtype`), variables (`variable`), function arguments (`formalparameter`). The tree structure mirrors the corresponding source code. E.g. a `class_type` DIE can contain `subprogram` DIEs representing methods of the class. Outputs the following columns: `offset` - position of the DIE in the `.debug_info` section `size` - number of bytes in the encoded DIE (including attributes) `tag` - type of the DIE; the conventional "DWTAG" prefix is omitted `unit_name` - name of the compilation unit containing this DIE `unitoffset` - position of the compilation unit containing this DIE in the `.debuginfo` section `ancestor_tags` - array of tags of the ancestors of the current DIE in the tree, in order from innermost to outermost `ancestoroffsets` - offsets of ancestors, parallel to `ancestortags` a few common attributes duplicated from the attributes array for convenience: `name` `linkage_name` - mangled fully-qualified name; typically only functions have it (but not all functions) `decl_file` - name of the source code file where this entity was declared `decl_line` - line number in the source code where this entity was declared parallel arrays describing attributes: `attrname` - name of the attribute; the conventional "DWAT_" prefix is omitted `attrform` - how the attribute is encoded and interpreted; the conventional DWFORM_ prefix is omitted `attr_int` - integer value of the attribute; 0 if the attribute doesn't have a numeric value `attr_str` - string value of the attribute; empty if the attribute doesn't have a string value Example: find compilation units that have the most function definitions (including template instantiations and functions from included header files): ```sql SELECT unit_name, count() AS c FROM file('programs/clickhouse', DWARF) WHERE tag = 'subprogram' AND NOT has(attr_name, 'declaration') GROUP BY unit_name ORDER BY c DESC LIMIT 3 ``` ```text unit_namec ./src/Core/Settings.cpp 28939 ./src/AggregateFunctions/AggregateFunctionSumMap.cpp 23327 ./src/AggregateFunctions/AggregateFunctionUniqCombined.cpp 22649 3 rows in set. Elapsed: 1.487 sec. Processed 139.76 million rows, 1.12 GB (93.97 million rows/s., 752.77 MB/s.) Peak memory usage: 271.92 MiB. ``` You can export results using format to generate output ready to be pasted into your `.md` files: ```sql SELECT number, number * 2 FROM numbers(5) FORMAT Markdown ``` ```results | number | multiply(number, 2) | |-:|-:| | 0 | 0 | | 1 | 2 | | 2 | 4 | | 3 | 6 | | 4 | 8 | ``` Markdown table will be generated automatically and can be used on markdown-enabled platforms, like Github. This format is used only for output. The Form format can be used to read or write a single record in the application/x-www-form-urlencoded format in which data is formatted `key1=value1&key2=value2` Examples: Given a file `data.tmp` placed in the `user_files` path with some URL encoded data: ```text t_page=116&c.e=ls7xfkpm&c.tti.m=raf&rt.start=navigation&rt.bmr=390%2C11%2C10 ``` ```sql SELECT * FROM file(data.tmp, Form) FORMAT vertical; ``` Result: ```text Row 1: t_page: 116 c.e: ls7xfkpm c.tti.m: raf rt.start: