Merge pull request #18153 from sevirov/sevirov-DOCSUP-4617-document_union_default_mode_setting

DOCSUP-4617: Document the union_default_mode setting

docs/en/operations/settings/settings.md

@@ -2470,6 +2470,20 @@ Possible values:
 
 Default value: `0`.
 
+## union_default_mode {#union-default-mode}
+
+Sets a mode for combining `SELECT` query results. The setting is only used when shared with [UNION](../../sql-reference/statements/select/union.md) without explicitly specifying the `UNION ALL` or `UNION DISTINCT`.
+
+Possible values:
+
+-   `'DISTINCT'` — ClickHouse outputs rows as a result of combining queries removing duplicate rows.
+-   `'ALL'` — ClickHouse outputs all rows as a result of combining queries including duplicate rows.
+-   `''` — Clickhouse generates an exception when used with `UNION`.
+
+Default value: `''`.
+
+See examples in [UNION](../../sql-reference/statements/select/union.md).
+
 ## data_type_default_nullable {#data_type_default_nullable}
 
 Allows data types without explicit modifiers [NULL or NOT NULL](../../sql-reference/statements/create/table.md#null-modifiers) in column definition will be [Nullable](../../sql-reference/data-types/nullable.md#data_type-nullable).

docs/en/sql-reference/statements/select/index.md

@@ -46,7 +46,7 @@ Specifics of each optional clause are covered in separate sections, which are li
 -   [SELECT clause](#select-clause)
 -   [DISTINCT clause](../../../sql-reference/statements/select/distinct.md)
 -   [LIMIT clause](../../../sql-reference/statements/select/limit.md)
--   [UNION clause](../../../sql-reference/statements/select/union-all.md)
+-   [UNION clause](../../../sql-reference/statements/select/union.md)
 -   [INTO OUTFILE clause](../../../sql-reference/statements/select/into-outfile.md)
 -   [FORMAT clause](../../../sql-reference/statements/select/format.md)
 

docs/en/sql-reference/statements/select/union-all.md

@@ -1,37 +0,0 @@
----
-toc_title: UNION
----
-
-# UNION ALL Clause {#union-all-clause}
-
-You can use `UNION ALL` to combine any number of `SELECT` queries by extending their results. Example:
-
-``` sql
-SELECT CounterID, 1 AS table, toInt64(count()) AS c
-    FROM test.hits
-    GROUP BY CounterID
-
-UNION ALL
-
-SELECT CounterID, 2 AS table, sum(Sign) AS c
-    FROM test.visits
-    GROUP BY CounterID
-    HAVING c > 0
-```
-
-Result columns are matched by their index (order inside `SELECT`). If column names do not match, names for the final result are taken from the first query.
-
-Type casting is performed for unions. For example, if two queries being combined have the same field with non-`Nullable` and `Nullable` types from a compatible type, the resulting `UNION ALL` has a `Nullable` type field.
-
-Queries that are parts of `UNION ALL` can’t be enclosed in round brackets. [ORDER BY](../../../sql-reference/statements/select/order-by.md) and [LIMIT](../../../sql-reference/statements/select/limit.md) are applied to separate queries, not to the final result. If you need to apply a conversion to the final result, you can put all the queries with `UNION ALL` in a subquery in the [FROM](../../../sql-reference/statements/select/from.md) clause.
-
-# UNION DISTINCT Clause {#union-distinct-clause}
-The difference between `UNION ALL` and `UNION DISTINCT` is that `UNION DISTINCT` will do a distinct transform for union result, it is equivalent to `SELECT DISTINCT` from a subquery containing `UNION ALL`.
-
-# UNION Clause {#union-clause}
-By default, `UNION` has the same behavior as `UNION DISTINCT`, but you can specify union mode by setting `union_default_mode`, values can be 'ALL', 'DISTINCT' or empty string. However, if you use `UNION` with setting `union_default_mode` to empty string, it will throw an exception.
-
-
-## Implementation Details {#implementation-details}
-
-Queries that are parts of `UNION/UNION ALL/UNION DISTINCT` can be run simultaneously, and their results can be mixed together.

docs/en/sql-reference/statements/select/union.md

@@ -0,0 +1,81 @@
+---
+toc_title: UNION
+---
+
+# UNION Clause {#union-clause}
+
+You can use `UNION` with explicitly specifying `UNION ALL` or `UNION DISTINCT`.
+
+If you don't specify `ALL` or `DISTINCT`, it will depend on the `union_default_mode` setting. The difference between `UNION ALL` and `UNION DISTINCT` is that `UNION DISTINCT` will do a distinct transform for union result, it is equivalent to `SELECT DISTINCT` from a subquery containing `UNION ALL`.
+
+You can use `UNION` to combine any number of `SELECT` queries by extending their results. Example:
+
+``` sql
+SELECT CounterID, 1 AS table, toInt64(count()) AS c
+    FROM test.hits
+    GROUP BY CounterID
+
+UNION ALL
+
+SELECT CounterID, 2 AS table, sum(Sign) AS c
+    FROM test.visits
+    GROUP BY CounterID
+    HAVING c > 0
+```
+
+Result columns are matched by their index (order inside `SELECT`). If column names do not match, names for the final result are taken from the first query.
+
+Type casting is performed for unions. For example, if two queries being combined have the same field with non-`Nullable` and `Nullable` types from a compatible type, the resulting `UNION` has a `Nullable` type field.
+
+Queries that are parts of `UNION` can be enclosed in round brackets. [ORDER BY](../../../sql-reference/statements/select/order-by.md) and [LIMIT](../../../sql-reference/statements/select/limit.md) are applied to separate queries, not to the final result. If you need to apply a conversion to the final result, you can put all the queries with `UNION` in a subquery in the [FROM](../../../sql-reference/statements/select/from.md) clause.
+
+If you use `UNION` without explicitly specifying `UNION ALL` or `UNION DISTINCT`, you can specify the union mode using the [union_default_mode](../../../operations/settings/settings.md#union-default-mode) setting. The setting values can be `ALL`, `DISTINCT` or an empty string. However, if you use `UNION` with `union_default_mode` setting to empty string, it will throw an exception. The following examples demonstrate the results of queries with different values setting.
+
+Query:
+
+```sql
+SET union_default_mode = 'DISTINCT';
+SELECT 1 UNION SELECT 2 UNION SELECT 3 UNION SELECT 2;
+```
+
+Result:
+
+```text
+┌─1─┐
+│ 1 │
+└───┘
+┌─1─┐
+│ 2 │
+└───┘
+┌─1─┐
+│ 3 │
+└───┘
+```
+
+Query:
+
+```sql
+SET union_default_mode = 'ALL';
+SELECT 1 UNION SELECT 2 UNION SELECT 3 UNION SELECT 2;
+```
+
+Result:
+
+```text
+┌─1─┐
+│ 1 │
+└───┘
+┌─1─┐
+│ 2 │
+└───┘
+┌─1─┐
+│ 2 │
+└───┘
+┌─1─┐
+│ 3 │
+└───┘
+```
+
+Queries that are parts of `UNION/UNION ALL/UNION DISTINCT` can be run simultaneously, and their results can be mixed together.
+
+[Original article](https://clickhouse.tech/docs/en/sql-reference/statements/select/union/) <!-- hide -->

docs/es/sql-reference/statements/select/index.md

@@ -44,7 +44,7 @@ Los detalles de cada cláusula opcional se cubren en secciones separadas, que se
 -   [Cláusula HAVING](having.md)
 -   [Cláusula SELECT](#select-clause)
 -   [Cláusula LIMIT](limit.md)
--   [UNION ALL cláusula](union-all.md)
+-   [UNION ALL cláusula](union.md)
 
 ## SELECT Cláusula {#select-clause}
 

docs/es/sql-reference/statements/select/union.md

@@ -3,7 +3,7 @@ machine_translated: true
 machine_translated_rev: 72537a2d527c63c07aa5d2361a8829f3895cf2bd
 ---
 
-# UNION ALL Cláusula {#union-all-clause}
+# UNION Cláusula {#union-clause}
 
 Usted puede utilizar `UNION ALL` combinar cualquier número de `SELECT` consultas extendiendo sus resultados. Ejemplo:
 

docs/fa/sql-reference/statements/select/index.md

@@ -44,7 +44,7 @@ SELECT [DISTINCT] expr_list
 -   [داشتن بند](having.md)
 -   [انتخاب بند](#select-clause)
 -   [بند محدود](limit.md)
--   [اتحادیه همه بند](union-all.md)
+-   [اتحادیه همه بند](union.md)
 
 ## انتخاب بند {#select-clause}
 

docs/fa/sql-reference/statements/select/union.md

@@ -3,7 +3,7 @@ machine_translated: true
 machine_translated_rev: 72537a2d527c63c07aa5d2361a8829f3895cf2bd
 ---
 
-# اتحادیه همه بند {#union-all-clause}
+# اتحادیه همه بند {#union-clause}
 
 شما می توانید استفاده کنید `UNION ALL` برای ترکیب هر تعداد از `SELECT` نمایش داده شد با گسترش نتایج خود را. مثال:
 

docs/fr/sql-reference/statements/select/index.md

@@ -44,7 +44,7 @@ Spécificités de chaque clause facultative, sont couverts dans des sections dis
 -   [Clause HAVING](having.md)
 -   [Clause SELECT](#select-clause)
 -   [Clause LIMIT](limit.md)
--   [Clause UNION ALL](union-all.md)
+-   [Clause UNION ALL](union.md)
 
 ## Clause SELECT {#select-clause}
 

docs/fr/sql-reference/statements/select/union.md

@@ -3,7 +3,7 @@ machine_translated: true
 machine_translated_rev: 72537a2d527c63c07aa5d2361a8829f3895cf2bd
 ---
 
-# Clause UNION ALL {#union-all-clause}
+# Clause UNION ALL {#union-clause}
 
 Vous pouvez utiliser `UNION ALL` à combiner `SELECT` requêtes en étendant leurs résultats. Exemple:
 

docs/ja/sql-reference/statements/select/union-all.md

@@ -1 +0,0 @@
-../../../../en/sql-reference/statements/select/union-all.md

docs/ja/sql-reference/statements/select/union.md

@@ -0,0 +1 @@
+../../../../en/sql-reference/statements/select/union.md

docs/ru/operations/settings/settings.md

@@ -2324,6 +2324,20 @@ SELECT number FROM numbers(3) FORMAT JSONEachRow;
 
 Значение по умолчанию: `0`.
 
+## union_default_mode {#union-default-mode}
+
+Устанавливает режим объединения результатов `SELECT` запросов. Настройка используется только при совместном использовании с [UNION](../../sql-reference/statements/select/union.md) без явного указания `UNION ALL` или `UNION DISTINCT`.
+
+Возможные значения:
+
+-   `'DISTINCT'` — ClickHouse выводит строки в результате объединения результатов запросов, удаляя повторяющиеся строки.
+-   `'ALL'` — ClickHouse выводит все строки в результате объединения результатов запросов, включая повторяющиеся строки.
+-   `''` — Clickhouse генерирует исключение при использовании с `UNION`.
+
+Значение по умолчанию: `''`.
+
+Смотрите примеры в разделе [UNION](../../sql-reference/statements/select/union.md).
+
 ## execute_merges_on_single_replica_time_threshold {#execute-merges-on-single-replica-time-threshold}
 
 Включает особую логику выполнения слияний на репликах.

docs/ru/sql-reference/statements/select/index.md

@@ -44,7 +44,7 @@ SELECT [DISTINCT] expr_list
 -   [Секция SELECT](#select-clause)
 -   [Секция DISTINCT](distinct.md)
 -   [Секция LIMIT](limit.md)
--   [Секция UNION ALL](union-all.md)
+-   [Секция UNION ALL](union.md)
 -   [Секция INTO OUTFILE](into-outfile.md)
 -   [Секция FORMAT](format.md)
 

docs/ru/sql-reference/statements/select/union-all.md

@@ -1,34 +0,0 @@
----
-toc_title: UNION ALL
----
-
-# Секция UNION ALL {#union-all-clause}
-
-Вы можете использовать `UNION ALL` чтобы объединить любое количество `SELECT` запросы путем расширения их результатов. Пример:
-
-``` sql
-SELECT CounterID, 1 AS table, toInt64(count()) AS c
-    FROM test.hits
-    GROUP BY CounterID
-
-UNION ALL
-
-SELECT CounterID, 2 AS table, sum(Sign) AS c
-    FROM test.visits
-    GROUP BY CounterID
-    HAVING c > 0
-```
-
-Результирующие столбцы сопоставляются по их индексу (порядку внутри `SELECT`). Если имена столбцов не совпадают, то имена для конечного результата берутся из первого запроса.
-
-При объединении выполняет приведение типов. Например, если два запроса имеют одно и то же поле с не-`Nullable` и `Nullable` совместимыми типами, полученные в результате `UNION ALL` данные будут иметь `Nullable` тип.
-
-Запросы, которые являются частью `UNION ALL` не могут быть заключен в круглые скобки. [ORDER BY](order-by.md) и [LIMIT](limit.md) применяются к отдельным запросам, а не к конечному результату. Если вам нужно применить преобразование к конечному результату, вы можете разместить все объединенные с помощью `UNION ALL` запросы в подзапрос в секции [FROM](from.md).
-
-## Ограничения {#limitations}
-
-Поддерживается только `UNION ALL`. Обычный `UNION` (`UNION DISTINCT`) не поддерживается. Если вам это нужно `UNION DISTINCT`, вы можете написать `SELECT DISTINCT` из подзапроса, содержащего `UNION ALL`.
-
-## Детали реализации {#implementation-details}
-
-Запросы, которые являются частью `UNION ALL` выполняются параллельно, и их результаты могут быть смешаны вместе.

docs/ru/sql-reference/statements/select/union.md

@@ -0,0 +1,81 @@
+---
+toc_title: UNION
+---
+
+# Секция UNION {#union-clause}
+
+Вы можете использовать `UNION` в двух режимах: `UNION ALL` или `UNION DISTINCT`.
+
+Если `UNION` используется без указания `ALL` или `DISTINCT`, то его поведение определяется настройкой `union_default_mode`. Разница между `UNION ALL` и `UNION DISTINCT` в том, что `UNION DISTINCT` выполняет явное преобразование для результата объединения. Это равнозначно выражению `SELECT DISTINCT` из подзапроса, содержащего `UNION ALL`.
+
+Чтобы объединить любое количество `SELECT` запросов путем объединения их результатов, вы можете использовать `UNION`. Пример:
+
+``` sql
+SELECT CounterID, 1 AS table, toInt64(count()) AS c
+    FROM test.hits
+    GROUP BY CounterID
+
+UNION ALL
+
+SELECT CounterID, 2 AS table, sum(Sign) AS c
+    FROM test.visits
+    GROUP BY CounterID
+    HAVING c > 0
+```
+
+Результирующие столбцы сопоставляются по их индексу (порядку внутри `SELECT`). Если имена столбцов не совпадают, то имена для конечного результата берутся из первого запроса.
+
+При объединении выполняет приведение типов. Например, если два запроса имеют одно и то же поле с не-`Nullable` и `Nullable` совместимыми типами, полученные в результате `UNION` данные будут иметь `Nullable` тип.
+
+Запросы, которые являются частью `UNION`, могут быть заключены в круглые скобки. [ORDER BY](order-by.md) и [LIMIT](limit.md) применяются к отдельным запросам, а не к конечному результату. Если вам нужно применить преобразование к конечному результату, вы можете разместить все объединенные с помощью `UNION` запросы в подзапрос в секции [FROM](from.md).
+
+Если используете `UNION` без явного указания `UNION ALL` или `UNION DISTINCT`, то вы можете указать режим объединения с помощью настройки [union_default_mode](../../../operations/settings/settings.md#union-default-mode), значениями которой могут быть `ALL`, `DISTINCT` или пустая строка. Однако если вы используете `UNION` с настройкой `union_default_mode`, значением которой является пустая строка, то будет сгенерировано исключение. В следующих примерах продемонстрированы результаты запросов при разных значениях настройки.
+
+Запрос:
+
+```sql
+SET union_default_mode = 'DISTINCT';
+SELECT 1 UNION SELECT 2 UNION SELECT 3 UNION SELECT 2;
+```
+
+Результат:
+
+```text
+┌─1─┐
+│ 1 │
+└───┘
+┌─1─┐
+│ 2 │
+└───┘
+┌─1─┐
+│ 3 │
+└───┘
+```
+
+Запрос:
+
+```sql
+SET union_default_mode = 'ALL';
+SELECT 1 UNION SELECT 2 UNION SELECT 3 UNION SELECT 2;
+```
+
+Результат:
+
+```text
+┌─1─┐
+│ 1 │
+└───┘
+┌─1─┐
+│ 2 │
+└───┘
+┌─1─┐
+│ 2 │
+└───┘
+┌─1─┐
+│ 3 │
+└───┘
+```
+
+Запросы, которые являются частью `UNION/UNION ALL/UNION DISTINCT`, выполняются параллельно, и их результаты могут быть смешаны вместе.
+
+[Оригинальная статья](https://clickhouse.tech/docs/ru/sql-reference/statements/select/union/) <!-- hide -->

docs/tr/sql-reference/statements/select/union-all.md

@@ -1 +0,0 @@
-../../../../en/sql-reference/statements/select/union-all.md

docs/tr/sql-reference/statements/select/union.md

@@ -0,0 +1 @@
+../../../../en/sql-reference/statements/select/union.md

docs/zh/sql-reference/statements/select/index.md

@@ -46,7 +46,7 @@ SELECT [DISTINCT] expr_list
 -   [SELECT 子句](#select-clause)
 -   [DISTINCT 子句](../../../sql-reference/statements/select/distinct.md)
 -   [LIMIT 子句](../../../sql-reference/statements/select/limit.md)
--   [UNION ALL 子句](../../../sql-reference/statements/select/union-all.md)
+-   [UNION ALL 子句](../../../sql-reference/statements/select/union.md)
 -   [INTO OUTFILE 子句](../../../sql-reference/statements/select/into-outfile.md)
 -   [FORMAT 子句](../../../sql-reference/statements/select/format.md)
 

docs/zh/sql-reference/statements/select/union.md

@@ -2,7 +2,7 @@
 toc_title: UNION ALL
 ---
 
-# UNION ALL子句 {#union-all-clause}
+# UNION ALL子句 {#union-clause}
 
 你可以使用 `UNION ALL` 结合任意数量的 `SELECT` 来扩展其结果。 示例: