Documenting numbers table function, VerticalRaw format, HTTP sessions, HTTP compression.

docs/en/formats/verticalraw.md

+# VerticalRaw
+
+Differs from `TabSeparated` format in that the rows are written without escaping.
+This format is only appropriate for outputting a query result, but not for parsing (retrieving data to insert in a table).
+
+Samples:
+```
+:) SHOW CREATE TABLE geonames FORMAT VerticalRaw;
+Row 1:
+──────
+statement: CREATE TABLE default.geonames ( geonameid UInt32,  name String,  asciiname String, alternatenames String,  latitude Float32,  longitude Float32,  feature_class String,  feature_code String,  country_code String,  cc2 String,  admin1_code String,  admin2_code String,  admin3_code String,  admin4_code String,  population Int64,  elevation String,  dem String,  timezone String,  modification_date Date, date Date DEFAULT CAST('2017-12-08' AS Date)) ENGINE = MergeTree(date, geonameid, 8192)
+
+:) SELECT 'string with \'quotes\' and \t with some special \n characters' AS test FORMAT VerticalRaw;
+Row 1:
+──────
+test: string with 'quotes' and   with some special
+ characters
+
+-- the same in Vertical format:
+:) SELECT 'string with \'quotes\' and \t with some special \n characters' AS test FORMAT Vertical;
+Row 1:
+──────
+test: string with \'quotes\' and \t with some special \n characters
+```

docs/en/interfaces/http_interface.md

@@ -130,11 +130,15 @@ POST 'http://localhost:8123/?query=DROP TABLE t'
 
 For successful requests that don't return a data table, an empty response body is returned.
 
-You can use compression when transmitting data. The compressed data has a non-standard format, and you will need to use the special compressor program to work with it (sudo apt-get install compressor-metrika-yandex).
+You can use compression when transmitting data.
 
+For using ClickHouse internal compression format, and you will need to use the special compressor program to work with it (sudo apt-get install compressor-metrika-yandex).
 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.
 
+Also standard gzip-based HTTP compression can be used. To send gzip compressed POST data just add `Content-Encoding: gzip` to request headers, and gzip POST body.
+To get response compressed, you need to add `Accept-Encoding: gzip` to request headers, and turn on ClickHouse setting called `enable_http_compression`.
+
 You can use this to reduce network traffic when transmitting a large amount of data, or for creating dumps that are immediately compressed.
 
 You can use the 'database' URL parameter to specify the default database.
@@ -190,7 +194,11 @@ $ echo 'SELECT number FROM system.numbers LIMIT 10' | curl 'http://localhost:812
 
 For information about other parameters, see the section "SET".
 
-In contrast to the native interface, the HTTP interface does not support the concept of sessions or session settings, does not allow aborting a query (to be exact, it allows this in only a few cases),  and does not show the progress of query processing. Parsing and data formatting are performed on the server side, and using the network might be ineffective.
+You can use ClickHouse sessions in the HTTP protocol. To do this, you need to specify the `session_id` GET parameter in HTTP request. You can use any alphanumeric string as a session_id. By default session will be timed out after 60 seconds of inactivity. You can change that by setting `default_session_timeout` in server config file, or by adding GET parameter `session_timeout`. You can also check the status of the session by using GET parameter `session_check=1`. When using sessions you can't run 2 queries with the same session_id simultaneously.
+
+You can get the progress of query execution in X-ClickHouse-Progress headers, by enabling setting send_progress_in_http_headers.
+
+Running query are not aborted automatically after closing HTTP connection. Parsing and data formatting are performed on the server side, and using the network might be ineffective.
 The optional 'query_id' parameter can be passed as the query ID (any string). For more information, see the section "Settings, replace_running_query".
 
 The optional 'quota_key' parameter can be passed as the quota key (any string). For more information, see the section "Quotas".
