Merge remote-tracking branch 'origin' into adaptive_index_granularity

2024-11-22 23:52:03 +00:00 · 2019-04-09 19:19:29 +03:00 · 2019-04-09 19:19:29 +03:00 · 91e362d874
commit 91e362d874
parent a53b002973 cc8186b77c
25 changed files with 488 additions and 262 deletions
--- a/dbms/tests/clickhouse-test
+++ b/dbms/tests/clickhouse-test
@ -17,19 +17,11 @@ from subprocess import CalledProcessError
 from datetime import datetime
 from time import sleep
 from errno import ESRCH
-from termcolor import colored
+import termcolor
 from random import random
 import commands


-OP_SQUARE_BRACKET = colored("[", attrs=['bold'])
-CL_SQUARE_BRACKET = colored("]", attrs=['bold'])
-
-MSG_FAIL = OP_SQUARE_BRACKET + colored(" FAIL ", "red", attrs=['bold']) + CL_SQUARE_BRACKET
-MSG_UNKNOWN = OP_SQUARE_BRACKET + colored(" UNKNOWN ", "yellow", attrs=['bold']) + CL_SQUARE_BRACKET
-MSG_OK = OP_SQUARE_BRACKET + colored(" OK ", "green", attrs=['bold']) + CL_SQUARE_BRACKET
-MSG_SKIPPED = OP_SQUARE_BRACKET + colored(" SKIPPED ", "cyan", attrs=['bold']) + CL_SQUARE_BRACKET
-
 MESSAGES_TO_RETRY = [
    "DB::Exception: ZooKeeper session has been expired",
    "Coordination::Exception: Connection loss",
@ -99,6 +91,20 @@ def main(args):

    SERVER_DIED = False

+    def colored(text, color=None, on_color=None, attrs=None):
+           if sys.stdout.isatty() or args.force_color:
+               return termcolor.colored(text, color, on_color, attrs)
+           else:
+               return text
+
+    OP_SQUARE_BRACKET = colored("[", attrs=['bold'])
+    CL_SQUARE_BRACKET = colored("]", attrs=['bold'])
+
+    MSG_FAIL = OP_SQUARE_BRACKET + colored(" FAIL ", "red", attrs=['bold']) + CL_SQUARE_BRACKET
+    MSG_UNKNOWN = OP_SQUARE_BRACKET + colored(" UNKNOWN ", "yellow", attrs=['bold']) + CL_SQUARE_BRACKET
+    MSG_OK = OP_SQUARE_BRACKET + colored(" OK ", "green", attrs=['bold']) + CL_SQUARE_BRACKET
+    MSG_SKIPPED = OP_SQUARE_BRACKET + colored(" SKIPPED ", "cyan", attrs=['bold']) + CL_SQUARE_BRACKET
+
    def is_data_present():
        clickhouse_proc = Popen(shlex.split(args.client), stdin=PIPE, stdout=PIPE, stderr=PIPE)
        (stdout, stderr) = clickhouse_proc.communicate("EXISTS TABLE test.hits")
@ -433,6 +439,7 @@ if __name__ == '__main__':
    parser.add_argument('--order', default='desc', help='Run order (asc, desc, random)')
    parser.add_argument('--testname', action='store_true', default=None, dest='testname', help='Make query with test name before test run')
    parser.add_argument('--hung-check', action='store_true', default=False)
+    parser.add_argument('--force-color', action='store_true', default=False)

    parser.add_argument('--no-stateless', action='store_true', help='Disable all stateless tests')
    parser.add_argument('--skip', nargs='+', help="Skip these tests")
--- a/dbms/tests/clickhouse-test-server
+++ b/dbms/tests/clickhouse-test-server
@ -131,7 +131,7 @@ else
    TEST_DICT=${TEST_DICT=1}
    CLICKHOUSE_CLIENT_QUERY="${CLICKHOUSE_CLIENT} --config ${CLICKHOUSE_CONFIG_CLIENT} --port $CLICKHOUSE_PORT_TCP -m -n -q"
    $CLICKHOUSE_CLIENT_QUERY 'SELECT * from system.build_options; SELECT * FROM system.clusters;'
-    CLICKHOUSE_TEST="env ${TEST_DIR}clickhouse-test --binary ${BIN_DIR}${CLICKHOUSE_BINARY_NAME} --configclient $CLICKHOUSE_CONFIG_CLIENT --configserver $CLICKHOUSE_CONFIG --tmp $DATA_DIR/tmp --queries $QUERIES_DIR $TEST_OPT0 $TEST_OPT"
+    CLICKHOUSE_TEST="env ${TEST_DIR}clickhouse-test --force-color --binary ${BIN_DIR}${CLICKHOUSE_BINARY_NAME} --configclient $CLICKHOUSE_CONFIG_CLIENT --configserver $CLICKHOUSE_CONFIG --tmp $DATA_DIR/tmp --queries $QUERIES_DIR $TEST_OPT0 $TEST_OPT"
    CLICKHOUSE_PERFORMANCE_TEST="${BIN_DIR}clickhouse-performance-test --port $CLICKHOUSE_PORT_TCP --recursive $CUR_DIR/performance --skip-tags=long"
    if [ "${TEST_RUN_STRESS}" ]; then
        # Running test in parallel will fail some results (tests can create/fill/drop same tables)
--- a/docs/en/interfaces/formats.md
+++ b/docs/en/interfaces/formats.md
@ -307,7 +307,7 @@ See also the `JSONEachRow` format.

 ## 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
 {"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.

-### 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}
@ -326,17 +326,17 @@ INSERT INTO UserActivity FORMAT JSONEachRow {"PageViews":5, "UserID":"4324182021
 ClickHouse allows:

 - 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
@ -346,15 +346,15 @@ CREATE TABLE IF NOT EXISTS example_table
 ) 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`.

 !!! 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─┐
@ -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`.

 !!! 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}

--- a/docs/en/operations/settings/settings.md
+++ b/docs/en/operations/settings/settings.md
@ -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.

+
 ## 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.
@ -186,20 +187,20 @@ Ok.

 ## 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.

 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"
-    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**

@ -208,6 +209,7 @@ For all other operations ClickHouse doesn't apply the setting.

 **Default value:** 0.

+
 ## join_default_strictness {#settings-join_default_strictness}

 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}

-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**

 - 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.

@ -300,15 +302,14 @@ Any positive integer.

 ## min_bytes_to_use_direct_io {#settings-min_bytes_to_use_direct_io}

-The minimum data volume to be read from storage required for using of the direct I/O access to the storage disk.
+The minimum data volume required for using direct I/O access to the storage disk.

-ClickHouse uses this setting when selecting the data from tables. If summary storage volume of all the data to be read exceeds `min_bytes_to_use_direct_io` bytes, then ClickHouse reads the data from the storage disk with `O_DIRECT` option.
+ClickHouse uses this setting when reading data from tables. If the total storage volume of all the data to be read exceeds `min_bytes_to_use_direct_io` bytes, then ClickHouse reads the data from the storage disk with the `O_DIRECT` option.

 **Possible values**

-Positive integer.
-
-0 — The direct I/O is disabled.
+- 0 — Direct I/O is disabled.
+- Positive integer.

 **Default value**: 0.

