Merge pull request #27725 from olgarev/revolg-DOCSUP-12894-projections_translated

DOCSUP-12894: Projections settings

docs/en/engines/table-engines/mergetree-family/mergetree.md

@@ -390,20 +390,27 @@ Functions with a constant argument that is less than ngram size can’t be used
     -   `s != 1`
     -   `NOT startsWith(s, 'test')`
 
-### Projections {#projections}
-Projections are like materialized views but defined in part-level. It provides consistency guarantees along with automatic usage in queries.
+## Projections {#projections}
+Projections are like [materialized views](../../../sql-reference/statements/create/view.md#materialized) but defined in part-level. It provides consistency guarantees along with automatic usage in queries.
 
-#### Query {#projection-query}
-A projection query is what defines a projection. It has the following grammar:
+Projections are an experimental feature. To enable them you must set the [allow_experimental_projection_optimization](../../../operations/settings/settings.md#allow-experimental-projection-optimization) to `1`. See also the [force_optimize_projection](../../../operations/settings/settings.md#force-optimize-projection) setting.
 
-`SELECT <COLUMN LIST EXPR> [GROUP BY] [ORDER BY]`
+Projections are not supported in the `SELECT` statements with the [FINAL](../../../sql-reference/statements/select/from.md#select-from-final) modifier.
 
-It implicitly selects data from the parent table.
+### Projection Query {#projection-query}
+A projection query is what defines a projection. It implicitly selects data from the parent table. 
+**Syntax**
 
-#### Storage {#projection-storage}
-Projections are stored inside the part directory. It's similar to an index but contains a subdirectory that stores an anonymous MergeTree table's part. The table is induced by the definition query of the projection. If there is a GROUP BY clause, the underlying storage engine becomes AggregatedMergeTree, and all aggregate functions are converted to AggregateFunction. If there is an ORDER BY clause, the MergeTree table will use it as its primary key expression. During the merge process, the projection part will be merged via its storage's merge routine. The checksum of the parent table's part will combine the projection's part. Other maintenance jobs are similar to skip indices.
+```sql
+SELECT <column list expr> [GROUP BY] <group keys expr> [ORDER BY] <expr>
+```
 
-#### Query Analysis {#projection-query-analysis}
+Projections can be modified or dropped with the [ALTER](../../../sql-reference/statements/alter/projection.md) statement.
+
+### Projection Storage {#projection-storage}
+Projections are stored inside the part directory. It's similar to an index but contains a subdirectory that stores an anonymous `MergeTree` table's part. The table is induced by the definition query of the projection. If there is a `GROUP BY` clause, the underlying storage engine becomes [AggregatingMergeTree](aggregatingmergetree.md), and all aggregate functions are converted to `AggregateFunction`. If there is an `ORDER BY` clause, the `MergeTree` table uses it as its primary key expression. During the merge process the projection part is merged via its storage's merge routine. The checksum of the parent table's part is combined with the projection's part. Other maintenance jobs are similar to skip indices.
+
+### Query Analysis {#projection-query-analysis}
 1. Check if the projection can be used to answer the given query, that is, it generates the same answer as querying the base table.
 2. Select the best feasible match, which contains the least granules to read.
 3. The query pipeline which uses projections will be different from the one that uses the original parts. If the projection is absent in some parts, we can add the pipeline to "project" it on the fly.

docs/en/operations/settings/settings.md

@@ -3435,3 +3435,25 @@ Possible values:
 -   1 — The table is automatically updated in the background, when schema changes are detected.
 
 Default value: `0`.
+
+## allow_experimental_projection_optimization {#allow-experimental-projection-optimization}
+
+Enables or disables [projection](../../engines/table-engines/mergetree-family/mergetree.md#projections) optimization when processing `SELECT` queries.
+
+Possible values:
+
+-   0 — Projection optimization disabled.
+-   1 — Projection optimization enabled.
+
+Default value: `0`.
+
+## force_optimize_projection {#force-optimize-projection}
+
+Enables or disables the obligatory use of [projections](../../engines/table-engines/mergetree-family/mergetree.md#projections) in `SELECT` queries, when projection optimization is enabled (see [allow_experimental_projection_optimization](#allow-experimental-projection-optimization) setting). 
+
+Possible values:
+
+-   0 — Projection optimization is not obligatory.
+-   1 — Projection optimization is obligatory.
+
+Default value: `0`.

docs/en/sql-reference/statements/alter/projection.md

@@ -5,7 +5,7 @@ toc_title: PROJECTION
 
 # Manipulating Projections {#manipulations-with-projections}
 
-The following operations are available:
+The following operations with [projections](../../../engines/table-engines/mergetree-family/mergetree.md#projections) are available:
 
 -   `ALTER TABLE [db].name ADD PROJECTION name AS SELECT <COLUMN LIST EXPR> [GROUP BY] [ORDER BY]` - Adds projection description to tables metadata.
 
@@ -15,7 +15,7 @@ The following operations are available:
 
 -   `ALTER TABLE [db.]table CLEAR PROJECTION name IN PARTITION partition_name` - Deletes projection files from disk without removing description.
 
-The commands ADD, DROP and CLEAR are lightweight in a sense that they only change metadata or remove files.
+The commands `ADD`, `DROP` and `CLEAR` are lightweight in a sense that they only change metadata or remove files.
 
 Also, they are replicated, syncing projections metadata via ZooKeeper.
 

docs/ru/engines/table-engines/mergetree-family/mergetree.md

@@ -377,23 +377,33 @@ INDEX b (u64 * length(str), i32 + f64 * 100, date, str) TYPE set(100) GRANULARIT
     -   `s != 1`
     -   `NOT startsWith(s, 'test')`
 
-### Проекции {#projections}
-Проекции похожи на материализованные представления, но определяются на уровне партов. Это обеспечивает гарантии согласованности наряду с автоматическим использованием в запросах.
+## Проекции {#projections}
+Проекции похожи на [материализованные представления](../../../sql-reference/statements/create/view.md#materialized), но определяются на уровне кусков данных. Это обеспечивает гарантии согласованности данных наряду с автоматическим использованием в запросах.
 
-#### Запрос {#projection-query}
-Запрос проекции — это то, что определяет проекцию. Он имеет следующую грамматику:
+Проекции — это экспериментальная возможность. Чтобы включить поддержку проекций, установите настройку [allow_experimental_projection_optimization](../../../operations/settings/settings.md#allow-experimental-projection-optimization) в значение `1`. См. также настройку [force_optimize_projection ](../../../operations/settings/settings.md#force-optimize-projection).
 
-`SELECT <COLUMN LIST EXPR> [GROUP BY] [ORDER BY]`
+Проекции не поддерживаются для запросов `SELECT` с модификатором [FINAL](../../../sql-reference/statements/select/from.md#select-from-final).
 
-Он неявно выбирает данные из родительской таблицы.
+### Запрос проекции {#projection-query}
+Запрос проекции — это то, что определяет проекцию. Такой запрос неявно выбирает данные из родительской таблицы. 
+**Синтаксис**
 
-#### Хранение {#projection-storage}
-Проекции хранятся в каталоге парта. Это похоже на хранение индексов, но используется подкаталог, в котором хранится анонимный парт таблицы MergeTree. Таблица создается запросом определения проекции. Если есть конструкция GROUP BY, то базовый механизм хранения становится AggregatedMergeTree, а все агрегатные функции преобразуются в AggregateFunction. Если есть конструкция ORDER BY, таблица MergeTree будет использовать его в качестве выражения первичного ключа. Во время процесса слияния парт проекции будет слит с помощью процедуры слияния ее хранилища. Контрольная сумма парта родительской таблицы будет включать парт проекции. Другие процедуры аналогичны индексам пропуска данных.
+```sql
+SELECT <column list expr> [GROUP BY] <group keys expr> [ORDER BY] <expr>
+```
 
-#### Анализ запросов {#projection-query-analysis}
-1. Проверить, можно ли использовать проекцию в данном запросе, то есть, что с ней выходит тот же результат, что и с запросом к базовой таблице.
-2. Выбрать наиболее подходящее совпадение, содержащее наименьшее количество гранул для чтения.
-3. План запроса, который использует проекции, будет отличаться от того, который использует исходные парты. При отсутствии проекции в некоторых партах можно расширить план, чтобы «проецировать» на лету.
+Проекции можно изменить или удалить с помощью запроса [ALTER](../../../sql-reference/statements/alter/projection.md).
+
+### Хранение проекции {#projection-storage}
+Проекции хранятся в каталоге куска данных. Это похоже на хранение индексов, но используется подкаталог, в котором хранится анонимный кусок таблицы `MergeTree`. Таблица создается запросом определения проекции. 
+Если присутствует секция `GROUP BY`, то используется движок [AggregatingMergeTree](aggregatingmergetree.md), а все агрегатные функции преобразуются в `AggregateFunction`. 
+Если присутствует секция `ORDER BY`, таблица `MergeTree` использует ее в качестве выражения для первичного ключа. 
+Во время процесса слияния кусок данных проекции объединяется с помощью процедуры слияния хранилища. Контрольная сумма куска данных родительской таблицы включает кусок данных проекции. Другие процедуры аналогичны индексам пропуска данных.
+
+### Анализ запросов {#projection-query-analysis}
+1. Проверьте, можно ли использовать проекцию в данном запросе, то есть, что с ней получается тот же результат, что и с запросом к базовой таблице.
+2. Выберите наиболее подходящее совпадение, содержащее наименьшее количество гранул для чтения.
+3. План запроса, который использует проекции, отличается от того, который использует исходные куски данных. Если в некоторых кусках проекции отсутствуют, можно расширить план, чтобы «проецировать» на лету.
 
 ## Конкурентный доступ к данным {#concurrent-data-access}
 

docs/ru/operations/settings/settings.md

@@ -3252,3 +3252,25 @@ SETTINGS index_granularity = 8192 │
 -   1 — таблица обновляется автоматически в фоновом режиме при обнаружении изменений схемы.
 
 Значение по умолчанию: `0`.
+
+## allow_experimental_projection_optimization {#allow-experimental-projection-optimization}
+
+Включает или отключает поддержку [проекций](../../engines/table-engines/mergetree-family/mergetree.md#projections) при обработке запросов `SELECT`.
+
+Возможные значения:
+
+-   0 — Проекции не поддерживаются.
+-   1 — Проекции поддерживаются.
+
+Значение по умолчанию: `0`.
+
+## force_optimize_projection {#force-optimize-projection}
+
+Включает или отключает обязательное использование [проекций](../../engines/table-engines/mergetree-family/mergetree.md#projections) в запросах `SELECT`, если поддержка проекций включена (см. настройку [allow_experimental_projection_optimization](#allow-experimental-projection-optimization)). 
+
+Возможные значения:
+
+-   0 — Проекции используются опционально.
+-   1 — Проекции обязательно используются.
+
+Значение по умолчанию: `0`.

docs/ru/sql-reference/statements/alter/projection.md

@@ -5,7 +5,7 @@ toc_title: PROJECTION
 
 # Манипуляции с проекциями {#manipulations-with-projections}
 
-Доступны следующие операции:
+Доступны следующие операции с [проекциями](../../../engines/table-engines/mergetree-family/mergetree.md#projections):
 
 -   `ALTER TABLE [db].name ADD PROJECTION name AS SELECT <COLUMN LIST EXPR> [GROUP BY] [ORDER BY]` — добавляет описание проекции в метаданные.
 
@@ -15,7 +15,7 @@ toc_title: PROJECTION
 
 -   `ALTER TABLE [db.]table CLEAR PROJECTION name IN PARTITION partition_name` — удаляет файлы проекции с диска без удаления описания.
 
-Комманды ADD, DROP и CLEAR — легковесны, поскольку они только меняют метаданные или удаляют файлы.
+Команды `ADD`, `DROP` и `CLEAR` — легковесны, поскольку они только меняют метаданные или удаляют файлы.
 
 Также команды реплицируются, синхронизируя описания проекций в метаданных с помощью ZooKeeper.