From f12fff6e1212cf7fc937b95cff6065f78b6faca7 Mon Sep 17 00:00:00 2001 From: BayoNet Date: Mon, 15 Apr 2019 14:47:45 +0300 Subject: [PATCH] DOCAPI-4177: HTTP compression settings. EN review. RU translation. (#4996) --- docs/en/interfaces/http.md | 14 +++--- docs/en/operations/settings/settings.md | 43 ++++++++++-------- docs/ru/interfaces/http.md | 33 +++++++++----- docs/ru/operations/settings/settings.md | 59 ++++++++++++++++++++----- 4 files changed, 103 insertions(+), 46 deletions(-) diff --git a/docs/en/interfaces/http.md b/docs/en/interfaces/http.md index a72a2e4a06..e1d1708a04 100644 --- a/docs/en/interfaces/http.md +++ b/docs/en/interfaces/http.md @@ -128,12 +128,12 @@ echo 'DROP TABLE t' | curl 'http://localhost:8123/' --data-binary @- For successful requests that don't return a data table, an empty response body is returned. -You can use the internal ClickHouse compression format when transmitting data. The compressed data has a non-standard format, and you will need to use the special `clickhouse-compressor` program to work with it (it is installed with the `clickhouse-client` package). To increase the efficiency of the data insertion, you may disable the server-side checksum verification with the [http_native_compression_disable_checksumming_on_decompress](../operations/settings/settings.md#settings-http_native_compression_disable_checksumming_on_decompress) setting. +You can use the internal ClickHouse compression format when transmitting data. The compressed data has a non-standard format, and you will need to use the special `clickhouse-compressor` program to work with it (it is installed with the `clickhouse-client` package). To increase the efficiency of data insertion, you can disable server-side checksum verification by using the [http_native_compression_disable_checksumming_on_decompress](../operations/settings/settings.md#settings-http_native_compression_disable_checksumming_on_decompress) setting. -If you specified `compress = 1` in the URL, the server compresses the data it sends you. -If you specified `decompress = 1` in the URL, the server decompresses the same data that you pass in the `POST` method. +If you specified `compress=1` in the URL, the server compresses the data it sends you. +If you specified `decompress=1` in the URL, the server decompresses the same data that you pass in the `POST` method. -It is also possible to use the standard `gzip`-based [HTTP compression](https://en.wikipedia.org/wiki/HTTP_compression). To send a `POST` request compressed using `gzip`, append the request header `Content-Encoding: gzip`. +It is also possible to use standard `gzip`-based [HTTP compression](https://en.wikipedia.org/wiki/HTTP_compression). To send a `POST` request compressed using `gzip`, append the request header `Content-Encoding: gzip`. In order for ClickHouse to compress the response using `gzip`, you must append `Accept-Encoding: gzip` to the request headers, and enable the ClickHouse [enable_http_compression](../operations/settings/settings.md#settings-enable_http_compression) setting. You can configure the compression level of the data with the [http_zlib_compression_level](#settings-http_zlib_compression_level) setting. You can use this to reduce network traffic when transmitting a large amount of data, or for creating dumps that are immediately compressed. @@ -149,7 +149,7 @@ echo "SELECT 1" | gzip -c | curl -sS --data-binary @- -H 'Content-Encoding: gzip ``` !!! note "Note" - Some HTTP clients can decompress data (`gzip` and `deflate`) from the server by default and you may get the decompressed data even if you use the compression settings correctly. + Some HTTP clients might decompress data from the server by default (with `gzip` and `deflate`) and you might get decompressed data even if you use the compression settings correctly. You can use the 'database' URL parameter to specify the default database. @@ -183,10 +183,10 @@ echo 'SELECT 1' | curl 'http://user:password@localhost:8123/' -d @- echo 'SELECT 1' | curl 'http://localhost:8123/?user=user&password=password' -d @- ``` -If the user name is not indicated, the username 'default' is used. If the password is not indicated, an empty password is used. +If the user name is not specified, the `default` name is used. If the password is not specified, the empty password is used. You can also use the URL parameters to specify any settings for processing a single query, or entire profiles of settings. Example:http://localhost:8123/?profile=web&max_rows_to_read=1000000000&query=SELECT+1 -For more information, see the section "Settings". +For more information, see the [Settings][../operations/settings/index.md] section. ```bash $ echo 'SELECT number FROM system.numbers LIMIT 10' | curl 'http://localhost:8123/?' --data-binary @- diff --git a/docs/en/operations/settings/settings.md b/docs/en/operations/settings/settings.md index 7b69d448b3..5abb9f83c6 100644 --- a/docs/en/operations/settings/settings.md +++ b/docs/en/operations/settings/settings.md @@ -14,7 +14,7 @@ Restrictions: - If the subquery concerns a distributed table containing more than one shard, - Not used for a table-valued [remote](../../query_language/table_functions/remote.md) function. -The possible values are: +Possible values: - `deny` — Default value. Prohibits using these types of subqueries (returns the "Double-distributed in/JOIN subqueries is denied" exception). - `local` — Replaces the database and table in the subquery with local ones for the destination server (shard), leaving the normal `IN`/`JOIN.` @@ -29,8 +29,8 @@ Predicate pushdown may significantly reduce network traffic for distributed quer Possible values: -- 0 — Functionality is turned off. -- 1 — Functionality is turned on. +- 0 — Disabled. +- 1 — Enabled. Default value: 0. @@ -75,42 +75,42 @@ If `force_primary_key=1`, ClickHouse checks to see if the query has a primary ke ## fsync_metadata -Enable or disable fsync when writing .sql files. Enabled by default. +Enables or disables [fsync](http://pubs.opengroup.org/onlinepubs/9699919799/functions/fsync.html) when writing `.sql` files. Enabled by default. It makes sense to disable it if the server has millions of tiny table chunks that are constantly being created and destroyed. ## enable_http_compression {#settings-enable_http_compression} -Enables/disables compression of the data in the response to an HTTP request. +Enables or disables data compression in the response to an HTTP request. For more information, read the [HTTP interface description](../../interfaces/http.md). Possible values: -- 0 — The functionality is disabled. -- 1 — The functionality is enabled. +- 0 — Disabled. +- 1 — Enabled. Default value: 0. ## http_zlib_compression_level {#settings-http_zlib_compression_level} -Sets the level of the compression of the data in the response to an HTTP request if [enable_http_compression = 1](#settings-enable_http_compression). +Sets the level of data compression in the response to an HTTP request if [enable_http_compression = 1](#settings-enable_http_compression). -Possible values: numbers from 1 to 9. +Possible values: Numbers from 1 to 9. Default value: 3. ## http_native_compression_disable_checksumming_on_decompress {#settings-http_native_compression_disable_checksumming_on_decompress} -Enables/disables the verification of the checksum when uncompressing the HTTP POST data from the client. Used only for ClickHouse native format of compression (neither `gzip` nor `deflate`). +Enables or disables checksum verification when decompressing the HTTP POST data from the client. Used only for ClickHouse native compression format (not used with `gzip` or `deflate`). For more information, read the [HTTP interface description](../../interfaces/http.md). Possible values: -- 0 — The functionality is disabled. -- 1 — The functionality is enabled. +- 0 — Disabled. +- 1 — Enabled. Default value: 0. @@ -142,15 +142,15 @@ If `input_format_allow_errors_ratio` is exceeded, ClickHouse throws an exception ## 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 the [Values](../../interfaces/formats.md#data-format-values) format during data insertion. For more information about syntax parsing, see the [Syntax](../../query_language/syntax.md) section. +Enables or disables the full SQL parser if the fast stream parser can't parse the data. This setting is used only for the [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. Possible values: -- 0 — Functionality is turned off. +- 0 — Disabled. In this case, you must provide formatted data. See the [Formats](../../interfaces/formats.md) section. -- 1 — Functionality is turned on. +- 1 — Enabled. In this case, you can use an SQL expression as a value, but data insertion is much slower this way. If you insert only formatted data, then ClickHouse behaves as if the setting value is 0. @@ -204,8 +204,8 @@ For all other operations, ClickHouse doesn't apply the setting. **Possible values** -- 0 — Functionality is disabled. -- 1 — Functionality is enabled. +- 0 — Disabled. +- 1 — Enabled. **Default value:** 0. @@ -580,15 +580,20 @@ Default value: 60 seconds. ## select_sequential_consistency {#settings-select_sequential_consistency} -Enables/disables sequential consistency for `SELECT` queries: +Enables or disables sequential consistency for `SELECT` queries: + +Possible values: - 0 — Disabled. - 1 — Enabled. + Default value: 0. +**Usage** + When sequential consistency is enabled, ClickHouse allows the client to execute the `SELECT` query only for those replicas that contain data from all previous `INSERT` queries executed with `insert_quorum`. If the client refers to a partial replica, ClickHouse will generate an exception. The SELECT query will not include data that has not yet been written to the quorum of replicas. -See also the following parameters: +**See Also** - [insert_quorum](#settings-insert_quorum) - [insert_quorum_timeout](#settings-insert_quorum_timeout) diff --git a/docs/ru/interfaces/http.md b/docs/ru/interfaces/http.md index effd512ea3..a78f12c709 100644 --- a/docs/ru/interfaces/http.md +++ b/docs/ru/interfaces/http.md @@ -35,7 +35,7 @@ Date: Fri, 16 Nov 2012 19:21:50 GMT ``` Как видно, curl немного неудобен тем, что надо URL-эскейпить пробелы. -wget сам всё эскейпит, но его не рекомендуется использовать, так как он плохо работает по HTTP 1.1 при использовании keep-alive и Transfer-Encoding: chunked. +Хотя wget сам всё эскейпит, но его не рекомендуется использовать, так как он плохо работает по HTTP 1.1 при использовании keep-alive и Transfer-Encoding: chunked. ```bash $ echo 'SELECT 1' | curl 'http://localhost:8123/' --data-binary @- @@ -129,16 +129,29 @@ echo 'DROP TABLE t' | curl 'http://localhost:8123/' --data-binary @- Для запросов, которые не возвращают таблицу с данными, в случае успеха, выдаётся пустое тело ответа. -Вы можете использовать внутренний формат сжатия Clickhouse при передаче данных. Формат сжатых данных нестандартный, и вам придётся использовать для работы с ним специальную программу clickhouse-compressor (устанавливается вместе с пакетом clickhouse-client). +Вы можете использовать внутренний формат сжатия Clickhouse при передаче данных. Формат сжатых данных нестандартный, и вам придётся использовать для работы с ним специальную программу `clickhouse-compressor` (устанавливается вместе с пакетом `clickhouse-client`). Для повышения эффективности вставки данных можно отключить проверку контрольной суммы на стороне сервера с помощью настройки[http_native_compression_disable_checksumming_on_decompress](../operations/settings/settings.md#settings-http_native_compression_disable_checksumming_on_decompress). -Если вы указали в URL compress=1, то сервер будет сжимать отправляемые вам данные. -Если вы указали в URL decompress=1, то сервер будет разжимать те данные, которые вы передаёте ему POST-ом. +Если вы указали `compress=1` в URL, то сервер сжимает данные, которые он отправляет. +Если вы указали `decompress=1` в URL, сервер распаковывает те данные, которые вы передаёте методом `POST`. -Также имеется возможность использования стандартного сжатия HTTP, на основе gzip. Чтобы отправить POST-запрос, сжатый с помощью gzip, добавьте к запросу заголовок `Content-Encoding: gzip`. -Чтобы ClickHouse сжимал ответ на запрос с помощью gzip, необходимо добавить `Accept-Encoding: gzip` к заголовкам запроса, и включить настройку ClickHouse `enable_http_compression`. +Также можно использовать стандартное [HTTP сжатие](https://en.wikipedia.org/wiki/HTTP_compression) с помощью `gzip`. Чтобы отправить запрос `POST`, сжатый с помощью `gzip`, добавьте к запросу заголовок `Content-Encoding: gzip`. +Чтобы ClickHouse сжимал ответ на запрос с помощью `gzip`, необходимо добавить `Accept-Encoding: gzip` к заголовкам запроса, и включить настройку ClickHouse [enable_http_compression](../operations/settings/settings.md#settings-enable_http_compression). Вы можете настроить уровень сжатия данных с помощью настройки [http_zlib_compression_level](#settings-http_zlib_compression_level). Это может быть использовано для уменьшения трафика по сети при передаче большого количества данных, а также для создания сразу сжатых дампов. +Примеры отправки данных со сжатием: + +```bash +#Отправка данных на сервер: +curl -vsS "http://localhost:8123/?enable_http_compression=1" -d 'SELECT number FROM system.numbers LIMIT 10' -H 'Accept-Encoding: gzip' + +#Отправка данных клиенту: +echo "SELECT 1" | gzip -c | curl -sS --data-binary @- -H 'Content-Encoding: gzip' 'http://localhost:8123/' +``` + +!!! note "Примечание" + Некоторые HTTP-клиенты могут по умолчанию распаковывать данные (`gzip` и `deflate`) с сервера в фоновом режиме и вы можете получить распакованные данные, даже если правильно используете настройки сжатия. + В параметре URL database может быть указана БД по умолчанию. ```bash @@ -171,11 +184,11 @@ echo 'SELECT 1' | curl 'http://user:password@localhost:8123/' -d @- echo 'SELECT 1' | curl 'http://localhost:8123/?user=user&password=password' -d @- ``` -Если имя пользователя не указано, то используется имя пользователя default. Если пароль не указан, то используется пустой пароль. +Если имя пользователя не указано, то используется `default`. Если пароль не указан, то используется пустой пароль. Также в параметрах URL вы можете указать любые настройки, которые будут использованы для обработки одного запроса, или целые профили настроек. Пример: http://localhost:8123/?profile=web&max_rows_to_read=1000000000&query=SELECT+1 -Подробнее см. раздел "Настройки". +Подробнее смотрите в разделе [Настройки](../operations/settings/index.md). ```bash $ echo 'SELECT number FROM system.numbers LIMIT 10' | curl 'http://localhost:8123/?' --data-binary @- @@ -193,9 +206,9 @@ $ echo 'SELECT number FROM system.numbers LIMIT 10' | curl 'http://localhost:812 Об остальных параметрах смотри раздел "SET". -В HTTP-протоколе можно использовать ClickHouse-сессии, для этого необходимо добавить к запросу GET-пaраметр `session_id`. В качестве идентификатора сессии можно использовать произвольную строку. По умолчанию через 60 секунд бездействия сессия будет прервана. Можно изменить этот таймаут, изменяя настройку `default_session_timeout` в конфигурации сервера, или добавив к запросу GET параметр `session_timeout`. Статус сессии можно проверить с помощью параметра `session_check=1`. В рамках одной сессии одновременно может испольняться только один запрос. +Аналогично можно использовать ClickHouse-сессии в HTTP-протоколе. Для этого необходимо добавить к запросу GET параметр `session_id`. В качестве идентификатора сессии можно использовать произвольную строку. По умолчанию через 60 секунд бездействия сессия будет прервана. Можно изменить этот таймаут, изменяя настройку `default_session_timeout` в конфигурации сервера, или добавив к запросу GET параметр `session_timeout`. Статус сессии можно проверить с помощью параметра `session_check=1`. В рамках одной сессии одновременно может исполняться только один запрос. -Имеется возможность получать информацию о прогрессе выполнения запроса в залоголвках X-ClickHouse-Progress, для этого нужно включить настройку send_progress_in_http_headers. +Имеется возможность получать информацию о прогрессе выполнения запроса в залоголвках X-ClickHouse-Progress. Для этого нужно включить настройку send_progress_in_http_headers. Запущенные запросы не останавливаются автоматически при разрыве HTTP соединения. Парсинг и форматирование данных производится на стороне сервера и использование сети может быть неэффективным. Может быть передан необязательный параметр query_id - идентификатор запроса, произвольная строка. Подробнее смотрите раздел "Настройки, replace_running_query". diff --git a/docs/ru/operations/settings/settings.md b/docs/ru/operations/settings/settings.md index d2de1d54e5..b8cdb7a541 100644 --- a/docs/ru/operations/settings/settings.md +++ b/docs/ru/operations/settings/settings.md @@ -28,8 +28,8 @@ ClickHouse применяет настройку в тех случаях, ко Возможные значения: -- 0 — функциональность выключена. -- 1 — функциональность включена. +- 0 — выключена. +- 1 — включена. Значение по умолчанию: 0. @@ -72,10 +72,44 @@ ClickHouse применяет настройку в тех случаях, ко ## fsync_metadata -Включить или отключить fsync при записи .sql файлов. По умолчанию включено. +Включает или отключает [fsync](http://pubs.opengroup.org/onlinepubs/9699919799/functions/fsync.html) при записи `.sql` файлов. По умолчанию включено. Имеет смысл выключать, если на сервере миллионы мелких таблиц-чанков, которые постоянно создаются и уничтожаются. +## enable_http_compression {#settings-enable_http_compression} + +Включает или отключает сжатие данных в ответе на HTTP-запрос. + +Для получения дополнительной информации, читайте [Описание интерфейса HTTP](../../interfaces/http.md). + +Возможные значения: + +- 0 — выключена. +- 1 — включена. + +Значение по умолчанию: 0. + +## http_zlib_compression_level {#settings-http_zlib_compression_level} + +Задает уровень сжатия данных в ответе на HTTP-запрос, если [enable_http_compression = 1](#settings-enable_http_compression). + +Возможные значения: числа от 1 до 9. + +Значение по умолчанию: 3. + +## http_native_compression_disable_checksumming_on_decompress {#settings-http_native_compression_disable_checksumming_on_decompress} + +Включает или отключает проверку контрольной суммы при распаковке данных HTTP POST от клиента. Используется только для собственного (`Navite`) формата сжатия ClickHouse (ни `gzip`, ни `deflate`). + +Для получения дополнительной информации, читайте [Описание интерфейса HTTP](../../interfaces/http.md). + +Возможные значения: + +- 0 — выключена. +- 1 — включена. + +Значение по умолчанию: 0. + ## input_format_allow_errors_num Устанавливает максимальное количество допустимых ошибок при чтении из текстовых форматов (CSV, TSV и т.п.). @@ -103,15 +137,15 @@ ClickHouse применяет настройку в тех случаях, ко ## input_format_values_interpret_expressions {#settings-input_format_values_interpret_expressions} -Включает парсер SQL, если потоковый парсер не может проанализировать данные. Этот параметр используется только для формата [Values](../../interfaces/formats.md#data-format-values) при вводе данных. Дополнительные сведения о парсерах читайте в разделе [Синтаксис](../../query_language/syntax.md). +Включает или отключает парсер SQL, если потоковый парсер не может проанализировать данные. Этот параметр используется только для формата [Values](../../interfaces/formats.md#data-format-values) при вводе данных. Дополнительные сведения о парсерах читайте в разделе [Синтаксис](../../query_language/syntax.md). Возможные значения: -- 0 — функциональность выключена. +- 0 — выключена. В этом случае необходимо вставлять форматированные данные. Смотрите раздел [Форматы](../../interfaces/formats.md). -- 1 — функциональность включена. +- 1 — включена. В этом случае вы можете использовать выражение SQL в качестве значения, но вставка данных намного медленнее. Если вы вставляете только форматированные данные, ClickHouse ведет себя так, как будто значение параметра равно 0. @@ -164,8 +198,8 @@ Ok. **Возможные значения** -- 0 — функциональность выключена. -- 1 — функциональность включена. +- 0 — выключена. +- 1 — включена. **Значение по умолчанию**: 0. @@ -534,15 +568,20 @@ ClickHouse использует этот параметр при чтении д ## select_sequential_consistency {#settings-select_sequential_consistency} -Включение/выключение последовательной консистентности для запросов `SELECT`: +Включает или выключает последовательную консистентность для запросов `SELECT`. + +Возможные значения: - 0 — выключена. - 1 — включена. + Значение по умолчанию: 0. +**Использование** + Когда последовательная консистентность включена, то ClickHouse позволит клиенту выполнить запрос `SELECT` только к тем репликам, которые содержат данные всех предыдущих запросов `INSERT`, выполненных с `insert_quorum`. Если клиент обратится к неполной реплике, то ClickHouse сгенерирует исключение. В запросе SELECT не будут участвовать данные, которые ещё не были записаны на кворум реплик. -См. также параметры: +**Смотрите также** - [insert_quorum](#settings-insert_quorum) - [insert_quorum_timeout](#settings-insert_quorum_timeout) -- GitLab