--- a/docs/en/operations/table_engines/join.md
+++ b/docs/en/operations/table_engines/join.md
@ -7,7 +7,7 @@ A prepared data structure for JOIN that is always located in RAM.
 Join(ANY|ALL, LEFT|INNER, k1[, k2, ...])
 ```

-Engine parameters: `ANY|ALL` – strictness; `LEFT|INNER` – type.
+Engine parameters: `ANY|ALL` – strictness; `LEFT|INNER` – type. For more information, see the [JOIN Clause](../../query_language/select.md#select-join) section.
 These parameters are set without quotes and must match the JOIN that the table will be used for. k1, k2, ... are the key columns from the USING clause that the join will be made on.

 The table can't be used for GLOBAL JOINs.
--- a/docs/en/operations/table_engines/mergetree.md
+++ b/docs/en/operations/table_engines/mergetree.md
@ -60,18 +60,16 @@ For a description of request parameters, see [request description](../../query_l

 - `PRIMARY KEY` - The primary key if it [differs from the sorting key](mergetree.md).

-    By default the primary key is the same as the sorting key (which is specified by the `ORDER BY` clause).
-    Thus in most cases it is unnecessary to specify a separate `PRIMARY KEY` clause.
+    By default the primary key is the same as the sorting key (which is specified by the `ORDER BY` clause). Thus in most cases it is unnecessary to specify a separate `PRIMARY KEY` clause.

 - `SAMPLE BY` — An expression for sampling.

-    If a sampling expression is used, the primary key must contain it. Example:  
-    `SAMPLE BY intHash32(UserID) ORDER BY (CounterID, EventDate, intHash32(UserID))`.
+    If a sampling expression is used, the primary key must contain it. Example: `SAMPLE BY intHash32(UserID) ORDER BY (CounterID, EventDate, intHash32(UserID))`.

 - `SETTINGS` — Additional parameters that control the behavior of the `MergeTree`:
    - `index_granularity` — The granularity of an index. The number of data rows between the "marks" of an index. By default, 8192. The list of all available parameters you can see in [MergeTreeSettings.h](https://github.com/yandex/ClickHouse/blob/master/dbms/src/Storages/MergeTree/MergeTreeSettings.h).
    - `use_minimalistic_part_header_in_zookeeper` — Storage method of the data parts headers in ZooKeeper. If  `use_minimalistic_part_header_in_zookeeper=1`, then ZooKeeper stores less data. For more information refer the [setting description](../server_settings/settings.md#server-settings-use_minimalistic_part_header_in_zookeeper) in the "Server configuration parameters" chapter.
-    - `min_merge_bytes_to_use_direct_io` — The minimum data volume for merge operation required for using of the direct I/O access to the storage disk. During the merging of the data parts, ClickHouse calculates summary storage volume of all the data to be merged. If the volume exceeds `min_merge_bytes_to_use_direct_io` bytes, thеn ClickHouse reads and writes the data using direct I/O interface (`O_DIRECT` option) to the storage disk. If `min_merge_bytes_to_use_direct_io = 0`, then the direct I/O is disabled. Default value: `10 * 1024 * 1024 * 1024` bytes.
+    - `min_merge_bytes_to_use_direct_io` — The minimum data volume for merge operation required for using of the direct I/O access to the storage disk. During the merging of the data parts, ClickHouse calculates summary storage volume of all the data to be merged. If the volume exceeds `min_merge_bytes_to_use_direct_io` bytes, then ClickHouse reads and writes the data using direct I/O interface (`O_DIRECT` option) to the storage disk. If `min_merge_bytes_to_use_direct_io = 0`, then the direct I/O is disabled. Default value: `10 * 1024 * 1024 * 1024` bytes.

 **Example of sections setting**

@ -192,7 +190,7 @@ added dimensions.
 In this case it makes sense to leave only a few columns in the primary key that will provide efficient
 range scans and add the remaining dimension columns to the sorting key tuple.

-[ALTER of the sorting key](../../query_language/alter.md) is a lightweight operation because when a new column is simultaneously added to the table and to the sorting key, existing data parts don't need to be changed. Since the old sorting key is a prefix of the new sorting key and there is no data in the just added column, the data at the moment of table modification is sorted by both the old and the new sorting key. 
+[ALTER of the sorting key](../../query_language/alter.md) is a lightweight operation because when a new column is simultaneously added to the table and to the sorting key, existing data parts don't need to be changed. Since the old sorting key is a prefix of the new sorting key and there is no data in the just added column, the data at the moment of table modification is sorted by both the old and the new sorting key.

 ### Use of Indexes and Partitions in Queries

@ -240,11 +238,11 @@ INDEX index_name expr TYPE type(...) GRANULARITY granularity_value

 For tables from the `*MergeTree` family data skipping indices can be specified.

-These indices aggregate some information about the specified expression on blocks, which consist of `granularity_value` granules (size of the granule is specified using `index_granularity` setting in the table engine),
-then these aggregates are used in `SELECT` queries for reducing the amount of data to read from the disk by skipping big blocks of data where `where` query cannot be satisfied.
+These indices aggregate some information about the specified expression on blocks, which consist of `granularity_value` granules (size of the granule is specified using `index_granularity` setting in the table engine), then these aggregates are used in `SELECT` queries for reducing the amount of data to read from the disk by skipping big blocks of data where `where` query cannot be satisfied.


-Example
+**Example**
+
 ```sql
 CREATE TABLE table_name
 (
@ -259,6 +257,7 @@ CREATE TABLE table_name
 ```

 Indices from the example can be used by ClickHouse to reduce the amount of data to read from disk in following queries.
+
 ```sql
 SELECT count() FROM table WHERE s < 'z'
 SELECT count() FROM table WHERE u64 * i32 == 10 AND u64 * length(s) >= 1234
@ -266,22 +265,26 @@ SELECT count() FROM table WHERE u64 * i32 == 10 AND u64 * length(s) >= 1234

 #### Available Types of Indices

-* `minmax`
-Stores extremes of the specified expression (if the expression is `tuple`, then it stores extremes for each element of `tuple`), uses stored info for skipping blocks of the data like the primary key.
+- `minmax`

-* `set(max_rows)`
-Stores unique values of the specified expression (no more than `max_rows` rows, `max_rows=0` means "no limits"), use them to check if the `WHERE` expression is not satisfiable on a block of the data.  
+    Stores extremes of the specified expression (if the expression is `tuple`, then it stores extremes for each element of `tuple`), uses stored info for skipping blocks of the data like the primary key.

-* `ngrambf_v1(n, size_of_bloom_filter_in_bytes, number_of_hash_functions, random_seed)` 
-Stores [bloom filter](https://en.wikipedia.org/wiki/Bloom_filter) that contains all ngrams from block of data. Works only with strings.
-Can be used for optimization of `equals`, `like` and `in` expressions.
-`n` -- ngram size,
-`size_of_bloom_filter_in_bytes` -- bloom filter size in bytes (you can use big values here, for example, 256 or 512, because it can be compressed well),
-`number_of_hash_functions` -- number of hash functions used in bloom filter,
-`random_seed` -- seed for bloom filter hash functions.
+- `set(max_rows)`

-* `tokenbf_v1(size_of_bloom_filter_in_bytes, number_of_hash_functions, random_seed)` 
-The same as `ngrambf_v1`, but instead of ngrams stores tokens, which are sequences separated by non-alphanumeric characters.
+    Stores unique values of the specified expression (no more than `max_rows` rows, `max_rows=0` means "no limits"), use them to check if the `WHERE` expression is not satisfiable on a block of the data.  
+
+- `ngrambf_v1(n, size_of_bloom_filter_in_bytes, number_of_hash_functions, random_seed)`
+
+    Stores [bloom filter](https://en.wikipedia.org/wiki/Bloom_filter) that contains all ngrams from block of data. Works only with strings. Can be used for optimization of `equals`, `like` and `in` expressions.
+
+    - `n` — ngram size,
+    - `size_of_bloom_filter_in_bytes` — bloom filter size in bytes (you can use big values here, for example, 256 or 512, because it can be compressed well),
+    - `number_of_hash_functions` — number of hash functions used in bloom filter,
+    - `random_seed` — seed for bloom filter hash functions.
+
+- `tokenbf_v1(size_of_bloom_filter_in_bytes, number_of_hash_functions, random_seed)`
+
+    The same as `ngrambf_v1`, but instead of ngrams stores tokens, which are sequences separated by non-alphanumeric characters.

 ```sql
 INDEX sample_index (u64 * length(s)) TYPE minmax GRANULARITY 4
@ -289,12 +292,10 @@ INDEX sample_index2 (u64 * length(str), i32 + f64 * 100, date, str) TYPE set(100
 INDEX sample_index3 (lower(str), str) TYPE ngrambf_v1(3, 256, 2, 0) GRANULARITY 4
 ```

-
 ## Concurrent Data Access

 For concurrent table access, we use multi-versioning. In other words, when a table is simultaneously read and updated, data is read from a set of parts that is current at the time of the query. There are no lengthy locks. Inserts do not get in the way of read operations.

 Reading from a table is automatically parallelized.

-
 [Original article](https://clickhouse.yandex/docs/en/operations/table_engines/mergetree/) <!--hide-->
--- a/docs/ru/interfaces/formats.md
+++ b/docs/ru/interfaces/formats.md
@ -4,31 +4,31 @@ ClickHouse может принимать (`INSERT`) и отдавать (`SELECT

 Поддерживаемые форматы и возможность использовать их в запросах `INSERT` и `SELECT` перечислены в таблице ниже.

-Формат | INSERT | SELECT
-------|--------|--------
-[TabSeparated](#tabseparated) | ✔ | ✔ |
-[TabSeparatedRaw](#tabseparatedraw)  | ✗ | ✔ |
-[TabSeparatedWithNames](#tabseparatedwithnames) | ✔ | ✔ |
-[TabSeparatedWithNamesAndTypes](#tabseparatedwithnamesandtypes) | ✔ | ✔ |
-[CSV](#csv) | ✔ | ✔ |
-[CSVWithNames](#csvwithnames) | ✔ | ✔ |
-[Values](#values) | ✔ | ✔ |
-[Vertical](#vertical) | ✗ | ✔ |
-[JSON](#json) | ✗ | ✔ |
-[JSONCompact](#jsoncompact) | ✗ | ✔ |
-[JSONEachRow](#jsoneachrow) | ✔ | ✔ |
-[TSKV](#tskv) | ✔ | ✔ |
-[Pretty](#pretty) | ✗ | ✔ |
-[PrettyCompact](#prettycompact) | ✗ | ✔ |
-[PrettyCompactMonoBlock](#prettycompactmonoblock) | ✗ | ✔ |
-[PrettyNoEscapes](#prettynoescapes) | ✗ | ✔ |
-[PrettySpace](#prettyspace) | ✗ | ✔ |
-[Protobuf](#protobuf) | ✔ | ✔ |
-[RowBinary](#rowbinary) | ✔ | ✔ |
-[Native](#native) | ✔ | ✔ |
-[Null](#null) | ✗ | ✔ |
-[XML](#xml) | ✗ | ✔ |
-[CapnProto](#capnproto) | ✔ | ✗ |
+| Формат | INSERT | SELECT |
+| ------- | -------- | -------- |
+| [TabSeparated](#tabseparated) | ✔ | ✔ |
+| [TabSeparatedRaw](#tabseparatedraw) | ✗ | ✔ |
+| [TabSeparatedWithNames](#tabseparatedwithnames) | ✔ | ✔ |
+| [TabSeparatedWithNamesAndTypes](#tabseparatedwithnamesandtypes) | ✔ | ✔ |
+| [CSV](#csv) | ✔ | ✔ |
+| [CSVWithNames](#csvwithnames) | ✔ | ✔ |
+| [Values](#data-format-values) | ✔ | ✔ |
+| [Vertical](#vertical) | ✗ | ✔ |
+| [JSON](#json) | ✗ | ✔ |
+| [JSONCompact](#jsoncompact) | ✗ | ✔ |
+| [JSONEachRow](#jsoneachrow) | ✔ | ✔ |
+| [TSKV](#tskv) | ✔ | ✔ |
+| [Pretty](#pretty) | ✗ | ✔ |
+| [PrettyCompact](#prettycompact) | ✗ | ✔ |
+| [PrettyCompactMonoBlock](#prettycompactmonoblock) | ✗ | ✔ |
+| [PrettyNoEscapes](#prettynoescapes) | ✗ | ✔ |
+| [PrettySpace](#prettyspace) | ✗ | ✔ |
+| [Protobuf](#protobuf) | ✔ | ✔ |
+| [RowBinary](#rowbinary) | ✔ | ✔ |
+| [Native](#native) | ✔ | ✔ |
+| [Null](#null) | ✗ | ✔ |
+| [XML](#xml) | ✗ | ✔ |
+| [CapnProto](#capnproto) | ✔ | ✗ |

 ## TabSeparated {#tabseparated}

@ -40,7 +40,7 @@ ClickHouse может принимать (`INSERT`) и отдавать (`SELECT

 Формат `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``
 ```

@ -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 делается автоматически.

-Строки выводятся с экранированием спецсимволов с помощью обратного слеша. При выводе, используются следующие 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
@ -91,7 +91,7 @@ world

 Массивы форматируются в виде списка значений через запятую в квадратных скобках. Элементы массива - числа форматируются как обычно, а даты, даты-с-временем и строки - в одинарных кавычках с такими же правилами экранирования, как указано выше.

-[NULL](../query_language/syntax.md) форматируется в виде `\N`.
+[NULL](../query_language/syntax.md) форматируется как `\N`.

 ## TabSeparatedRaw {#tabseparatedraw}

@ -103,7 +103,7 @@ world
 ## TabSeparatedWithNames {#tabseparatedwithnames}

 Отличается от формата `TabSeparated` тем, что в первой строке пишутся имена столбцов.
-При парсинге, первая строка полностью игнорируется: вы не можете использовать имена столбцов, чтобы указать их порядок расположения, или чтобы проверить их корректность.
+При парсинге, первая строка полностью игнорируется. Вы не можете использовать имена столбцов, чтобы указать их порядок расположения, или чтобы проверить их корректность.
 (Поддержка обработки заголовка при парсинге может быть добавлена в будущем.)

 Этот формат также доступен под именем `TSVWithNames`.
@ -132,24 +132,25 @@ SearchPhrase=дизайн штор        count()=1064
 SearchPhrase=баку       count()=1000
 ```

-[NULL](../query_language/syntax.md) форматируется в виде `\N`.
+[NULL](../query_language/syntax.md) форматируется как `\N`.

-``` sql
+```sql
 SELECT * FROM t_null FORMAT TSKV
 ```
+
 ```
 x=1	y=\N
 ```

 При большом количестве маленьких столбцов, этот формат существенно неэффективен, и обычно нет причин его использовать. Он реализован, так как используется в некоторых отделах Яндекса.

-Поддерживается как вывод, так и парсинг данных в этом формате. При парсинге, поддерживается расположение значений разных столбцов в произвольном порядке. Допустимо отсутствие некоторых значений - тогда они воспринимаются как равные значениям по умолчанию. При этом, в качестве значений по умолчанию используются нули, пустые строки и не поддерживаются сложные значения по умолчанию, которые могут быть заданы в таблице.
+Поддерживается как вывод, так и парсинг данных в этом формате. При парсинге, поддерживается расположение значений разных столбцов в произвольном порядке. Допустимо отсутствие некоторых значений - тогда они воспринимаются как равные значениям по умолчанию. В этом случае в качестве значений по умолчанию используются нули и пустые строки. Сложные значения, которые могут быть заданы в таблице не поддерживаются как значения по умолчанию.

 При парсинге, в качестве дополнительного поля, может присутствовать `tskv` без знака равенства и без значения. Это поле игнорируется.

 ## 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 сериализуются, как отдельные столбцы (то есть, теряется их вложенность в кортеж).

@ -159,7 +160,7 @@ clickhouse-client --format_csv_delimiter="|" --query="INSERT INTO test.csv FORMA

 &ast;По умолчанию — `,`. См. настройку [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`.

@ -173,7 +174,7 @@ clickhouse-client --format_csv_delimiter="|" --query="INSERT INTO test.csv FORMA

 Выводит данные в формате 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
 ```

@ -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` - общее количество выведенных строчек.

@ -256,7 +257,7 @@ JSON совместим с JavaScript. Для этого, дополнитель

 ClickHouse поддерживает [NULL](../query_language/syntax.md), который при выводе JSON будет отображен как `null`.

-Смотрите также формат JSONEachRow.
+Смотрите также формат [JSONEachRow](#jsoneachrow) .

 ## JSONCompact {#jsoncompact}

@ -306,24 +307,73 @@ ClickHouse поддерживает [NULL](../query_language/syntax.md), кот

 ## JSONEachRow {#jsoneachrow}

-Выводит данные в виде отдельных JSON объектов для каждой строки (newline delimited JSON).
+При использовании этого формата, ClickHouse выводит каждую запись как объект 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()":"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}

@ -359,7 +409,7 @@ SELECT * FROM t_null
 SELECT 'String with \'quotes\' and \t character' AS Escaping_test
 ```

-``` 
+```
 ┌─Escaping_test────────────────────────┐
 │ String with 'quotes' and 	 character │
 └──────────────────────────────────────┘
@ -445,7 +495,7 @@ Array представлены как длина в формате varint (unsig

 Для поддержки [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`.

--- a/docs/ru/operations/settings/settings.md
+++ b/docs/ru/operations/settings/settings.md
@ -15,10 +15,10 @@ ClickHouse применяет настройку в тех случаях, ко

 Возможные значения:

- `deny`  — значение по умолчанию. Запрещает использование таких подзапросов (При попытке использование вернет исключение "Double-distributed IN/JOIN subqueries is denied");
- `local`  - заменяет базу данных и таблицу в подзапросе на локальные для конечного сервера (шарда), оставив обычный `IN` / `JOIN.`
- `global` - заменяет запрос `IN` / `JOIN` на `GLOBAL IN` / `GLOBAL JOIN.`
- `allow`  - разрешает использование таких подзапросов.
+- `deny` — значение по умолчанию. Запрещает использование таких подзапросов (При попытке использование вернет исключение "Double-distributed IN/JOIN subqueries is denied");
+- `local` — заменяет базу данных и таблицу в подзапросе на локальные для конечного сервера (шарда), оставив обычный `IN` / `JOIN.`
+- `global` — заменяет запрос `IN` / `JOIN` на `GLOBAL IN` / `GLOBAL JOIN.`
+- `allow` — разрешает использование таких подзапросов.

 ## enable_optimize_predicate_expression

@ -62,7 +62,7 @@ ClickHouse применяет настройку в тех случаях, ко

 При `force_index_by_date=1` ClickHouse проверяет, есть ли в запросе условие на ключ даты, которое может использоваться для отсечения диапазонов данных. Если подходящего условия нет - кидается исключение. При этом не проверяется, действительно ли условие уменьшает объём данных для чтения. Например, условие `Date != '2000-01-01'` подходит даже в том случае, когда соответствует всем данным в таблице (т.е. для выполнения запроса требуется full scan). Подробнее про диапазоны данных в таблицах MergeTree читайте в разделе "[MergeTree](../../operations/table_engines/mergetree.md)".

-## force_primary_key
+## force_primary_key {#settings-force_primary_key}

 Запрещает выполнение запросов, если использовать индекс по первичному ключу невозможно.

@ -101,6 +101,30 @@ 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](../../query_language/select.md#select-join).
@ -108,7 +132,7 @@ ClickHouse применяет настройку в тех случаях, ко
 **Возможные значения**

 - `ALL` — если в правой таблице несколько совпадающих строк, данные умножаются на количество этих строк. Это нормальное поведение `JOIN` как в стандартном SQL.
- `ANY` — если в правой таблице несколько соответствующих строк, то соединяется только первая найденная. Если в "правой" таблице есть не более одной подходящей строки, то результаты `ANY` и `ALL`  совпадают.
+- `ANY` — если в правой таблице несколько соответствующих строк, то соединяется только первая найденная. Если в "правой" таблице есть не более одной подходящей строки, то результаты `ANY` и `ALL` совпадают.
 - `Пустая строка` — если `ALL` или `ANY` не указаны в запросе, то ClickHouse генерирует исключение.

 **Значение по умолчанию**: `ALL`
@ -120,7 +144,7 @@ ClickHouse применяет настройку в тех случаях, ко
 **Возможные значения**

 - 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.

@ -140,7 +164,7 @@ ClickHouse применяет настройку в тех случаях, ко

 ## 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` строк в одном запросе, 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) определяет размер кэша несжатых блоков.

 **Возможные значения**

@ -189,6 +213,19 @@ ClickHouse применяет настройку в тех случаях, ко

 **Значение по умолчанию**: 1048576.

+## min_bytes_to_use_direct_io {#settings-min_bytes_to_use_direct_io}
+
+Минимальный объем данных, необходимый для прямого (небуферизованного) чтения/записи (direct I/O) на диск.
+
+ClickHouse использует этот параметр при чтении данных из таблиц. Если общий объем хранения всех данных для чтения превышает `min_bytes_to_use_direct_io` байт, тогда ClickHouse использует флаг `O_DIRECT` при чтении данных с диска.
+
+**Возможные значения**
+
+- 0 — прямой ввод-вывод отключен.
+- Положительное целое число.
+
+**Значение по умолчанию**: 0.
+
 ## log_queries

 Установка логгирования запроса.
@ -228,7 +265,7 @@ ClickHouse применяет настройку в тех случаях, ко
 Этот параметр относится к потокам, которые выполняют параллельно одни стадии конвейера выполнения запроса.
 Например, при чтении из таблицы, если есть возможность вычислять выражения с функциями, фильтровать с помощью WHERE и предварительно агрегировать для GROUP BY параллельно, используя хотя бы количество потоков max_threads, то используются max_threads.

-По умолчанию - 2.
+Значение по умолчанию: 2.

 Если на сервере обычно исполняется менее одного запроса SELECT одновременно, то выставите этот параметр в значение чуть меньше количества реальных процессорных ядер.

@ -256,7 +293,7 @@ ClickHouse применяет настройку в тех случаях, ко

 Как правило, не имеет смысла менять эту настройку.

-## max_query_size
+## max_query_size {#settings-max_query_size}

 Максимальный кусок запроса, который будет считан в оперативку для разбора парсером языка SQL.
 Запрос INSERT также содержит данные для INSERT-а, которые обрабатываются отдельным, потоковым парсером (расходующим O(1) оперативки), и не учитываются в этом ограничении.
@ -285,7 +322,7 @@ ClickHouse применяет настройку в тех случаях, ко

 Максимальное количество одновременных соединений с удалёнными серверами при распределённой обработке одного запроса к одной таблице типа Distributed. Рекомендуется выставлять не меньше, чем количество серверов в кластере.

-По умолчанию - 1024.
+Значение по умолчанию: 1024.

 Следующие параметры имеют значение только на момент создания таблицы типа Distributed (и при запуске сервера), поэтому их не имеет смысла менять в рантайме.

@ -293,7 +330,7 @@ ClickHouse применяет настройку в тех случаях, ко

 Максимальное количество одновременных соединений с удалёнными серверами при распределённой обработке всех запросов к одной таблице типа Distributed. Рекомендуется выставлять не меньше, чем количество серверов в кластере.

-По умолчанию - 1024.
+Значение по умолчанию: 1024.

 ## connect_timeout_with_failover_ms

@ -316,7 +353,8 @@ ClickHouse применяет настройку в тех случаях, ко
 ## use_uncompressed_cache {#setting-use_uncompressed_cache}

 Использовать ли кэш разжатых блоков. Принимает 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.

@ -337,7 +375,7 @@ ClickHouse применяет настройку в тех случаях, ко

 ## stream_flush_interval_ms

-Работает для таблиц со стриммингом в случае тайм-аута, или когда поток генерирует [max_insert_block_size](#settings-max_insert_block_size)  строк.
+Работает для таблиц со стриммингом в случае тайм-аута, или когда поток генерирует [max_insert_block_size](#settings-max_insert_block_size) строк.

 Значение по умолчанию - 7500.

@ -404,11 +442,7 @@ ClickHouse применяет настройку в тех случаях, ко
 Если значение равно true, то при выполнении INSERT входные данные из столбцов с неизвестными именами будут пропущены. В противном случае эта ситуация создаст исключение.
 Работает для форматов JSONEachRow и TSKV.

-## insert_sample_with_metadata
-
-Для запросов INSERT. Указывает, что серверу необходимо отправлять клиенту метаданные о значениях столбцов по умолчанию, которые будут использоваться для вычисления выражений по умолчанию. По умолчанию отключено.
-
-## output_format_json_quote_64bit_integers
+## output_format_json_quote_64bit_integers {#session_settings-output_format_json_quote_64bit_integers}

 Если значение истинно, то при использовании JSON\* форматов UInt64 и Int64 числа выводятся в кавычках (из соображений совместимости с большинством реализаций JavaScript), иначе - без кавычек.

@ -470,4 +504,3 @@ ClickHouse применяет настройку в тех случаях, ко
 - [insert_quorum_timeout](#settings-insert_quorum_timeout)

 [Оригинальная статья](https://clickhouse.yandex/docs/ru/operations/settings/settings/) <!--hide-->
-
--- a/docs/ru/operations/table_engines/mergetree.md
+++ b/docs/ru/operations/table_engines/mergetree.md
@ -2,8 +2,7 @@

 Движок `MergeTree`, а также другие движки этого семейства (`*MergeTree`) — это наиболее функциональные движки таблиц ClickHousе.

-!!!info
-    Движок [Merge](merge.md) не относится к семейству `*MergeTree`.
+Основная идея, заложенная в основу движков семейства `MergeTree` следующая. Когда у вас есть огромное количество данных, которые должны быть вставлены в таблицу, вы должны быстро записать их по частям, а затем объединить части по некоторым правилам в фоновом режиме. Этот метод намного эффективнее, чем постоянная перезапись данных в хранилище при вставке.

 Основные возможности:

@ -23,6 +22,8 @@

    При необходимости можно задать способ сэмплирования данных в таблице.

+!!! info
+    Движок [Merge](merge.md) не относится к семейству `*MergeTree`.

 ## Создание таблицы {#table_engine-mergetree-creating-a-table}

@ -46,7 +47,7 @@ CREATE TABLE [IF NOT EXISTS] [db.]table_name [ON CLUSTER cluster]

 **Секции запроса**

- `ENGINE` — Имя и параметры движка. `ENGINE = MergeTree()`. Движок `MergeTree` не имеет параметров.
+- `ENGINE` — Имя и параметры движка. `ENGINE = MergeTree()`. `MergeTree` не имеет параметров.

 - `PARTITION BY` — [ключ партиционирования](custom_partitioning_key.md).

@ -54,21 +55,21 @@ CREATE TABLE [IF NOT EXISTS] [db.]table_name [ON CLUSTER cluster]

 - `ORDER BY` — ключ сортировки.

-    Кортеж столбцов или произвольных выражений. Пример: `ORDER BY (CounerID, EventDate)`.  
+    Кортеж столбцов или произвольных выражений. Пример: `ORDER BY (CounterID, EventDate)`.

- `PRIMARY KEY` - первичный ключ, если он [отличается от ключа сортировки](mergetree.md).
+- `PRIMARY KEY` — первичный ключ, если он [отличается от ключа сортировки](mergetree.md).

-    По умолчанию первичный ключ совпадает с ключом сортировки (который задаётся секцией `ORDER BY`). Поэтому
-    в большинстве случаев секцию `PRIMARY KEY` отдельно указывать не нужно.
+    По умолчанию первичный ключ совпадает с ключом сортировки (который задаётся секцией `ORDER BY`.) Поэтому в большинстве случаев секцию `PRIMARY KEY` отдельно указывать не нужно.

 - `SAMPLE BY` — выражение для сэмплирования.

-    Если используется выражение для сэмплирования, то первичный ключ должен содержать его. Пример:  
-    `SAMPLE BY intHash32(UserID) ORDER BY (CounerID, EventDate, intHash32(UserID))`.
+    Если используется выражение для сэмплирования, то первичный ключ должен содержать его. Пример:
+`SAMPLE BY intHash32(UserID) ORDER BY (CounterID, EventDate, intHash32(UserID))`.

 - `SETTINGS` — дополнительные параметры, регулирующие поведение `MergeTree`:

-    - `index_granularity` — гранулярность индекса. Число строк данных между «засечками» индекса. По умолчанию — 8192.
+    - `index_granularity` — гранулярность индекса. Число строк данных между «засечками» индекса. По умолчанию — 8192. Список всех доступных параметров можно посмотреть в [MergeTreeSettings.h](https://github.com/yandex/ClickHouse/blob/master/dbms/src/Storages/MergeTree/MergeTreeSettings.h).
+    - `min_merge_bytes_to_use_direct_io` — минимальный объем данных, необходимый для прямого (небуферизованного) чтения/записи (direct I/O) на диск. При слиянии частей данных ClickHouse вычисляет общий объем хранения всех данных, подлежащих слиянию. Если общий объем хранения всех данных для чтения превышает `min_bytes_to_use_direct_io` байт, тогда ClickHouse  использует флаг `O_DIRECT` при чтении данных с диска. Если `min_merge_bytes_to_use_direct_io = 0`, тогда прямой ввод-вывод отключен. Значение по умолчанию: `10 * 1024 * 1024 * 1024` байт.

 **Пример задания секций**

@ -78,7 +79,8 @@ ENGINE MergeTree() PARTITION BY toYYYYMM(EventDate) ORDER BY (CounterID, EventDa

 В примере мы устанавливаем партиционирование по месяцам.

-Также мы задаем выражение для сэмплирования в виде хэша по идентификатору посетителя. Это позволяет псевдослучайным образом перемешать данные в таблице для каждого `CounterID` и `EventDate`. Если при выборке данных задать секцию [SAMPLE](../../query_language/select.md#sample], то ClickHouse вернёт равномерно-псевдослучайную выборку данных для подмножества посетителей.
+Также мы задаем выражение для сэмплирования в виде хэша по идентификатору посетителя. Это позволяет псевдослучайным образом перемешать данные в таблице для каждого `CounterID` и `EventDate`. Если при выборке данных задать секцию [SAMPLE](../../query_language/select.md#select-section-sample), то ClickHouse вернёт равномерно-псевдослучайную выборку данных для подмножества посетителей.
+
 `index_granularity` можно было не указывать, поскольку 8192 — это значение по умолчанию.

 <details markdown="1"><summary>Устаревший способ создания таблицы</summary>
@ -118,13 +120,13 @@ MergeTree(EventDate, intHash32(UserID), (CounterID, EventDate, intHash32(UserID)

 Данные, относящиеся к разным партициям, разбиваются на разные куски. В фоновом режиме ClickHouse выполняет слияния (merge) кусков данных для более эффективного хранения. Куски, относящиеся к разным партициям не объединяются. Механизм слияния не гарантирует, что все строки с одинаковым первичным ключом окажутся в одном куске.

-Для каждого куска данных ClickHouse создаёт индексный файл, который содержит значение первичного ключа для каждой индексной строки («засечка»). Номера индексных строк определяются как `n * index_granularity`, а максимальное значение `n` равно целой части от деления общего количества строк на `index_granularity`. Для каждого столбца также пишутся «засечки» для тех же индексных строк, что и для первичного ключа, эти «засечки»  позволяют находить непосредственно данные в столбцах.
+Для каждого куска данных ClickHouse создаёт индексный файл, который содержит значение первичного ключа для каждой индексной строки («засечка»). Номера строк индекса определяются как `n * index_granularity`. Максимальное значение `n` равно целой части деления общего числа строк на `index_granularity`. Для каждого столбца "засечки" также записываются для тех же строк индекса, что и первичный ключ. Эти "засечки" позволяют находить данные непосредственно в столбцах.

 Вы можете использовать одну большую таблицу, постоянно добавляя в неё данные пачками, именно для этого предназначен движок `MergeTree`.

 ## Первичные ключи и индексы в запросах {#primary-keys-and-indexes-in-queries}

-Рассмотрим первичный ключ — `(CounterID, Date)`, в этом случае, сортировку и индекс можно проиллюстрировать следующим образом:
+Рассмотрим первичный ключ — `(CounterID, Date)`. В этом случае сортировку и индекс можно проиллюстрировать следующим образом:

 ```
 Whole data:     [-------------------------------------------------------------------------]
@ -166,11 +168,10 @@ ClickHouse не требует уникального первичного кл

 - Обеспечить дополнительную логику при слиянии кусков данных в движках [CollapsingMergeTree](collapsingmergetree.md#table_engine-collapsingmergetree) и [SummingMergeTree](summingmergetree.md).

-    В этом случае имеет смысл задать отдельный *ключ сортировки*, отличающийся от первичного ключа.
+    В этом случае имеет смысл указать отдельный *ключ сортировки*, отличающийся от первичного ключа.

 Длинный первичный ключ будет негативно влиять на производительность вставки и потребление памяти, однако на производительность ClickHouse при запросах `SELECT` лишние столбцы в первичном ключе не влияют.

-
 ### Первичный ключ, отличный от ключа сортировки

 Существует возможность задать первичный ключ (выражение, значения которого будут записаны в индексный файл для
@ -181,16 +182,14 @@ ClickHouse не требует уникального первичного кл
 Данная возможность особенно полезна при использовании движков [SummingMergeTree](summingmergetree.md)
 и [AggregatingMergeTree](aggregatingmergetree.md). В типичном сценарии использования этих движков таблица
 содержит столбцы двух типов: *измерения* (dimensions) и *меры* (measures). Типичные запросы агрегируют
-значения столбцов-мер с произвольной группировкой и фильтрацией по измерениям. Так как SummingMergeTree
-и AggregatingMergeTree производят фоновую агрегацию строк с одинаковым значением ключа сортировки, приходится
+значения столбцов-мер с произвольной группировкой и фильтрацией по измерениям. Так как `SummingMergeTree`
+и `AggregatingMergeTree` производят фоновую агрегацию строк с одинаковым значением ключа сортировки, приходится
 добавлять в него все столбцы-измерения. В результате выражение ключа содержит большой список столбцов,
 который приходится постоянно расширять при добавлении новых измерений.

-В этом сценарии имеет смысл оставить в первичном ключе всего несколько столбцов, которые обеспечат эффективную
-фильтрацию по индексу, а остальные столбцы-измерения добавить в выражение ключа сортировки.
+В этом сценарии имеет смысл оставить в первичном ключе всего несколько столбцов, которые обеспечат эффективную фильтрацию по индексу, а остальные столбцы-измерения добавить в выражение ключа сортировки.

-[ALTER ключа сортировки](../../query_language/alter.md) — легкая операция, так как при одновременном добавлении нового столбца в таблицу и в ключ сортировки, не нужно изменять
-данные кусков (они остаются упорядоченными и по новому выражению ключа).
+[ALTER ключа сортировки](../../query_language/alter.md) — лёгкая операция, так как при одновременном добавлении нового столбца в таблицу и ключ сортировки не нужно изменять данные кусков (они остаются упорядоченными и по новому выражению ключа).

 ### Использование индексов и партиций в запросах

@ -206,7 +205,7 @@ ENGINE MergeTree() PARTITION BY toYYYYMM(EventDate) ORDER BY (CounterID, EventDa

 В этом случае в запросах:

-``` sql
+```sql
 SELECT count() FROM table WHERE EventDate = toDate(now()) AND CounterID = 34
 SELECT count() FROM table WHERE EventDate = toDate(now()) AND (CounterID = 34 OR CounterID = 42)
 SELECT count() FROM table WHERE ((EventDate >= toDate('2014-01-01') AND EventDate <= toDate('2014-01-31')) OR EventDate = toDate('2014-05-01')) AND CounterID IN (101500, 731962, 160656) AND (CounterID = 101500 OR EventDate != toDate('2014-05-01'))
@ -218,23 +217,30 @@ ClickHouse будет использовать индекс по первичн

 В примере ниже индекс не может использоваться.

-``` sql
+```sql
 SELECT count() FROM table WHERE CounterID = 34 OR URL LIKE '%upyachka%'
 ```

-Чтобы проверить, сможет ли ClickHouse использовать индекс при выполнении запроса, используйте настройки [force_index_by_date](../settings/settings.md#settings-force_index_by_date) и [force_primary_key](../settings/settings.md).
+Чтобы проверить, сможет ли ClickHouse использовать индекс при выполнении запроса, используйте настройки [force_index_by_date](../settings/settings.md#settings-force_index_by_date) и [force_primary_key](../settings/settings.md#settings-force_primary_key).

 Ключ партиционирования по месяцам обеспечивает чтение только тех блоков данных, которые содержат даты из нужного диапазона. При этом блок данных может содержать данные за многие даты (до целого месяца). В пределах одного блока данные упорядочены по первичному ключу, который может не содержать дату в качестве первого столбца. В связи с этим, при использовании запроса с указанием условия только на дату, но не на префикс первичного ключа, будет читаться данных больше, чем за одну дату.

-### Дополнительные индексы (Экспериментальный функционал)
+### Дополнительные индексы (Экспериментальная функциональность)

-Для использования требуется установить настройку `allow_experimental_data_skipping_indices` в 1.  (запустить `SET allow_experimental_data_skipping_indices = 1`).
+Для использования требуется установить настройку `allow_experimental_data_skipping_indices` в 1. (запустить `SET allow_experimental_data_skipping_indices = 1`).
+
+Объявление индексов при определении столбцов в запросе `CREATE`.
+
+```sql
+INDEX index_name expr TYPE type(...) GRANULARITY granularity_value
+```

 Для таблиц семейства `*MergeTree` можно задать дополнительные индексы в секции столбцов.

 Индексы агрегируют для заданного выражения некоторые данные, а потом при `SELECT` запросе используют для пропуска блоков данных (пропускаемый блок состоит из гранул данных в количестве равном гранулярности данного индекса), на которых секция `WHERE` не может быть выполнена, тем самым уменьшая объем данных читаемых с диска.

-Пример
+**Пример**
+
 ```sql
 CREATE TABLE table_name
 (
@ -243,12 +249,13 @@ CREATE TABLE table_name
    s String,
    ...
    INDEX a (u64 * i32, s) TYPE minmax GRANULARITY 3,
-    INDEX b (u64 * length(s), i32) TYPE set(1000) GRANULARITY 4
+    INDEX b (u64 * length(s)) TYPE set(1000) GRANULARITY 4
 ) ENGINE = MergeTree()
 ...
 ```

 Эти индексы смогут использоваться для оптимизации следующих запросов
+
 ```sql
 SELECT count() FROM table WHERE s < 'z'
 SELECT count() FROM table WHERE u64 * i32 == 10 AND u64 * length(s) >= 1234
@ -262,14 +269,13 @@ SELECT count() FROM table WHERE u64 * i32 == 10 AND u64 * length(s) >= 1234
 * `set(max_rows)`
 Хранит уникальные значения выражения на блоке в количестве не более `max_rows` (если `max_rows = 0`, то ограничений нет), используя их для пропуска блоков, оценивая выполнимость `WHERE` выражения на хранимых данных.

+**Примеры**

-Примеры
 ```sql
 INDEX b (u64 * length(str), i32 + f64 * 100, date, str) TYPE minmax GRANULARITY 4
 INDEX b (u64 * length(str), i32 + f64 * 100, date, str) TYPE set(100) GRANULARITY 4
 ```

-
 ## Конкурентный доступ к данным

 Для конкурентного доступа к таблице используется мультиверсионность. То есть, при одновременном чтении и обновлении таблицы, данные будут читаться из набора кусочков, актуального на момент запроса. Длинных блокировок нет. Вставки никак не мешают чтениям.
--- a/docs/ru/query_language/select.md
+++ b/docs/ru/query_language/select.md
@ -60,7 +60,7 @@ SELECT [DISTINCT] expr_list

 Свойства сэмплирования:

- Сэмплирование работает детерминированно. При многократном выполнении одного и того же запроса `SELECT .. SAMPLE`, результат всегда будет одинаковым. 
+- Сэмплирование работает детерминированно. При многократном выполнении одного и того же запроса `SELECT .. SAMPLE`, результат всегда будет одинаковым.
 - Сэмплирование поддерживает консистентность для разных таблиц. Имеется в виду, что для таблиц с одним и тем же ключом сэмплирования, подмножество данных в выборках будет одинаковым (выборки при этом должны быть сформированы для одинаковой доли данных). Например, выборка по идентификаторам посетителей выберет из разных таблиц строки с одинаковым подмножеством всех возможных идентификаторов. Это свойство позволяет использовать выборки в подзапросах в секции [IN](#select-in-operators), а также объединять выборки с помощью [JOIN](#select-join).
 - Сэмплирование позволяет читать меньше данных с диска. Обратите внимание, для этого необходимо корректно указать ключ сэмплирования. Подробнее см. в разделе [Создание таблицы MergeTree](../operations/table_engines/mergetree.md#table_engine-mergetree-creating-a-table).

@ -68,11 +68,11 @@ SELECT [DISTINCT] expr_list

 Выражение `SAMPLE` в запросе можно задать следующими способами:

-| Способ&#160;задания&#160;SAMPLE| Описание | 
-| ---------------- | --------- | 
+| Способ&#160;задания&#160;SAMPLE| Описание |
+| ---------------- | --------- |
 | `SAMPLE k` | Здесь `k` – это дробное число в интервале от 0 до 1.<br/> Запрос будет выполнен по `k` доле данных. Например, если указано `SAMPLE 1/10`, то запрос будет выполнен для выборки из 1/10 данных. [Подробнее](#select-sample-k)|
 | `SAMPLE n` | Здесь `n` – это достаточно большое целое число.</br> Запрос будет выполнен для выборки, состоящей из не менее чем `n` строк. Например, если указано `SAMPLE 10000000`, то запрос будет выполнен для не менее чем 10,000,000 строк. [Подробнее](#select-sample-n) |
-| `SAMPLE k OFFSET m` | Здесь `k` и `m` – числа от 0 до 1.</br> Запрос будет выполнен по `k` доле данных. При этом выборка будет сформирована со смещением на `m` долю. [Подробнее](#select-sample-offset) | 
+| `SAMPLE k OFFSET m` | Здесь `k` и `m` – числа от 0 до 1.</br> Запрос будет выполнен по `k` доле данных. При этом выборка будет сформирована со смещением на `m` долю. [Подробнее](#select-sample-offset) |

 #### SAMPLE k {#select-sample-k}

@ -98,14 +98,14 @@ ORDER BY PageViews DESC LIMIT 1000

 #### SAMPLE n {#select-sample-n}

-Здесь `n` – это достаточно большое целое число. Например, `SAMPLE 10000000`. 
+Здесь `n` – это достаточно большое целое число. Например, `SAMPLE 10000000`.

-Если задано выражение `SAMPLE n`, запрос будет выполнен для выборки из не менее `n` строк (но не значительно больше этого значения). Например, если задать `SAMPLE 10000000`, в выборку попадут не менее 10,000,000 строк. 
+Если задано выражение `SAMPLE n`, запрос будет выполнен для выборки из не менее `n` строк (но не значительно больше этого значения). Например, если задать `SAMPLE 10000000`, в выборку попадут не менее 10,000,000 строк.

 !!! note "Примечание"
    Следует иметь в виду, что `n` должно быть достаточно большим числом. Так как минимальной единицей данных для чтения является одна гранула (её размер задаётся настройкой `index_granularity` для таблицы), имеет смысл создавать выборки, размер которых существенно превосходит размер гранулы.

-При выполнении `SAMPLE n` коэффициент сэмплирования заранее неизвестен (то есть нет информации о том, относительно какого количества данных будет сформирована выборка). Чтобы узнать коэффициент сэмплирования, используйте столбец `_sample_factor`. 
+При выполнении `SAMPLE n` коэффициент сэмплирования заранее неизвестен (то есть нет информации о том, относительно какого количества данных будет сформирована выборка). Чтобы узнать коэффициент сэмплирования, используйте столбец `_sample_factor`.

 Виртуальный столбец `_sample_factor` автоматически создается в тех таблицах, для которых задано выражение `SAMPLE BY` (подробнее см. в разделе [Создание таблицы MergeTree](../operations/table_engines/mergetree.md#table_engine-mergetree-creating-a-table)). В столбце содержится коэффициент сэмплирования для таблицы – он рассчитывается динамически по мере добавления данных в таблицу. Ниже приведены примеры использования столбца `_sample_factor`.

@ -793,7 +793,7 @@ WHERE и HAVING отличаются тем, что WHERE выполняется

 `LIMIT m` позволяет выбрать из результата первые `m` строк.

-`LIMIT n, m` позволяет выбрать из результата первые `m` строк после пропуска первых `n` строк. Синтаксис `LIMIT m OFFSET n` также поддерживается. 
+`LIMIT n, m` позволяет выбрать из результата первые `m` строк после пропуска первых `n` строк. Синтаксис `LIMIT m OFFSET n` также поддерживается.

 `n` и `m` должны быть неотрицательными целыми числами.

--- a/docs/tools/build.py
+++ b/docs/tools/build.py
@ -3,14 +3,12 @@
 from __future__ import unicode_literals

 import argparse
-import contextlib
 import datetime
 import logging
 import os
 import shutil
 import subprocess
 import sys
-import tempfile
 import time

 import markdown.extensions
@ -21,26 +19,12 @@ from mkdocs import exceptions
 from mkdocs.commands import build as mkdocs_build

 from concatenate import concatenate
+
 from website import build_website, minify_website
 import mdx_clickhouse
 import test
+import util

-@contextlib.contextmanager
-def temp_dir():
-    path = tempfile.mkdtemp(dir=os.environ.get('TEMP'))
-    try:
-        yield path
-    finally:
-        shutil.rmtree(path)
-
-
-@contextlib.contextmanager
-def autoremoved_file(path):
-    try:
-        with open(path, 'w') as handle:
-            yield handle
-    finally:
-        os.unlink(path)

 class ClickHouseMarkdown(markdown.extensions.Extension):
    class ClickHousePreprocessor(markdown.util.Processor):
@ -52,8 +36,10 @@ class ClickHouseMarkdown(markdown.extensions.Extension):
    def extendMarkdown(self, md):
        md.preprocessors.register(self.ClickHousePreprocessor(), 'clickhouse_preprocessor', 31)

+
 markdown.extensions.ClickHouseMarkdown = ClickHouseMarkdown

+
 def build_for_lang(lang, args):
    logging.info('Building %s docs' % lang)
    os.environ['SINGLE_PAGE'] = '0'
@ -80,25 +66,29 @@ def build_for_lang(lang, args):
            'search_index_only': True,
            'static_templates': ['404.html'],
            'extra': {
-                'single_page': False,
                'now': int(time.mktime(datetime.datetime.now().timetuple())) # TODO better way to avoid caching
            }
        }

        site_names = {
-            'en': 'ClickHouse Documentation',
-            'ru': 'Документация ClickHouse',
-            'zh': 'ClickHouse文档',
-            'fa': 'مستندات ClickHouse'
+            'en': 'ClickHouse %s Documentation',
+            'ru': 'Документация ClickHouse %s',
+            'zh': 'ClickHouse文档 %s',
+            'fa': 'مستندات  %sClickHouse'
        }

+        if args.version_prefix:
+            site_dir = os.path.join(args.docs_output_dir, args.version_prefix, lang)
+        else:
+            site_dir = os.path.join(args.docs_output_dir, lang)
+            
        cfg = config.load_config(
            config_file=config_path,
-            site_name=site_names.get(lang, site_names['en']),
+            site_name=site_names.get(lang, site_names['en']) % args.version_prefix,
            site_url='https://clickhouse.yandex/docs/%s/' % lang,
            docs_dir=os.path.join(args.docs_dir, lang),
-            site_dir=os.path.join(args.docs_output_dir, lang),
-            strict=True,
+            site_dir=site_dir,
+            strict=not args.version_prefix,
            theme=theme_cfg,
            copyright='©2016–2019 Yandex LLC',
            use_directory_urls=True,
@ -127,7 +117,9 @@ def build_for_lang(lang, args):
            extra={
                'search': {
                    'language': 'en,ru' if lang == 'ru' else 'en'
-                }
+                },
+                'stable_releases': args.stable_releases,
+                'version_prefix': args.version_prefix
            }
        )

@ -144,13 +136,14 @@ def build_single_page_version(lang, args, cfg):
    logging.info('Building single page version for ' + lang)
    os.environ['SINGLE_PAGE'] = '1'

-    with autoremoved_file(os.path.join(args.docs_dir, lang, 'single.md')) as single_md:
+    with util.autoremoved_file(os.path.join(args.docs_dir, lang, 'single.md')) as single_md:
        concatenate(lang, args.docs_dir, single_md)

-        with temp_dir() as site_temp:
-            with temp_dir() as docs_temp:
+        with util.temp_dir() as site_temp:
+            with util.temp_dir() as docs_temp:
+                docs_src_lang = os.path.join(args.docs_dir, lang)
                docs_temp_lang = os.path.join(docs_temp, lang)
-                shutil.copytree(os.path.join(args.docs_dir, lang), docs_temp_lang)
+                shutil.copytree(docs_src_lang, docs_temp_lang)
                for root, _, filenames in os.walk(docs_temp_lang):
                    for filename in filenames:
                        if filename != 'single.md' and filename.endswith('.md'):
@ -169,7 +162,10 @@ def build_single_page_version(lang, args, cfg):

                mkdocs_build.build(cfg)

-                single_page_output_path = os.path.join(args.docs_dir, args.docs_output_dir, lang, 'single')
+                if args.version_prefix:
+                    single_page_output_path = os.path.join(args.docs_dir, args.docs_output_dir, args.version_prefix, lang, 'single')
+                else:
+                    single_page_output_path = os.path.join(args.docs_dir, args.docs_output_dir, lang, 'single')

                if os.path.exists(single_page_output_path):
                    shutil.rmtree(single_page_output_path)
@ -186,7 +182,7 @@ def build_single_page_version(lang, args, cfg):
                    logging.debug(' '.join(create_pdf_command))
                    subprocess.check_call(' '.join(create_pdf_command), shell=True)

-                with temp_dir() as test_dir:
+                with util.temp_dir() as test_dir:
                    cfg.load_dict({
                        'docs_dir': docs_temp_lang,
                        'site_dir': test_dir,
@ -198,7 +194,8 @@ def build_single_page_version(lang, args, cfg):
                        ]
                    })
                    mkdocs_build.build(cfg)
-                    test.test_single_page(os.path.join(test_dir, 'single', 'index.html'), lang)
+                    if not args.version_prefix:  # maybe enable in future
+                        test.test_single_page(os.path.join(test_dir, 'single', 'index.html'), lang)
                    if args.save_raw_single_page:
                        shutil.copytree(test_dir, args.save_raw_single_page)

@ -217,6 +214,11 @@ def build_redirects(args):
        f.write('\n'.join(rewrites))


+def build_docs(args):
+    for lang in args.lang.split(','):
+        build_for_lang(lang, args)
+
+
 def build(args):
    if os.path.exists(args.output_dir):
        shutil.rmtree(args.output_dir)
@ -224,21 +226,28 @@ def build(args):
    if not args.skip_website:
        build_website(args)

-    for lang in args.lang.split(','):
-        build_for_lang(lang, args)
+    build_docs(args)
+    
+    from github import build_releases
+    build_releases(args, build_docs)

    build_redirects(args)

    if not args.skip_website:
        minify_website(args)

+
 if __name__ == '__main__':
+    os.chdir(os.path.join(os.path.dirname(__file__), '..'))
+    
    arg_parser = argparse.ArgumentParser()
    arg_parser.add_argument('--lang', default='en,ru,zh,fa')
    arg_parser.add_argument('--docs-dir', default='.')
    arg_parser.add_argument('--theme-dir', default='mkdocs-material-theme')
    arg_parser.add_argument('--website-dir', default=os.path.join('..', 'website'))
    arg_parser.add_argument('--output-dir', default='build')
+    arg_parser.add_argument('--enable-stable-releases', action='store_true')
+    arg_parser.add_argument('--version-prefix', type=str, default='')
    arg_parser.add_argument('--skip-single-page', action='store_true')
    arg_parser.add_argument('--skip-pdf', action='store_true')
    arg_parser.add_argument('--skip-website', action='store_true')
@ -246,8 +255,12 @@ if __name__ == '__main__':
    arg_parser.add_argument('--verbose', action='store_true')

    args = arg_parser.parse_args()
-    args.docs_output_dir = os.path.join(args.output_dir, 'docs')
-    os.chdir(os.path.join(os.path.dirname(__file__), '..'))
+    args.docs_output_dir = os.path.join(os.path.abspath(args.output_dir), 'docs')
+    
+    from github import choose_latest_releases
+    args.stable_releases = choose_latest_releases() if args.enable_stable_releases else []
+    
+    

    logging.basicConfig(
        level=logging.DEBUG if args.verbose else logging.INFO,
--- a/docs/tools/concatenate.py
+++ b/docs/tools/concatenate.py
@ -1,17 +1,5 @@
 # -*- coding: utf-8 -*-

-# - Single-page document.
-#   - Requirements to the md-souces:
-#       - Don't use links without anchors. It means, that you can not just link file. You should specify an anchor at the top of the file and then link to this anchor
-#       - Anchors should be unique through whole document.
-#   - Implementation:
-#       - Script gets list of the file from the `pages` section of `mkdocs.yml`. It gets commented files too, and it right.
-#       - Files are concatenated by order with incrementing level of headers in all files except the first one
-#       - Script converts links to other files into inside page links.
-#         - Skipping links started with 'http'
-#         - Not http-links with anchor are cutted to the anchor sign (#).
-#         - For not http-links without anchor script logs an error and cuts them from the resulting single-page document.
-
 import logging
 import re
 import os
@ -34,35 +22,36 @@ def concatenate(lang, docs_path, single_page_file):
        ' files will be concatenated into single md-file.')
    logging.debug('Concatenating: ' + ', '.join(files_to_concatenate))

-    first_file = True
-
    for path in files_to_concatenate:
-        with open(os.path.join(lang_path, path)) as f:
-            anchors = set()
-            tmp_path = path.replace('/index.md', '/').replace('.md', '/')
-            prefixes = ['', '../', '../../', '../../../']
-            parts = tmp_path.split('/')
-            anchors.add(parts[-2] + '/')
-            anchors.add('/'.join(parts[1:]))
-
-            for part in parts[0:-2] if len(parts) > 2 else parts:
-                for prefix in prefixes:
-                    anchor = prefix + tmp_path
-                    if anchor:
-                        anchors.add(anchor)
-                        anchors.add('../' + anchor)
-                        anchors.add('../../' + anchor)
-                tmp_path = tmp_path.replace(part, '..')
-
-            for anchor in anchors:
-                if re.search(az_re, anchor):
-                    single_page_file.write('<a name="%s"></a>\n' % anchor)
-
-            single_page_file.write('\n\n')
-
-            for l in f:
-                if l.startswith('#'):
-                    l = '#' + l
-                single_page_file.write(l)
+        try:
+            with open(os.path.join(lang_path, path)) as f:
+                anchors = set()
+                tmp_path = path.replace('/index.md', '/').replace('.md', '/')
+                prefixes = ['', '../', '../../', '../../../']
+                parts = tmp_path.split('/')
+                anchors.add(parts[-2] + '/')
+                anchors.add('/'.join(parts[1:]))
+    
+                for part in parts[0:-2] if len(parts) > 2 else parts:
+                    for prefix in prefixes:
+                        anchor = prefix + tmp_path
+                        if anchor:
+                            anchors.add(anchor)
+                            anchors.add('../' + anchor)
+                            anchors.add('../../' + anchor)
+                    tmp_path = tmp_path.replace(part, '..')
+    
+                for anchor in anchors:
+                    if re.search(az_re, anchor):
+                        single_page_file.write('<a name="%s"></a>\n' % anchor)
+    
+                single_page_file.write('\n\n')
+    
+                for l in f:
+                    if l.startswith('#'):
+                        l = '#' + l
+                    single_page_file.write(l)
+        except IOError as e:
+            logging.warning(str(e))

    single_page_file.flush()
--- a/docs/tools/github.py
+++ b/docs/tools/github.py
@ -0,0 +1,44 @@
+import collections
+import copy
+import io
+import logging
+import os
+import tarfile
+
+import requests
+
+import util
+
+
+def choose_latest_releases():
+    seen = collections.OrderedDict()
+    candidates = requests.get('https://api.github.com/repos/yandex/ClickHouse/tags?per_page=100').json()
+    for tag in candidates:
+        name = tag.get('name', '')
+        if 'v18' in name or 'stable' not in name:
+            continue
+        major_version = '.'.join((name.split('.', 2))[:2])
+        if major_version not in seen:
+            seen[major_version] = (name, tag.get('tarball_url'),)
+            
+    return seen.items()
+    
+
+def process_release(args, callback, release):
+    name, (full_name, tarball_url,) = release
+    logging.info('Building docs for %s', full_name)
+    buf = io.BytesIO(requests.get(tarball_url).content)
+    tar = tarfile.open(mode='r:gz', fileobj=buf)
+    with util.temp_dir() as base_dir:
+        tar.extractall(base_dir)
+        args = copy.deepcopy(args)
+        args.version_prefix = name
+        args.docs_dir = os.path.join(base_dir, os.listdir(base_dir)[0], 'docs')
+        callback(args)
+
+
+def build_releases(args, callback):
+    for release in args.stable_releases:
+        process_release(args, callback, release)
+
+
--- a/docs/tools/mkdocs-material-theme/assets/stylesheets/custom.css
+++ b/docs/tools/mkdocs-material-theme/assets/stylesheets/custom.css
@ -166,6 +166,38 @@ h1, h2, h3, .md-logo {
    text-decoration: none;
 }

+.md-selector {
+    border: 1px solid #ccc;
+    padding: 2px;
+    border-radius: 3px;
+    overflow: hidden;
+    background: #fff;
+}
+
+.md-selector select {
+    padding: 8px 8px;
+    border: none;
+    box-shadow: none;
+    background: transparent;
+    background-image: none;
+    -webkit-appearance: none;
+    display: inline-block;
+    padding-right: 20px;
+    position: relative;
+    z-index: 2;
+}
+
+#releases-selector-after {
+    padding: 0 4px;
+    margin-left: -20px;
+    position: relative;
+    z-index: 1;
+}
+
+.md-selector select:focus {
+    outline: none;
+}
+
@media only screen and (min-width: 60em) {
    #md-sidebar-flags {
        display: none;
--- a/docs/tools/mkdocs-material-theme/base.html
+++ b/docs/tools/mkdocs-material-theme/base.html
@ -256,6 +256,17 @@
            feedback_email[i].setAttribute('href', 'mailto:' + feedback_address);
            feedback_email[i].innerHTML = feedback_address;
          }
+
+          document.getElementById("releases-selector").addEventListener(
+            "change",
+            function() {
+              var target = window.location.href.split('docs')[0] + 'docs/';
+              if (this.value) {
+                target = target + this.value + '/';
+              }
+              window.location = target + '{{ config.theme.language }}';
+            }
+          )
      });
    </script>
    <!-- Yandex.Metrika counter -->
--- a/docs/tools/mkdocs-material-theme/partials/flags.html
+++ b/docs/tools/mkdocs-material-theme/partials/flags.html
@ -6,4 +6,3 @@
    {% include "assets/flags/" + alt_lang + ".svg" %}
  </a>
 {% endfor %}
-
--- a/docs/tools/mkdocs-material-theme/partials/language/en.html
+++ b/docs/tools/mkdocs-material-theme/partials/language/en.html
@ -7,8 +7,10 @@
  "footer.next": "Next",
  "meta.comments": "Comments",
  "meta.source": "Source",
+  "nav.latest": "latest",
  "nav.multi_page": "Multi page version",
  "nav.pdf": "PDF version",
+  "nav.release": "Release",
  "nav.single_page": "Single page version",
  "nav.source": "ClickHouse source code",
  "search.placeholder": "Search",
--- a/docs/tools/mkdocs-material-theme/partials/language/fa.html
+++ b/docs/tools/mkdocs-material-theme/partials/language/fa.html
@ -8,8 +8,10 @@
  "footer.next": "بعدی",
  "meta.comments": "نظرات",
  "meta.source": "منبع",
+  "nav.latest": "آخرین",
  "nav.multi_page": "نسخه چند صفحه ای",
  "nav.pdf": "نسخه PDF",
+  "nav.release": "رهایی",
  "nav.single_page": "نسخه تک صفحه",
  "nav.source": "کد منبع کلیک",
  "search.language": "",
--- a/docs/tools/mkdocs-material-theme/partials/language/ru.html
+++ b/docs/tools/mkdocs-material-theme/partials/language/ru.html
@ -7,8 +7,10 @@
  "footer.next": "Вперед",
  "meta.comments": "Комментарии",
  "meta.source": "Исходный код",
+  "nav.latest": "последний",
  "nav.multi_page": "Многостраничная версия",
  "nav.pdf": "PDF версия",
+  "nav.release": "Релиз",
  "nav.single_page": "Одностраничная версия",
  "nav.source": "Исходный код ClickHouse",
  "search.placeholder": "Поиск",
--- a/docs/tools/mkdocs-material-theme/partials/language/zh.html
+++ b/docs/tools/mkdocs-material-theme/partials/language/zh.html
@ -7,8 +7,10 @@
  "footer.next": "前进",
  "meta.comments": "评论",
  "meta.source": "来源",
+  "nav.latest": "最新",
  "nav.multi_page": "多页版本",
  "nav.pdf": "PDF版本",
+  "nav.release": "发布",
  "nav.single_page": "单页版本",
  "nav.source": "ClickHouse源代码",
  "search.placeholder": "搜索",
--- a/docs/tools/mkdocs-material-theme/partials/nav.html
+++ b/docs/tools/mkdocs-material-theme/partials/nav.html
@ -14,6 +14,21 @@
  {% endif %}

  <ul id="md-extra-nav" class="md-nav__list" data-md-scrollfix>
+    <li class="md-nav__item md-nav__item--active">
+      {{ lang.t("nav.release") }}:
+      <span class="md-selector">
+        <select id="releases-selector">
+          <option value="">{{ lang.t("nav.latest") }}</option>
+          {% for release in config.extra.stable_releases %}
+            <option value="{{ release.0 }}"
+              {% if release.0 == config.extra.version_prefix %}
+                selected="selected"
+              {% endif %}
+            >{{ release.0 }}</option>
+          {% endfor %}
+        </select><span id="releases-selector-after">&nbsp;▾</span>
+      </span>
+    </li>
    <li class="md-nav__item md-nav__item--active">
        {% if config.extra.single_page %}
          <a href="{{ base_url }}" class="md-nav__link md-nav__link--active">{{ lang.t("nav.multi_page") }}</a>
--- a/docs/tools/release.sh
+++ b/docs/tools/release.sh
@ -15,7 +15,7 @@ DOCKER_HASH="$2"
 if [[ -z "$1" ]]
 then
    source "${BASE_DIR}/venv/bin/activate"
-    python "${BASE_DIR}/build.py"
+    python "${BASE_DIR}/build.py" "--enable-stable-releases"
    cd "${BUILD_DIR}"
    docker build -t "${FULL_NAME}" "${BUILD_DIR}"
    docker tag "${FULL_NAME}" "${REMOTE_NAME}"
--- a/docs/tools/util.py
+++ b/docs/tools/util.py
@ -0,0 +1,22 @@
+import contextlib
+import os
+import shutil
+import tempfile
+
+
+@contextlib.contextmanager
+def temp_dir():
+    path = tempfile.mkdtemp(dir=os.environ.get('TEMP'))
+    try:
+        yield path
+    finally:
+        shutil.rmtree(path)
+
+
+@contextlib.contextmanager
+def autoremoved_file(path):
+    try:
+        with open(path, 'w') as handle:
+            yield handle
+    finally:
+        os.unlink(path)
--- a/docs/zh/operations/table_engines/join.md
+++ b/docs/zh/operations/table_engines/join.md
@ -1,19 +1,19 @@
 # Join

-A prepared data structure for JOIN that is always located in RAM.
+加载好的 JOIN 表数据会常驻内存中。

 ```
 Join(ANY|ALL, LEFT|INNER, k1[, k2, ...])
 ```

-Engine parameters: `ANY|ALL` – strictness; `LEFT|INNER` – type.
-These parameters are set without quotes and must match the JOIN that the table will be used for. k1, k2, ... are the key columns from the USING clause that the join will be made on.
+引擎参数：`ANY|ALL` – 连接修饰；`LEFT|INNER` – 连接类型。更多信息可参考 [JOIN子句](../../query_language/select.md#select-join)。
+这些参数设置不用带引号，但必须与要 JOIN 表匹配。 k1，k2，……是 USING 子句中要用于连接的关键列。

-The table can't be used for GLOBAL JOINs.
+此引擎表不能用于 GLOBAL JOIN 。

-You can use INSERT to add data to the table, similar to the Set engine. For ANY, data for duplicated keys will be ignored. For ALL, it will be counted. You can't perform SELECT directly from the table. The only way to retrieve data is to use it as the "right-hand" table for JOIN.
+类似于 Set 引擎，可以使用 INSERT 向表中添加数据。设置为 ANY 时，重复键的数据会被忽略（仅一条用于连接）。设置为 ALL 时，重复键的数据都会用于连接。不能直接对 JOIN 表进行 SELECT。检索其数据的唯一方法是将其作为 JOIN 语句右边的表。

-Storing data on the disk is the same as for the Set engine.
+跟 Set 引擎类似，Join 引擎把数据存储在磁盘中。


-[Original article](https://clickhouse.yandex/docs/en/operations/table_engines/join/) <!--hide-->
+[来源文章](https://clickhouse.yandex/docs/en/operations/table_engines/join/) <!--hide-->
--- a/website/index.html
+++ b/website/index.html
@ -92,11 +92,6 @@
        <div class="clear"></div>
    </div>
 </div>
-<div id="announcement" class="colored-block">
-    <div class="page">
-        Upcoming ClickHouse Community Meetups: <a class="announcement-link" href="https://www.eventbrite.com/e/clickhouse-meetup-in-madrid-registration-55376746339" rel="external nofollow" target="_blank">Madrid</a> on April 2
-    </div>
-</div>
 <div class="page">
    <h2 id="slogan">ClickHouse. Just makes you think faster.</h2>