thevar1able/ClickHouse
1
0
Fork 0
mirror of https://github.com/ClickHouse/ClickHouse.git synced 2024-11-26 01:22:04 +00:00
Code Issues Packages Projects Releases Wiki Activity

DOCAPI-5102: JSONEachRow + insert_sample_with_metadata. EN review and RU Translation (#4882)

Browse Source 
* DOCAPI-5102: New setting insert_sample_with_metadata description.

* DOCAPI-5102: Updated the descriptions of insert_sample_with_metadata setting and JSONEachRow format.

* DOCAPI-5102: Fixed the title case.

* DOCAPI-5102: Clarified the JSONEachRow and insert_sample_with_metadata descriptions.

* DOCAPI-5102: Clarification of the JSONEachRow description.

* DOCAPI-5102: EN review.

* DOCAPI-5102: RU translation.

* DOCAPI-5102: Fixed links.
This commit is contained in:
BayoNet 2019-04-08 19:06:57 +03:00 committed by Ivan Blinkov
parent 87f6889ae6
commit 579ec85b6e
4 changed files with 161 additions and 90 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
docs/en/interfaces/formats.md
View File

@ -307,7 +307,7 @@ See also the `JSONEachRow` format.
## JSONEachRow {#jsoneachrow} ## JSONEachRow {#jsoneachrow}
When using this format, ClickHouse outputs rows as separated, newline delimited JSON objects, but the whole data is not a valid JSON. When using this format, ClickHouse outputs rows as separated, newline-delimited JSON objects, but the data as a whole is not valid JSON.
```json ```json
{"SearchPhrase":"curtain designs","count()":"1064"} {"SearchPhrase":"curtain designs","count()":"1064"}
@ -317,7 +317,7 @@ When using this format, ClickHouse outputs rows as separated, newline delimited
When inserting the data, you should provide a separate JSON object for each row. When inserting the data, you should provide a separate JSON object for each row.
### Inserting the Data ### Inserting Data
``` ```
INSERT INTO UserActivity FORMAT JSONEachRow {"PageViews":5, "UserID":"4324182021466249494", "Duration":146,"Sign":-1} {"UserID":"4324182021466249494","PageViews":6,"Duration":185,"Sign":1} INSERT INTO UserActivity FORMAT JSONEachRow {"PageViews":5, "UserID":"4324182021466249494", "Duration":146,"Sign":-1} {"UserID":"4324182021466249494","PageViews":6,"Duration":185,"Sign":1}
@ -326,17 +326,17 @@ INSERT INTO UserActivity FORMAT JSONEachRow {"PageViews":5, "UserID":"4324182021
ClickHouse allows: ClickHouse allows:
- Any order of key-value pairs in the object. - Any order of key-value pairs in the object.
- The omission of some values. - Omitting some values.
ClickHouse ignores spaces between elements and commas after the objects. You can pass all the objects to a line. You do not have to separate them with line breaks. ClickHouse ignores spaces between elements and commas after the objects. You can pass all the objects in one line. You don't have to separate them with line breaks.
**Processing of omitted values** **Omitted values processing**
ClickHouse substitutes the omitted values with the default values of corresponding [data types](../data_types/index.md). ClickHouse substitutes omitted values with the default values for the corresponding [data types](../data_types/index.md).
In case of the `DEFAULT expr` is specified, ClickHouse uses different substitution rules depending on the [insert_sample_with_metadata](../operations/settings/settings.md#session_settings-insert_sample_with_metadata) setting. If `DEFAULT expr` is specified, ClickHouse uses different substitution rules depending on the [insert_sample_with_metadata](../operations/settings/settings.md#session_settings-insert_sample_with_metadata) setting.
Let's consider the following table: Consider the following table:
``` ```
CREATE TABLE IF NOT EXISTS example_table CREATE TABLE IF NOT EXISTS example_table
@ -346,15 +346,15 @@ CREATE TABLE IF NOT EXISTS example_table
) ENGINE = Memory; ) ENGINE = Memory;
``` ```
- If `insert_sample_with_metadata = 0`, then the default value for `x` and `a` equals `0` (as a default value for `UInt32` data type). - If `insert_sample_with_metadata = 0`, then the default value for `x` and `a` equals `0` (as the default value for the `UInt32` data type).
- If `insert_sample_with_metadata = 1`, then the default value for `x` equals `0`, but the default value of `a` equals `x * 2`. - If `insert_sample_with_metadata = 1`, then the default value for `x` equals `0`, but the default value of `a` equals `x * 2`.
!!! note "Warning" !!! note "Warning"
Use this option carefully, enabling it negatively affects the performance of the ClickHouse server. Use this option carefully. Enabling it negatively affects the performance of the ClickHouse server.
### Selecting the Data ### Selecting Data
Let's consider the `UserActivity` table as an example: Consider the `UserActivity` table as an example:
``` ```
┌──────────────UserID─┬─PageViews─┬─Duration─┬─Sign─┐ ┌──────────────UserID─┬─PageViews─┬─Duration─┬─Sign─┐
@ -373,7 +373,7 @@ The query `SELECT * FROM UserActivity FORMAT JSONEachRow` returns:
Unlike the [JSON](#json) format, there is no substitution of invalid UTF-8 sequences. Values are escaped in the same way as for `JSON`. Unlike the [JSON](#json) format, there is no substitution of invalid UTF-8 sequences. Values are escaped in the same way as for `JSON`.
!!! note "Note" !!! note "Note"
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 into JSON without losing any information. 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.
## Native {#native} ## Native {#native}

16
docs/en/operations/settings/settings.md
View File

@ -139,6 +139,7 @@ If an error occurred while reading rows but the error counter is still less than
If `input_format_allow_errors_ratio` is exceeded, ClickHouse throws an exception. If `input_format_allow_errors_ratio` is exceeded, ClickHouse throws an exception.
## input_format_values_interpret_expressions {#settings-input_format_values_interpret_expressions} ## input_format_values_interpret_expressions {#settings-input_format_values_interpret_expressions}
Turns on the full SQL parser if the fast stream parser can't parse the data. This setting is used only for [Values](../../interfaces/formats.md#data-format-values) format at the data insertion. For more information about syntax parsing, see the [Syntax](../../query_language/syntax.md) section. Turns on the full SQL parser if the fast stream parser can't parse the data. This setting is used only for [Values](../../interfaces/formats.md#data-format-values) format at the data insertion. For more information about syntax parsing, see the [Syntax](../../query_language/syntax.md) section.
@ -186,20 +187,20 @@ Ok.
## insert_sample_with_metadata {#session_settings-insert_sample_with_metadata} ## insert_sample_with_metadata {#session_settings-insert_sample_with_metadata}
Turns on/off the extended data exchange between a ClickHouse client and a ClickHouse server. The setting is applies for `INSERT` queries. Turns on/off the extended data exchange between a ClickHouse client and a ClickHouse server. This setting applies for `INSERT` queries.
When executing the `INSERT` query, ClickHouse client prepares data and sends it to the server for writing. During the preparation of the data, the client gets the table structure from the server. In some cases, the client needs more information than the server sends by default. Turn on the extended data exchange with `insert_sample_with_metadata = 1`. When executing the `INSERT` query, the ClickHouse client prepares data and sends it to the server for writing. The client gets the table structure from the server when preparing the data. In some cases, the client needs more information than the server sends by default. Turn on the extended data exchange with `insert_sample_with_metadata = 1`.
When the extended data exchange is enabled, the server sends the additional metadata along with the table structure. The composition of the metadata depends on the operation. When the extended data exchange is enabled, the server sends the additional metadata along with the table structure. The composition of the metadata depends on the operation.
Operations where you may need the extended data exchange enabled: Operations where you may need the extended data exchange enabled:
- Inserting the data of the [JSONEachRow](../../interfaces/formats.md#jsoneachrow) format. - Inserting data in [JSONEachRow](../../interfaces/formats.md#jsoneachrow) format.
For all other operations ClickHouse doesn't apply the setting. For all other operations, ClickHouse doesn't apply the setting.
!!! note "Note" !!! note "Note"
The functionality of the extended data exchange consumes additional computing resources on the server and can reduce the performance. The extended data exchange functionality consumes additional computing resources on the server and can reduce performance.
**Possible values** **Possible values**
@ -208,6 +209,7 @@ For all other operations ClickHouse doesn't apply the setting.
**Default value:** 0. **Default value:** 0.
## join_default_strictness {#settings-join_default_strictness} ## join_default_strictness {#settings-join_default_strictness}
Sets default strictness for [JOIN clauses](../../query_language/select.md#select-join). Sets default strictness for [JOIN clauses](../../query_language/select.md#select-join).
@ -223,12 +225,12 @@ Sets default strictness for [JOIN clauses](../../query_language/select.md#select
## join_use_nulls {#settings-join_use_nulls} ## join_use_nulls {#settings-join_use_nulls}
Sets the type of [JOIN](../../query_language/select.md) behavior. When merging tables the empty cells may appear. ClickHouse fills them differently based on setting. Sets the type of [JOIN](../../query_language/select.md) behavior. When merging tables, empty cells may appear. ClickHouse fills them differently based on this setting.
**Possible values** **Possible values**
- 0 — The empty cells are filled with the default value of the corresponding field type. - 0 — The empty cells are filled with the default value of the corresponding field type.
- 1 — `JOIN` behaves like in standard SQL. The type of the corresponding field is converted to [Nullable](../../data_types/nullable.md#data_type-nullable), and empty cells are filled with [NULL](../../query_language/syntax.md). - 1 — `JOIN` behaves the same way as in standard SQL. The type of the corresponding field is converted to [Nullable](../../data_types/nullable.md#data_type-nullable), and empty cells are filled with [NULL](../../query_language/syntax.md).
**Default value**: 0. **Default value**: 0.

150
docs/ru/interfaces/formats.md
View File

@ -4,31 +4,31 @@ ClickHouse может принимать (`INSERT`) и отдавать (`SELECT
Поддерживаемые форматы и возможность использовать их в запросах `INSERT` и `SELECT` перечислены в таблице ниже. Поддерживаемые форматы и возможность использовать их в запросах `INSERT` и `SELECT` перечислены в таблице ниже.
Формат | INSERT | SELECT | Формат | INSERT | SELECT |
-------|--------|-------- | ------- | -------- | -------- |
[TabSeparated](#tabseparated) | ✔ | ✔ | | [TabSeparated](#tabseparated) | ✔ | ✔ |
[TabSeparatedRaw](#tabseparatedraw) | ✗ | ✔ | | [TabSeparatedRaw](#tabseparatedraw) | ✗ | ✔ |
[TabSeparatedWithNames](#tabseparatedwithnames) | ✔ | ✔ | | [TabSeparatedWithNames](#tabseparatedwithnames) | ✔ | ✔ |
[TabSeparatedWithNamesAndTypes](#tabseparatedwithnamesandtypes) | ✔ | ✔ | | [TabSeparatedWithNamesAndTypes](#tabseparatedwithnamesandtypes) | ✔ | ✔ |
[CSV](#csv) | ✔ | ✔ | | [CSV](#csv) | ✔ | ✔ |
[CSVWithNames](#csvwithnames) | ✔ | ✔ | | [CSVWithNames](#csvwithnames) | ✔ | ✔ |
[Values](#values) | ✔ | ✔ | | [Values](#data-format-values) | ✔ | ✔ |
[Vertical](#vertical) | ✗ | ✔ | | [Vertical](#vertical) | ✗ | ✔ |
[JSON](#json) | ✗ | ✔ | | [JSON](#json) | ✗ | ✔ |
[JSONCompact](#jsoncompact) | ✗ | ✔ | | [JSONCompact](#jsoncompact) | ✗ | ✔ |
[JSONEachRow](#jsoneachrow) | ✔ | ✔ | | [JSONEachRow](#jsoneachrow) | ✔ | ✔ |
[TSKV](#tskv) | ✔ | ✔ | | [TSKV](#tskv) | ✔ | ✔ |
[Pretty](#pretty) | ✗ | ✔ | | [Pretty](#pretty) | ✗ | ✔ |
[PrettyCompact](#prettycompact) | ✗ | ✔ | | [PrettyCompact](#prettycompact) | ✗ | ✔ |
[PrettyCompactMonoBlock](#prettycompactmonoblock) | ✗ | ✔ | | [PrettyCompactMonoBlock](#prettycompactmonoblock) | ✗ | ✔ |
[PrettyNoEscapes](#prettynoescapes) | ✗ | ✔ | | [PrettyNoEscapes](#prettynoescapes) | ✗ | ✔ |
[PrettySpace](#prettyspace) | ✗ | ✔ | | [PrettySpace](#prettyspace) | ✗ | ✔ |
[Protobuf](#protobuf) | ✔ | ✔ | | [Protobuf](#protobuf) | ✔ | ✔ |
[RowBinary](#rowbinary) | ✔ | ✔ | | [RowBinary](#rowbinary) | ✔ | ✔ |
[Native](#native) | ✔ | ✔ | | [Native](#native) | ✔ | ✔ |
[Null](#null) | ✗ | ✔ | | [Null](#null) | ✗ | ✔ |
[XML](#xml) | ✗ | ✔ | | [XML](#xml) | ✗ | ✔ |
[CapnProto](#capnproto) | ✔ | ✗ | | [CapnProto](#capnproto) | ✔ | ✗ |
## TabSeparated {#tabseparated} ## TabSeparated {#tabseparated}
@ -40,7 +40,7 @@ ClickHouse может принимать (`INSERT`) и отдавать (`SELECT
Формат `TabSeparated` поддерживает вывод тотальных значений (при использовании WITH TOTALS) и экстремальных значений (при настройке extremes выставленной в 1). В этих случаях, после основных данных выводятся тотальные значения, и экстремальные значения. Основной результат, тотальные значения и экстремальные значения, отделяются друг от друга пустой строкой. Пример: Формат `TabSeparated` поддерживает вывод тотальных значений (при использовании WITH TOTALS) и экстремальных значений (при настройке extremes выставленной в 1). В этих случаях, после основных данных выводятся тотальные значения, и экстремальные значения. Основной результат, тотальные значения и экстремальные значения, отделяются друг от друга пустой строкой. Пример:
``` sql ```sql
SELECT EventDate, count() AS c FROM test.hits GROUP BY EventDate WITH TOTALS ORDER BY EventDate FORMAT TabSeparated`` SELECT EventDate, count() AS c FROM test.hits GROUP BY EventDate WITH TOTALS ORDER BY EventDate FORMAT TabSeparated``
``` ```
@ -74,7 +74,7 @@ SELECT EventDate, count() AS c FROM test.hits GROUP BY EventDate WITH TOTALS ORD
В качестве исключения, поддерживается также парсинг даты-с-временем в формате unix timestamp, если он состоит ровно из 10 десятичных цифр. Результат не зависит от часового пояса. Различение форматов YYYY-MM-DD hh:mm:ss и NNNNNNNNNN делается автоматически. В качестве исключения, поддерживается также парсинг даты-с-временем в формате unix timestamp, если он состоит ровно из 10 десятичных цифр. Результат не зависит от часового пояса. Различение форматов YYYY-MM-DD hh:mm:ss и NNNNNNNNNN делается автоматически.
Строки выводятся с экранированием спецсимволов с помощью обратного слеша. При выводе, используются следующие escape-последовательности: `\b`, `\f`, `\r`, `\n`, `\t`, `\0`, `\'`, `\\`. При парсинге, также поддерживаются последовательности `\a`, `\v`, а также `\xHH` (hex escape-последовательности) и любые последовательности вида `\c`, где `c` - любой символ - такие последовательности преобразуется в `c`. Таким образом, при чтении поддерживаются форматы, где перевод строки может быть записан как `\n` и как `\` и перевод строки. Например, строка `Hello world`, где между словами вместо пробела стоит перевод строки, может быть считана в любом из следующих вариантов: Строки выводятся с экранированием спецсимволов с помощью обратного слеша. При выводе, используются следующие escape-последовательности: `\b`, `\f`, `\r`, `\n`, `\t`, `\0`, `\'`, `\\`. Парсер также поддерживает последовательности `\a`, `\v`, и `\xHH` (последовательности hex escape) и любые последовательности вида `\c`, где `c` — любой символ (такие последовательности преобразуются в `c`). Таким образом, при чтении поддерживаются форматы, где перевод строки может быть записан как `\n` и как `\` и перевод строки. Например, строка `Hello world`, где между словами вместо пробела стоит перевод строки, может быть считана в любом из следующих вариантов:
``` ```
Hello\nworld Hello\nworld
@ -91,7 +91,7 @@ world
Массивы форматируются в виде списка значений через запятую в квадратных скобках. Элементы массива - числа форматируются как обычно, а даты, даты-с-временем и строки - в одинарных кавычках с такими же правилами экранирования, как указано выше. Массивы форматируются в виде списка значений через запятую в квадратных скобках. Элементы массива - числа форматируются как обычно, а даты, даты-с-временем и строки - в одинарных кавычках с такими же правилами экранирования, как указано выше.
[NULL](../query_language/syntax.md) форматируется в виде `\N`. [NULL](../query_language/syntax.md) форматируется как `\N`.
## TabSeparatedRaw {#tabseparatedraw} ## TabSeparatedRaw {#tabseparatedraw}
@ -103,7 +103,7 @@ world
## TabSeparatedWithNames {#tabseparatedwithnames} ## TabSeparatedWithNames {#tabseparatedwithnames}
Отличается от формата `TabSeparated` тем, что в первой строке пишутся имена столбцов. Отличается от формата `TabSeparated` тем, что в первой строке пишутся имена столбцов.
При парсинге, первая строка полностью игнорируется: вы не можете использовать имена столбцов, чтобы указать их порядок расположения, или чтобы проверить их корректность. При парсинге, первая строка полностью игнорируется. Вы не можете использовать имена столбцов, чтобы указать их порядок расположения, или чтобы проверить их корректность.
(Поддержка обработки заголовка при парсинге может быть добавлена в будущем.) (Поддержка обработки заголовка при парсинге может быть добавлена в будущем.)
Этот формат также доступен под именем `TSVWithNames`. Этот формат также доступен под именем `TSVWithNames`.
@ -132,24 +132,25 @@ SearchPhrase=дизайн штор count()=1064
SearchPhrase=баку count()=1000 SearchPhrase=баку count()=1000
``` ```
[NULL](../query_language/syntax.md) форматируется в виде `\N`. [NULL](../query_language/syntax.md) форматируется как `\N`.
``` sql ```sql
SELECT * FROM t_null FORMAT TSKV SELECT * FROM t_null FORMAT TSKV
``` ```
``` ```
x=1 y=\N x=1 y=\N
``` ```
При большом количестве маленьких столбцов, этот формат существенно неэффективен, и обычно нет причин его использовать. Он реализован, так как используется в некоторых отделах Яндекса. При большом количестве маленьких столбцов, этот формат существенно неэффективен, и обычно нет причин его использовать. Он реализован, так как используется в некоторых отделах Яндекса.
Поддерживается как вывод, так и парсинг данных в этом формате. При парсинге, поддерживается расположение значений разных столбцов в произвольном порядке. Допустимо отсутствие некоторых значений - тогда они воспринимаются как равные значениям по умолчанию. При этом, в качестве значений по умолчанию используются нули, пустые строки и не поддерживаются сложные значения по умолчанию, которые могут быть заданы в таблице. Поддерживается как вывод, так и парсинг данных в этом формате. При парсинге, поддерживается расположение значений разных столбцов в произвольном порядке. Допустимо отсутствие некоторых значений - тогда они воспринимаются как равные значениям по умолчанию. В этом случае в качестве значений по умолчанию используются нули и пустые строки. Сложные значения, которые могут быть заданы в таблице не поддерживаются как значения по умолчанию.
При парсинге, в качестве дополнительного поля, может присутствовать `tskv` без знака равенства и без значения. Это поле игнорируется. При парсинге, в качестве дополнительного поля, может присутствовать `tskv` без знака равенства и без значения. Это поле игнорируется.
## CSV {#csv} ## CSV {#csv}
Формат comma separated values ([RFC](https://tools.ietf.org/html/rfc4180)). Формат Comma Separated Values ([RFC](https://tools.ietf.org/html/rfc4180)).
При форматировании, строки выводятся в двойных кавычках. Двойная кавычка внутри строки выводится как две двойные кавычки подряд. Других правил экранирования нет. Даты и даты-с-временем выводятся в двойных кавычках. Числа выводятся без кавычек. Значения разделяются символом-разделителем, по умолчанию — `,`. Символ-разделитель определяется настройкой [format_csv_delimiter](../operations/settings/settings.md#settings-format_csv_delimiter). Строки разделяются unix переводом строки (LF). Массивы сериализуются в CSV следующим образом: сначала массив сериализуется в строку, как в формате TabSeparated, а затем полученная строка выводится в CSV в двойных кавычках. Кортежи в формате CSV сериализуются, как отдельные столбцы (то есть, теряется их вложенность в кортеж). При форматировании, строки выводятся в двойных кавычках. Двойная кавычка внутри строки выводится как две двойные кавычки подряд. Других правил экранирования нет. Даты и даты-с-временем выводятся в двойных кавычках. Числа выводятся без кавычек. Значения разделяются символом-разделителем, по умолчанию — `,`. Символ-разделитель определяется настройкой [format_csv_delimiter](../operations/settings/settings.md#settings-format_csv_delimiter). Строки разделяются unix переводом строки (LF). Массивы сериализуются в CSV следующим образом: сначала массив сериализуется в строку, как в формате TabSeparated, а затем полученная строка выводится в CSV в двойных кавычках. Кортежи в формате CSV сериализуются, как отдельные столбцы (то есть, теряется их вложенность в кортеж).
@ -159,7 +160,7 @@ clickhouse-client --format_csv_delimiter="|" --query="INSERT INTO test.csv FORMA
*По умолчанию — `,`. См. настройку [format_csv_delimiter](../operations/settings/settings.md#settings-format_csv_delimiter) для дополнительной информации. *По умолчанию — `,`. См. настройку [format_csv_delimiter](../operations/settings/settings.md#settings-format_csv_delimiter) для дополнительной информации.
При парсинге, все значения могут парситься как в кавычках, так и без кавычек. Поддерживаются как двойные, так и одинарные кавычки. В том числе, строки могут быть расположены без кавычек - тогда они парсятся до символа-разделителя или перевода строки (CR или LF). В нарушение RFC, в случае парсинга строк не в кавычках, начальные и конечные пробелы и табы игнорируются. В качестве перевода строки, поддерживаются как Unix (LF), так и Windows (CR LF) и Mac OS Classic (LF CR) варианты. При парсинге, все значения могут парситься как в кавычках, так и без кавычек. Поддерживаются как двойные, так и одинарные кавычки. Строки также могут быть без кавычек. В этом случае они парсятся до символа-разделителя или перевода строки (CR или LF). В нарушение RFC, в случае парсинга строк не в кавычках, начальные и конечные пробелы и табы игнорируются. В качестве перевода строки, поддерживаются как Unix (LF), так и Windows (CR LF) и Mac OS Classic (LF CR) варианты.
`NULL` форматируется в виде `\N`. `NULL` форматируется в виде `\N`.
@ -173,7 +174,7 @@ clickhouse-client --format_csv_delimiter="|" --query="INSERT INTO test.csv FORMA
Выводит данные в формате JSON. Кроме таблицы с данными, также выводятся имена и типы столбцов, и некоторая дополнительная информация - общее количество выведенных строк, а также количество строк, которое могло бы быть выведено, если бы не было LIMIT-а. Пример: Выводит данные в формате JSON. Кроме таблицы с данными, также выводятся имена и типы столбцов, и некоторая дополнительная информация - общее количество выведенных строк, а также количество строк, которое могло бы быть выведено, если бы не было LIMIT-а. Пример:
``` sql ```sql
SELECT SearchPhrase, count() AS c FROM test.hits GROUP BY SearchPhrase WITH TOTALS ORDER BY c DESC LIMIT 5 FORMAT JSON SELECT SearchPhrase, count() AS c FROM test.hits GROUP BY SearchPhrase WITH TOTALS ORDER BY c DESC LIMIT 5 FORMAT JSON
``` ```
@ -241,7 +242,7 @@ SELECT SearchPhrase, count() AS c FROM test.hits GROUP BY SearchPhrase WITH TOTA
} }
``` ```
JSON совместим с JavaScript. Для этого, дополнительно экранируются некоторые символы: символ прямого слеша `/` экранируется в виде `\/`; альтернативные переводы строк `U+2028`, `U+2029`, на которых ломаются некоторые браузеры, экранируются в виде `\uXXXX`-последовательностей. Экранируются ASCII control characters: backspace, form feed, line feed, carriage return, horizontal tab в виде `\b`, `\f`, `\n`, `\r`, `\t` соответственно, а также остальные байты из диапазона 00-1F с помощью `\uXXXX`-последовательностей. Невалидные UTF-8 последовательности заменяются на replacement character <20> и, таким образом, выводимый текст будет состоять из валидных UTF-8 последовательностей. Числа типа UInt64 и Int64, для совместимости с JavaScript, по умолчанию выводятся в двойных кавычках, чтобы они выводились без кавычек можно установить конфигурационный параметр output_format_json_quote_64bit_integers равным 0. JSON совместим с JavaScript. Для этого, дополнительно экранируются некоторые символы: символ прямого слеша `/` экранируется в виде `\/`; альтернативные переводы строк `U+2028`, `U+2029`, на которых ломаются некоторые браузеры, экранируются в виде `\uXXXX`-последовательностей. Экранируются ASCII control characters: backspace, form feed, line feed, carriage return, horizontal tab в виде `\b`, `\f`, `\n`, `\r`, `\t` соответственно, а также остальные байты из диапазона 00-1F с помощью `\uXXXX`-последовательностей. Невалидные UTF-8 последовательности заменяются на replacement character <20> и, таким образом, выводимый текст будет состоять из валидных UTF-8 последовательностей. Числа типа UInt64 и Int64, для совместимости с JavaScript, по умолчанию выводятся в двойных кавычках. Чтобы они выводились без кавычек, можно установить конфигурационный параметр [output_format_json_quote_64bit_integers](../operations/settings/settings.md#session_settings-output_format_json_quote_64bit_integers) равным 0.
`rows` - общее количество выведенных строчек. `rows` - общее количество выведенных строчек.
@ -256,7 +257,7 @@ JSON совместим с JavaScript. Для этого, дополнитель
ClickHouse поддерживает [NULL](../query_language/syntax.md), который при выводе JSON будет отображен как `null`. ClickHouse поддерживает [NULL](../query_language/syntax.md), который при выводе JSON будет отображен как `null`.
Смотрите также формат JSONEachRow. Смотрите также формат [JSONEachRow](#jsoneachrow) .
## JSONCompact {#jsoncompact} ## JSONCompact {#jsoncompact}
@ -306,24 +307,73 @@ ClickHouse поддерживает [NULL](../query_language/syntax.md), кот
## JSONEachRow {#jsoneachrow} ## JSONEachRow {#jsoneachrow}
Выводит данные в виде отдельных JSON объектов для каждой строки (newline delimited JSON). При использовании этого формата, ClickHouse выводит каждую запись как объект JSON (каждый объект отдельной строкой), при этом данные в целом — невалидный JSON.
```json ```json
{"SearchPhrase":"","count()":"8267016"}
{"SearchPhrase":"интерьер ванной комнаты","count()":"2166"}
{"SearchPhrase":"яндекс","count()":"1655"}
{"SearchPhrase":"весна 2014 мода","count()":"1549"}
{"SearchPhrase":"фриформ фото","count()":"1480"}
{"SearchPhrase":"анджелина джоли","count()":"1245"}
{"SearchPhrase":"омск","count()":"1112"}
{"SearchPhrase":"фото собак разных пород","count()":"1091"}
{"SearchPhrase":"дизайн штор","count()":"1064"} {"SearchPhrase":"дизайн штор","count()":"1064"}
{"SearchPhrase":"баку","count()":"1000"} {"SearchPhrase":"баку","count()":"1000"}
{"SearchPhrase":"","count":"8267016"}
``` ```
В отличие от формата JSON, нет замены невалидных UTF-8 последовательностей. В строках может выводиться произвольный набор байт. Это сделано для того, чтобы данные форматировались без потери информации. Экранирование значений осуществляется аналогично формату JSON. При вставке данных необходимо каждую запись передавать как отдельный объект JSON.
При парсинге, поддерживается расположение значений разных столбцов в произвольном порядке. Допустимо отсутствие некоторых значений - тогда они воспринимаются как равные значениям по умолчанию. При этом, в качестве значений по умолчанию используются нули, и пустые строки. Сложные значения которые могут быть заданы в таблице, не поддерживаются по умолчанию, но их можно включить с помощью опции `insert_sample_with_metadata = 1`. Пропускаются пробельные символы между элементами. После объектов может быть расположена запятая, которая игнорируется. Объекты не обязательно должны быть разделены переводами строк. ### Вставка данных
```
INSERT INTO UserActivity FORMAT JSONEachRow {"PageViews":5, "UserID":"4324182021466249494", "Duration":146,"Sign":-1} {"UserID":"4324182021466249494","PageViews":6,"Duration":185,"Sign":1}
```
ClickHouse допускает:
- Любой порядок пар ключ-значение в объекте.
- Пропуск отдельных значений.
ClickHouse игнорирует пробелы между элементами и запятые после объектов. Вы можете передать все объекты одной строкой. Вам не нужно разделять их переносами строк.
**Обработка пропущенных значений**
ClickHouse заменяет опущенные значения значениями по умолчанию для соответствующих [data types](../data_types/index.md).
Если указано `DEFAULT expr`, то ClickHouse использует различные правила подстановки в зависимости от настройки [insert_sample_with_metadata](../operations/settings/settings.md#session_settings-insert_sample_with_metadata).
Рассмотрим следующую таблицу:
```
CREATE TABLE IF NOT EXISTS example_table
(
x UInt32,
a DEFAULT x * 2
) ENGINE = Memory;
```
- Если `insert_sample_with_metadata = 0`, то значение по умолчанию для `x` и `a` равняется `0` (поскольку это значение по умолчанию для типа данных `UInt32`.)
- Если `insert_sample_with_metadata = 1`, то значение по умолчанию для `x` равно `0`, а значение по умолчанию `a` равно `x * 2`.
!!! note "Предупреждение"
Используйте эту опцию осторожно. Её включение негативно влияет на производительность сервера ClickHouse.
### Выборка данных
Рассмотрим в качестве примера таблицу `UserActivity`:
```
┌──────────────UserID─┬─PageViews─┬─Duration─┬─Sign─┐
│ 4324182021466249494 │ 5 │ 146 │ -1 │
│ 4324182021466249494 │ 6 │ 185 │ 1 │
└─────────────────────┴───────────┴──────────┴──────┘
```
Запрос `SELECT * FROM UserActivity FORMAT JSONEachRow` возвращает:
```
{"UserID":"4324182021466249494","PageViews":5,"Duration":146,"Sign":-1}
{"UserID":"4324182021466249494","PageViews":6,"Duration":185,"Sign":1}
```
В отличие от формата [JSON](#json), для `JSONEachRow` ClickHouse не заменяет невалидные UTF-8 последовательности. Значения экранируются так же, как и для формата `JSON`.
!!! Примечание " Примечание"
В строках может выводиться произвольный набор байт. Используйте формат `JSONEachRow`, если вы уверены, что данные в таблице могут быть представлены в формате JSON без потери информации.
## Native {#native} ## Native {#native}
@ -359,7 +409,7 @@ SELECT * FROM t_null
SELECT 'String with \'quotes\' and \t character' AS Escaping_test SELECT 'String with \'quotes\' and \t character' AS Escaping_test
``` ```
``` ```
┌─Escaping_test────────────────────────┐ ┌─Escaping_test────────────────────────┐
│ String with 'quotes' and character │ │ String with 'quotes' and character │
└──────────────────────────────────────┘ └──────────────────────────────────────┘
@ -445,7 +495,7 @@ Array представлены как длина в формате varint (unsig
Для поддержки [NULL](../query_language/syntax.md#null-literal) перед каждым значением типа [Nullable](../data_types/nullable.md Для поддержки [NULL](../query_language/syntax.md#null-literal) перед каждым значением типа [Nullable](../data_types/nullable.md
## Values ## Values {#data-format-values}
Выводит каждую строку в скобках. Строки разделены запятыми. После последней строки запятой нет. Значения внутри скобок также разделены запятыми. Числа выводятся в десятичном виде без кавычек. Массивы выводятся в квадратных скобках. Строки, даты, даты-с-временем выводятся в кавычках. Правила экранирования и особенности парсинга аналогичны формату [TabSeparated](#tabseparated). При форматировании, лишние пробелы не ставятся, а при парсинге - допустимы и пропускаются (за исключением пробелов внутри значений типа массив, которые недопустимы). [NULL](../query_language/syntax.md) представляется как `NULL`. Выводит каждую строку в скобках. Строки разделены запятыми. После последней строки запятой нет. Значения внутри скобок также разделены запятыми. Числа выводятся в десятичном виде без кавычек. Массивы выводятся в квадратных скобках. Строки, даты, даты-с-временем выводятся в кавычках. Правила экранирования и особенности парсинга аналогичны формату [TabSeparated](#tabseparated). При форматировании, лишние пробелы не ставятся, а при парсинге - допустимы и пропускаются (за исключением пробелов внутри значений типа массив, которые недопустимы). [NULL](../query_language/syntax.md) представляется как `NULL`.

59
docs/ru/operations/settings/settings.md
View File

@ -15,10 +15,10 @@ ClickHouse применяет настройку в тех случаях, ко
Возможные значения: Возможные значения:
- `deny` — значение по умолчанию. Запрещает использование таких подзапросов (При попытке использование вернет исключение "Double-distributed IN/JOIN subqueries is denied"); - `deny` — значение по умолчанию. Запрещает использование таких подзапросов (При попытке использование вернет исключение "Double-distributed IN/JOIN subqueries is denied");
- `local` - заменяет базу данных и таблицу в подзапросе на локальные для конечного сервера (шарда), оставив обычный `IN` / `JOIN.` - `local` — заменяет базу данных и таблицу в подзапросе на локальные для конечного сервера (шарда), оставив обычный `IN` / `JOIN.`
- `global` - заменяет запрос `IN` / `JOIN` на `GLOBAL IN` / `GLOBAL JOIN.` - `global` — заменяет запрос `IN` / `JOIN` на `GLOBAL IN` / `GLOBAL JOIN.`
- `allow` - разрешает использование таких подзапросов. - `allow` — разрешает использование таких подзапросов.
## enable_optimize_predicate_expression ## enable_optimize_predicate_expression
@ -101,6 +101,30 @@ ClickHouse применяет настройку в тех случаях, ко
В случае превышения `input_format_allow_errors_ratio` ClickHouse генерирует исключение. В случае превышения `input_format_allow_errors_ratio` ClickHouse генерирует исключение.
## insert_sample_with_metadata {#session_settings-insert_sample_with_metadata}
Включает/выключает расширенный обмен данными между клиентом ClickHouse и сервером ClickHouse. Параметр применяется для запросов `INSERT`.
При выполнении запроса`INSERT`, клиент ClickHouse подготавливает данные и отправляет их на сервер для записи. При подготовке данных клиент получает структуру таблицы от сервера. В некоторых случаях клиенту требуется больше информации, чем сервер отправляет по умолчанию. Включите расширенный обмен данными с помощью настройки `insert_sample_with_metadata = 1`.
Если расширенный обмен данными включен, сервер отправляет дополнительные метаданные вместе со структурой таблицы. Состав метаданных зависит от операции.
Операции, для которых может потребоваться включить расширенный обмен данными:
- Вставка данных в формате [JSONEachRow](../../interfaces/formats.md#jsoneachrow).
Для всех остальных операций ClickHouse не применяет этот параметр.
!!! Примечание " Примечание"
Функциональность расширенного обмена данными потребляет дополнительные вычислительные ресурсы на сервере и может снизить производительность.
**Возможные значения**
- 0 — функциональность выключена.
- 1 — функциональность включена.
**Значение по умолчанию**: 0.
## join_default_strictness {#settings-join_default_strictness} ## join_default_strictness {#settings-join_default_strictness}
Устанавливает строгость по умолчанию для [JOIN](../../query_language/select.md#select-join). Устанавливает строгость по умолчанию для [JOIN](../../query_language/select.md#select-join).
@ -108,7 +132,7 @@ ClickHouse применяет настройку в тех случаях, ко
**Возможные значения** **Возможные значения**
- `ALL` — если в правой таблице несколько совпадающих строк, данные умножаются на количество этих строк. Это нормальное поведение `JOIN` как в стандартном SQL. - `ALL` — если в правой таблице несколько совпадающих строк, данные умножаются на количество этих строк. Это нормальное поведение `JOIN` как в стандартном SQL.
- `ANY` — если в правой таблице несколько соответствующих строк, то соединяется только первая найденная. Если в "правой" таблице есть не более одной подходящей строки, то результаты `ANY` и `ALL` совпадают. - `ANY` — если в правой таблице несколько соответствующих строк, то соединяется только первая найденная. Если в "правой" таблице есть не более одной подходящей строки, то результаты `ANY` и `ALL` совпадают.
- `Пустая строка` — если `ALL` или `ANY` не указаны в запросе, то ClickHouse генерирует исключение. - `Пустая строка` — если `ALL` или `ANY` не указаны в запросе, то ClickHouse генерирует исключение.
**Значение по умолчанию**: `ALL` **Значение по умолчанию**: `ALL`
@ -120,7 +144,7 @@ ClickHouse применяет настройку в тех случаях, ко
**Возможные значения** **Возможные значения**
- 0 — пустые ячейки заполняются значением по умолчанию соответствующего типа поля. - 0 — пустые ячейки заполняются значением по умолчанию соответствующего типа поля.
- 1 — `JOIN` ведет себя как в стандартном SQL. Тип соответствующего поля преобразуется в [Nullable](../../data_types/nullable.md#data_type-nullable), а пустые ячейки заполняются значениями [NULL](../../query_language/syntax.md). - 1 — `JOIN` ведет себя как в стандартном SQL. Тип соответствующего поля преобразуется в [Nullable](../../data_types/nullable.md#data_type-nullable), а пустые ячейки заполняются значениями [NULL](../../query_language/syntax.md).
**Значение по умолчанию**: 0. **Значение по умолчанию**: 0.
@ -140,7 +164,7 @@ ClickHouse применяет настройку в тех случаях, ко
## merge_tree_uniform_read_distribution {#setting-merge_tree_uniform_read_distribution} ## merge_tree_uniform_read_distribution {#setting-merge_tree_uniform_read_distribution}
При чтении из таблиц [MergeTree*](../table_engines/mergetree.md) ClickHouse использует несколько потоков. Этот параметр включает/выключает равномерное распределение заданий по рабочим потокам. Алгоритм равномерного распределения стремится сделать время выполнения всех потоков примерно равным для одного запроса `SELECT`. При чтении из таблиц [MergeTree*](../table_engines/mergetree.md) ClickHouse использует несколько потоков. Этот параметр включает/выключает равномерное распределение заданий по рабочим потокам. Алгоритм равномерного распределения стремится сделать время выполнения всех потоков примерно равным для одного запроса `SELECT`.
**Возможные значения** **Возможные значения**
@ -181,7 +205,7 @@ ClickHouse применяет настройку в тех случаях, ко
## merge_tree_max_rows_to_use_cache {#setting-merge_tree_max_rows_to_use_cache} ## merge_tree_max_rows_to_use_cache {#setting-merge_tree_max_rows_to_use_cache}
Если требуется прочитать более, чем `merge_tree_max_rows_to_use_cache` строк в одном запросе, ClickHouse не используют кэш несжатых блоков. Настройка сервера [uncompressed_cache_size](../server_settings/settings.md#server-settings-uncompressed_cache_size) определяет размер кэша несжатых блоков. Если требуется прочитать более, чем `merge_tree_max_rows_to_use_cache` строк в одном запросе, ClickHouse не используют кэш несжатых блоков. Настройка сервера [uncompressed_cache_size](../server_settings/settings.md#server-settings-uncompressed_cache_size) определяет размер кэша несжатых блоков.
**Возможные значения** **Возможные значения**
@ -228,7 +252,7 @@ ClickHouse применяет настройку в тех случаях, ко
Этот параметр относится к потокам, которые выполняют параллельно одни стадии конвейера выполнения запроса. Этот параметр относится к потокам, которые выполняют параллельно одни стадии конвейера выполнения запроса.
Например, при чтении из таблицы, если есть возможность вычислять выражения с функциями, фильтровать с помощью WHERE и предварительно агрегировать для GROUP BY параллельно, используя хотя бы количество потоков max_threads, то используются max_threads. Например, при чтении из таблицы, если есть возможность вычислять выражения с функциями, фильтровать с помощью WHERE и предварительно агрегировать для GROUP BY параллельно, используя хотя бы количество потоков max_threads, то используются max_threads.
По умолчанию - 2. Значение по умолчанию: 2.
Если на сервере обычно исполняется менее одного запроса SELECT одновременно, то выставите этот параметр в значение чуть меньше количества реальных процессорных ядер. Если на сервере обычно исполняется менее одного запроса SELECT одновременно, то выставите этот параметр в значение чуть меньше количества реальных процессорных ядер.
@ -256,7 +280,7 @@ ClickHouse применяет настройку в тех случаях, ко
Как правило, не имеет смысла менять эту настройку. Как правило, не имеет смысла менять эту настройку.
## max_query_size ## max_query_size {#settings-max_query_size}
Максимальный кусок запроса, который будет считан в оперативку для разбора парсером языка SQL. Максимальный кусок запроса, который будет считан в оперативку для разбора парсером языка SQL.
Запрос INSERT также содержит данные для INSERT-а, которые обрабатываются отдельным, потоковым парсером (расходующим O(1) оперативки), и не учитываются в этом ограничении. Запрос INSERT также содержит данные для INSERT-а, которые обрабатываются отдельным, потоковым парсером (расходующим O(1) оперативки), и не учитываются в этом ограничении.
@ -285,7 +309,7 @@ ClickHouse применяет настройку в тех случаях, ко
Максимальное количество одновременных соединений с удалёнными серверами при распределённой обработке одного запроса к одной таблице типа Distributed. Рекомендуется выставлять не меньше, чем количество серверов в кластере. Максимальное количество одновременных соединений с удалёнными серверами при распределённой обработке одного запроса к одной таблице типа Distributed. Рекомендуется выставлять не меньше, чем количество серверов в кластере.
По умолчанию - 1024. Значение по умолчанию: 1024.
Следующие параметры имеют значение только на момент создания таблицы типа Distributed (и при запуске сервера), поэтому их не имеет смысла менять в рантайме. Следующие параметры имеют значение только на момент создания таблицы типа Distributed (и при запуске сервера), поэтому их не имеет смысла менять в рантайме.
@ -293,7 +317,7 @@ ClickHouse применяет настройку в тех случаях, ко
Максимальное количество одновременных соединений с удалёнными серверами при распределённой обработке всех запросов к одной таблице типа Distributed. Рекомендуется выставлять не меньше, чем количество серверов в кластере. Максимальное количество одновременных соединений с удалёнными серверами при распределённой обработке всех запросов к одной таблице типа Distributed. Рекомендуется выставлять не меньше, чем количество серверов в кластере.
По умолчанию - 1024. Значение по умолчанию: 1024.
## connect_timeout_with_failover_ms ## connect_timeout_with_failover_ms
@ -316,7 +340,7 @@ ClickHouse применяет настройку в тех случаях, ко
## use_uncompressed_cache {#setting-use_uncompressed_cache} ## use_uncompressed_cache {#setting-use_uncompressed_cache}
Использовать ли кэш разжатых блоков. Принимает 0 или 1. По умолчанию - 0 (выключено). Использовать ли кэш разжатых блоков. Принимает 0 или 1. По умолчанию - 0 (выключено).
Использование кэша несжатых блоков (только для таблиц семейства MergeTree) может существенно сократить задержку и увеличить пропускную способность при работе с большим количеством коротких запросов. Включите эту настройку для пользователей, от которых идут частые короткие запросы. Также обратите внимание на конфигурационный параметр [uncompressed_cache_size](../server_settings/settings.md#server-settings-uncompressed_cache_size) (настраивается только в конфигурационном файле) - размер кэша разжатых блоков. По умолчанию - 8 GiB. Кэш разжатых блоков заполняется по мере надобности, а наиболее невостребованные данные автоматически удаляются. Использование кэша несжатых блоков (только для таблиц семейства MergeTree) может существенно сократить задержку и увеличить пропускную способность при работе с большим количеством коротких запросов. Включите эту настройку для пользователей, от которых идут частые короткие запросы. Также обратите внимание на конфигурационный параметр[uncompressed_cache_size](../server_settings/settings.md#server-settings-uncompressed_cache_size) (настраивается только в конфигурационном файле) - размер кэша разжатых блоков. По умолчанию - 8 GiB. Кэш разжатых блоков заполняется по мере надобности, а наиболее невостребованные данные автоматически удаляются.
Для запросов, читающих хоть немного приличный объём данных (миллион строк и больше), кэш разжатых блоков автоматически выключается, чтобы оставить место для действительно мелких запросов. Поэтому, можно держать настройку `use_uncompressed_cache` всегда выставленной в 1. Для запросов, читающих хоть немного приличный объём данных (миллион строк и больше), кэш разжатых блоков автоматически выключается, чтобы оставить место для действительно мелких запросов. Поэтому, можно держать настройку `use_uncompressed_cache` всегда выставленной в 1.
@ -337,7 +361,7 @@ ClickHouse применяет настройку в тех случаях, ко
## stream_flush_interval_ms ## stream_flush_interval_ms
Работает для таблиц со стриммингом в случае тайм-аута, или когда поток генерирует [max_insert_block_size](#settings-max_insert_block_size) строк. Работает для таблиц со стриммингом в случае тайм-аута, или когда поток генерирует [max_insert_block_size](#settings-max_insert_block_size) строк.
Значение по умолчанию - 7500. Значение по умолчанию - 7500.
@ -404,11 +428,7 @@ ClickHouse применяет настройку в тех случаях, ко
Если значение равно true, то при выполнении INSERT входные данные из столбцов с неизвестными именами будут пропущены. В противном случае эта ситуация создаст исключение. Если значение равно true, то при выполнении INSERT входные данные из столбцов с неизвестными именами будут пропущены. В противном случае эта ситуация создаст исключение.
Работает для форматов JSONEachRow и TSKV. Работает для форматов JSONEachRow и TSKV.
## insert_sample_with_metadata ## output_format_json_quote_64bit_integers {#session_settings-output_format_json_quote_64bit_integers}
Для запросов INSERT. Указывает, что серверу необходимо отправлять клиенту метаданные о значениях столбцов по умолчанию, которые будут использоваться для вычисления выражений по умолчанию. По умолчанию отключено.
## output_format_json_quote_64bit_integers
Если значение истинно, то при использовании JSON\* форматов UInt64 и Int64 числа выводятся в кавычках (из соображений совместимости с большинством реализаций JavaScript), иначе - без кавычек. Если значение истинно, то при использовании JSON\* форматов UInt64 и Int64 числа выводятся в кавычках (из соображений совместимости с большинством реализаций JavaScript), иначе - без кавычек.
@ -470,4 +490,3 @@ ClickHouse применяет настройку в тех случаях, ко
- [insert_quorum_timeout](#settings-insert_quorum_timeout) - [insert_quorum_timeout](#settings-insert_quorum_timeout)
[Оригинальная статья](https://clickhouse.yandex/docs/ru/operations/settings/settings/) <!--hide--> [Оригинальная статья](https://clickhouse.yandex/docs/ru/operations/settings/settings/) <!--hide-->