@@ -212,4 +220,3 @@ curl -sS 'http://localhost:8123/?max_result_bytes=4000000&buffer_size=3000000&wa
 ```
 
 Use buffering to avoid situations where a query processing error occurred after the response code and HTTP headers were sent to the client. In this situation, an error message is written at the end of the response body, and on the client side, the error can only be detected at the parsing stage.
-

docs/en/table_functions/numbers.md

+# numbers
+
+`numbers(N)` - returns the table with one column named `number` (UInt64 type), containing integer numbers from 0 to N-1.
+
+`numbers(N)` (like a table `system.numbers`) can be used in tests or for sequences generation.
+
+Two following queries are equal:
+```sql
+SELECT * FROM numbers(10);
+SELECT * FROM system.numbers LIMIT 10;
+```
+
+Samples:
+```sql
+-- generation of sequence of dates from 2010-01-01 to 2010-12-31
+select toDate('2010-01-01') + number as d FROM numbers(365);
+```

docs/mkdocs_en.yml

@@ -122,6 +122,7 @@ pages:
   - 'Introduction': 'table_functions/index.md'
   - 'remote': 'table_functions/remote.md'
   - 'merge': 'table_functions/merge.md'
+  - 'numbers': 'table_functions/numbers.md'
 
 - 'Formats':
   - 'Introduction': 'formats/index.md'
@@ -133,6 +134,7 @@ pages:
   - 'CSVWithNames': 'formats/csvwithnames.md'
   - 'Values': 'formats/values.md'
   - 'Vertical': 'formats/vertical.md'
+  - 'VerticalRaw': 'formats/verticalraw.md'
   - 'JSON': 'formats/json.md'
   - 'JSONCompact': 'formats/jsoncompact.md'
   - 'JSONEachRow': 'formats/jsoneachrow.md'

docs/mkdocs_ru.yml

@@ -124,6 +124,7 @@ pages:
   - 'Введение': 'table_functions/index.md'
   - 'remote': 'table_functions/remote.md'
   - 'merge': 'table_functions/merge.md'
+  - 'numbers': 'table_functions/numbers.md'
 
 - 'Форматы':
   - 'Введение': 'formats/index.md'
@@ -135,6 +136,7 @@ pages:
   - 'CSVWithNames': 'formats/csvwithnames.md'
   - 'Values': 'formats/values.md'
   - 'Vertical': 'formats/vertical.md'
+  - 'VerticalRaw': 'formats/verticalraw.md'
   - 'JSON': 'formats/json.md'
   - 'JSONCompact': 'formats/jsoncompact.md'
   - 'JSONEachRow': 'formats/jsoneachrow.md'

docs/ru/formats/verticalraw.md

+# VerticalRaw
+
+Отличается от формата `Vertical` тем, что строки выводятся без экранирования.
+Этот формат подходит только для вывода результата выполнения запроса, но не для парсинга (приёма данных для вставки в таблицу).
+
+Примеры:
+```
+:) SHOW CREATE TABLE geonames FORMAT VerticalRaw;
+Row 1:
+──────
+statement: CREATE TABLE default.geonames ( geonameid UInt32,  name String,  asciiname String, alternatenames String,  latitude Float32,  longitude Float32,  feature_class String,  feature_code String,  country_code String,  cc2 String,  admin1_code String,  admin2_code String,  admin3_code String,  admin4_code String,  population Int64,  elevation String,  dem String,  timezone String,  modification_date Date, date Date DEFAULT CAST('2017-12-08' AS Date)) ENGINE = MergeTree(date, geonameid, 8192)
+
+:) SELECT 'string with \'quotes\' and \t with some special \n characters' AS test FORMAT VerticalRaw;
+Row 1:
+──────
+test: string with 'quotes' and   with some special
+ characters
+```
+
+Для сравнения - формат Vertical:
+```
+:) SELECT 'string with \'quotes\' and \t with some special \n characters' AS test FORMAT Vertical;
+Row 1:
+──────
+test: string with \'quotes\' and \t with some special \n characters
+```

docs/ru/interfaces/http_interface.md

@@ -132,11 +132,14 @@ POST 'http://localhost:8123/?query=DROP TABLE t'
 
 Для запросов, которые не возвращают таблицу с данными, в случае успеха, выдаётся пустое тело ответа.
 
-Вы можете использовать сжатие при передаче данных. Формат сжатых данных нестандартный, и вам придётся использовать для работы с ним специальную программу compressor (sudo apt-get install compressor-metrika-yandex).
+Вы можете использовать внутренний формат сжатия Clickhouse при передаче данных. Формат сжатых данных нестандартный, и вам придётся использовать для работы с ним специальную программу compressor (sudo apt-get install compressor-metrika-yandex).
 
 Если вы указали в URL compress=1, то сервер будет сжимать отправляемые вам данные.
 Если вы указали в URL decompress=1, то сервер будет разжимать те данные, которые вы передаёте ему POST-ом.
 
+Также имеется возможность использования стандартного сжатия HTTP, на основе gzip. Чтобы отправить POST-запрос, сжатый с помощью gzip, добавьте к запросу заголовок `Content-Encoding: gzip`.
+Чтобы ClickHouse сжимал ответ на запрос с помощью gzip, необходимо добавить `Accept-Encoding: gzip` к заголовкам запроса, и включить настройку ClickHouse  `enable_http_compression`.
+
 Это может быть использовано для уменьшения трафика по сети при передаче большого количества данных, а также для создания сразу сжатых дампов.
 
 В параметре URL database может быть указана БД по умолчанию.
@@ -193,7 +196,11 @@ $ echo 'SELECT number FROM system.numbers LIMIT 10' | curl 'http://localhost:812
 
 Об остальных параметрах смотри раздел "SET".
 
-В отличие от родного интерфейса, HTTP интерфейс не поддерживает понятие сессии и настройки в пределах сессии, не позволяет (вернее, позволяет лишь в некоторых случаях) прервать выполнение запроса, не показывает прогресс выполнения запроса. Парсинг и форматирование данных производится на стороне сервера и использование сети может быть неэффективным.
+В HTTP-протоколе можно использовать ClickHouse-сессии, для этого необходимо добавить к запросу GET-пaраметр `session_id`. В качестве идентификатора сессии можно использовать произвольную строку. По умолчанию через 60 секунд бездействия сессия будет прервана. Можно изменить этот таймаут, изменяя настройку `default_session_timeout` в конфигурации сервера, или добавив к запросу GET параметр `session_timeout`. Статус сессии можно проверить с помощью параметра `session_check=1`. В рамках одной сессии одновременно может испольняться только один запрос.
+
+Имеется возможность получать информацию о прогрессе выполнения запроса в залоголвках X-ClickHouse-Progress, для этого нужно включить настройку send_progress_in_http_headers.
+
+Запущенные запросы не останавливаются автоматически при разрыве HTTP соединения. Парсинг и форматирование данных производится на стороне сервера и использование сети может быть неэффективным.
 Может быть передан необязательный параметр query_id - идентификатор запроса, произвольная строка. Подробнее смотрите раздел "Настройки, replace_running_query".
 
 Может быть передан необязательный параметр quota_key - ключ квоты, произвольная строка. Подробнее смотрите раздел "Квоты".

docs/ru/table_functions/numbers.md

+# numbers
+
+`numbers(N)` - возвращает таблицу с единственным столбцом number (тип UInt64), содержащую натуральные числа от 0 до N-1.
+
+Так же как и таблица `system.numbers` может использоваться для тестов и генерации последовательных значений.
+
+Следующие 2 запроса эквивалентны:
+```sql
+SELECT * FROM numbers(10);
+SELECT * FROM system.numbers LIMIT 10;
+```
+Примеры:
+```sql
+-- генарация последовательности всех дат от 2010-01-01 до 2010-12-31
+select toDate('2010-01-01') + number as d FROM numbers(365);
+```