From 333b56ccfa4282b33f532ab40d014f7890ed001c Mon Sep 17 00:00:00 2001 From: BayoNet Date: Tue, 26 Mar 2019 11:05:41 +0300 Subject: [PATCH] DOCAPI-4177: HTTP compression settings a described. (#4801) --- docs/en/interfaces/http.md | 23 ++++++++++++---- docs/en/operations/settings/settings.md | 35 +++++++++++++++++++++++++ 2 files changed, 53 insertions(+), 5 deletions(-) diff --git a/docs/en/interfaces/http.md b/docs/en/interfaces/http.md index 8dece39249f..a72a2e4a06e 100644 --- a/docs/en/interfaces/http.md +++ b/docs/en/interfaces/http.md @@ -128,16 +128,29 @@ 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). +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. -If you specified 'compress=1' in the URL, the server will compress the data it sends you. -If you specified 'decompress=1' in the URL, the server will decompress 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. 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 setting `enable_http_compression`. +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`. +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. +Examples of sending the data with compression: + +```bash +#Sending the data to the server: +curl -vsS "http://localhost:8123/?enable_http_compression=1" -d 'SELECT number FROM system.numbers LIMIT 10' -H 'Accept-Encoding: gzip' + +#Sending the data to the client: +echo "SELECT 1" | gzip -c | curl -sS --data-binary @- -H 'Content-Encoding: gzip' 'http://localhost:8123/' +``` + +!!! 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. + You can use the 'database' URL parameter to specify the default database. ```bash diff --git a/docs/en/operations/settings/settings.md b/docs/en/operations/settings/settings.md index 3e9ecef9d17..00c5d476771 100644 --- a/docs/en/operations/settings/settings.md +++ b/docs/en/operations/settings/settings.md @@ -79,6 +79,41 @@ Enable or disable fsync 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. + +For more information, read the [HTTP interface description](../../interfaces/http.md). + +Possible values: + +- 0 — The functionality is disabled. +- 1 — The functionality is 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). + +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`). + +For more information, read the [HTTP interface description](../../interfaces/http.md). + +Possible values: + +- 0 — The functionality is disabled. +- 1 — The functionality is enabled. + +Default value: 0. + ## input_format_allow_errors_num Sets the maximum number of acceptable errors when reading from text formats (CSV, TSV, etc.).