Merge pull request #14772 from otrazhenia/evgsudarikova-DOCSUP-2039

DOCS-323: LowCardinality

docs/en/operations/settings/settings.md

@@ -1817,7 +1817,7 @@ Default value: 8192.
 
 Turns on or turns off using of single dictionary for the data part.
 
-By default, ClickHouse server monitors the size of dictionaries and if a dictionary overflows then the server starts to write the next one. To prohibit creating several dictionaries set `low_cardinality_use_single_dictionary_for_part = 1`.
+By default, the ClickHouse server monitors the size of dictionaries and if a dictionary overflows then the server starts to write the next one. To prohibit creating several dictionaries set `low_cardinality_use_single_dictionary_for_part = 1`.
 
 Possible values:
 

docs/en/sql-reference/data-types/lowcardinality.md

@@ -21,7 +21,7 @@ LowCardinality(data_type)
 
 `LowCardinality` is a superstructure that changes a data storage method and rules of data processing. ClickHouse applies [dictionary coding](https://en.wikipedia.org/wiki/Dictionary_coder) to `LowCardinality`-columns. Operating with dictionary encoded data significantly increases performance of [SELECT](../../sql-reference/statements/select/index.md) queries for many applications.
 
-The efficiency of using `LowCarditality` data type depends on data diversity. If a dictionary contains less than 10,000 distinct values, then ClickHouse mostly shows higher efficiency of data reading and storing. If a dictionary contains more than 100,000 distinct values, then ClickHouse can perform worse in comparison with using ordinary data types.
+The efficiency of using `LowCardinality` data type depends on data diversity. If a dictionary contains less than 10,000 distinct values, then ClickHouse mostly shows higher efficiency of data reading and storing. If a dictionary contains more than 100,000 distinct values, then ClickHouse can perform worse in comparison with using ordinary data types.
 
 Consider using `LowCardinality` instead of [Enum](../../sql-reference/data-types/enum.md) when working with strings. `LowCardinality` provides more flexibility in use and often reveals the same or higher efficiency.
 

docs/en/sql-reference/functions/type-conversion-functions.md

@@ -516,7 +516,7 @@ Result:
 
 **See Also**
 
--   \[ISO 8601 announcement by @xkcd\](https://xkcd.com/1179/)
+-   [ISO 8601 announcement by @xkcd](https://xkcd.com/1179/)
 -   [RFC 1123](https://tools.ietf.org/html/rfc1123)
 -   [toDate](#todate)
 -   [toDateTime](#todatetime)

docs/ru/operations/settings/settings.md

@@ -1616,6 +1616,63 @@ SELECT idx, i FROM null_in WHERE i IN (1, NULL) SETTINGS transform_null_in = 1;
 
 -   [Обработка значения NULL в операторе IN](../../sql-reference/operators/in.md#in-null-processing)
 
+## low\_cardinality\_max\_dictionary\_size {#low_cardinality_max_dictionary_size}
+
+Задает максимальный размер общего глобального словаря (в строках) для типа данных `LowCardinality`, который может быть записан в файловую систему хранилища. Настройка предотвращает проблемы с оперативной памятью в случае неограниченного увеличения словаря. Все данные, которые не могут быть закодированы из-за ограничения максимального размера словаря, ClickHouse записывает обычным способом.
+
+Допустимые значения:
+
+-   Положительное целое число.
+
+Значение по умолчанию: 8192.
+
+## low\_cardinality\_use\_single\_dictionary\_for\_part {#low_cardinality_use_single_dictionary_for_part}
+
+Включает или выключает использование единого словаря для куска (парта).
+
+По умолчанию сервер ClickHouse следит за размером словарей, и если словарь переполняется, сервер создает следующий. Чтобы запретить создание нескольких словарей, задайте настройку `low_cardinality_use_single_dictionary_for_part = 1`.
+
+Допустимые значения:
+
+-   1 — Создание нескольких словарей для частей данных запрещено.
+-   0 — Создание нескольких словарей для частей данных не запрещено.
+
+Значение по умолчанию: 0.
+
+## low\_cardinality\_allow\_in\_native\_format {#low_cardinality_allow_in_native_format}
+
+Разрешает или запрещает использование типа данных `LowCardinality` с форматом данных [Native](../../interfaces/formats.md#native).
+
+Если использование типа `LowCardinality` ограничено, сервер CLickHouse преобразует столбцы `LowCardinality` в обычные столбцы для запросов `SELECT`, а обычные столбцы - в столбцы `LowCardinality` для запросов `INSERT`.
+
+В основном настройка используется для сторонних клиентов, не поддерживающих тип данных `LowCardinality`.
+
+Допустимые значения:
+
+-   1 — Использование `LowCardinality` не ограничено.
+-   0 — Использование `LowCardinality` ограничено.
+
+Значение по умолчанию: 1.
+
+## allow\_suspicious\_low\_cardinality\_types {#allow_suspicious_low_cardinality_types}
+
+Разрешает или запрещает использование типа данных `LowCardinality` с типами данных с фиксированным размером 8 байт или меньше: числовые типы данных и `FixedString (8_bytes_or_less)`.
+
+Для небольших фиксированных значений использование `LowCardinality` обычно неэффективно, поскольку ClickHouse хранит числовой индекс для каждой строки. В результате:
+
+-   Используется больше дискового пространства.
+-   Потребление ОЗУ увеличивается, в зависимости от размера словаря.
+-   Некоторые функции работают медленнее из-за дополнительных операций кодирования.
+
+Время слияния в таблицах на движке [MergeTree](../../engines/table-engines/mergetree-family/mergetree.md) также может увеличиться по описанным выше причинам.
+
+Допустимые значения:
+
+-   1 — Использование `LowCardinality` не ограничено.
+-   0 — Использование `LowCardinality` ограничено.
+
+Значение по умолчанию: 0.
+
 ## background_buffer_flush_schedule_pool_size {#background_buffer_flush_schedule_pool_size}
 
 Задает количество потоков для выполнения фонового сброса данных в таблицах с движком [Buffer](../../engines/table-engines/special/buffer.md). Настройка применяется при запуске сервера ClickHouse и не может быть изменена в пользовательском сеансе.

docs/ru/sql-reference/data-types/aggregatefunction.md

@@ -1,3 +1,8 @@
+---
+toc_priority: 53
+toc_title: AggregateFunction
+---
+
 # AggregateFunction {#data-type-aggregatefunction}
 
 Агрегатные функции могут обладать определяемым реализацией промежуточным состоянием, которое может быть сериализовано в тип данных, соответствующий AggregateFunction(…), и быть записано в таблицу обычно посредством [материализованного представления] (../../sql-reference/statements/create.md#create-view). Чтобы получить промежуточное состояние, обычно используются агрегатные функции с суффиксом `-State`. Чтобы в дальнейшем получить агрегированные данные необходимо использовать те же агрегатные функции с суффиксом `-Merge`.

docs/ru/sql-reference/data-types/array.md

@@ -1,3 +1,8 @@
+---
+toc_priority: 52
+toc_title: Array(T)
+---
+
 # Array(T) {#data-type-array}
 
 Массив из элементов типа `T`.

docs/ru/sql-reference/data-types/lowcardinality.md

@@ -0,0 +1,59 @@
+---
+toc_priority: 51
+toc_title: LowCardinality
+---
+
+# LowCardinality {#lowcardinality-data-type}
+
+Изменяет внутреннее представление других типов данных, превращая их в тип со словарным кодированием.
+
+## Синтаксис {#lowcardinality-syntax}
+
+```sql
+LowCardinality(data_type)
+```
+
+**Параметры**
+
+- `data_type` — [String](string.md), [FixedString](fixedstring.md), [Date](date.md), [DateTime](datetime.md) и числа за исключением типа [Decimal](decimal.md). `LowCardinality` неэффективен для некоторых типов данных, см. описание настройки [allow_suspicious_low_cardinality_types](../../operations/settings/settings.md#allow_suspicious_low_cardinality_types).
+
+## Описание {#lowcardinality-dscr}
+
+`LowCardinality` — это надстройка, изменяющая способ хранения и правила обработки данных. ClickHouse применяет [словарное кодирование](https://en.wikipedia.org/wiki/Dictionary_coder) в столбцы типа `LowCardinality`. Работа с данными, представленными в словарном виде, может значительно увеличивать производительность запросов [SELECT](../statements/select/index.md) для многих приложений.
+
+Эффективность использования типа данных `LowCarditality` зависит от разнообразия данных. Если словарь содержит менее 10 000 различных значений, ClickHouse в основном показывает более высокую эффективность чтения и хранения данных. Если же словарь содержит более 100 000 различных значений, ClickHouse может работать хуже, чем при использовании обычных типов данных.
+
+При работе со строками, использование `LowCardinality` вместо [Enum](enum.md). `LowCardinality` обеспечивает большую гибкость в использовании и часто показывает такую же или более высокую эффективность.
+
+## Пример
+
+Создать таблицу со столбцами типа `LowCardinality`:
+
+```sql
+CREATE TABLE lc_t
+(
+    `id` UInt16, 
+    `strings` LowCardinality(String)
+)
+ENGINE = MergeTree()
+ORDER BY id
+```
+
+## Связанные настройки и функции
+
+Настройки:
+
+- [low_cardinality_max_dictionary_size](../../operations/settings/settings.md#low_cardinality_max_dictionary_size)
+- [low_cardinality_use_single_dictionary_for_part](../../operations/settings/settings.md#low_cardinality_use_single_dictionary_for_part)
+- [low_cardinality_allow_in_native_format](../../operations/settings/settings.md#low_cardinality_allow_in_native_format)
+- [allow_suspicious_low_cardinality_types](../../operations/settings/settings.md#allow_suspicious_low_cardinality_types)
+
+Функции:
+
+- [toLowCardinality](../functions/type-conversion-functions.md#tolowcardinality)
+
+## Смотрите также
+
+- [A Magical Mystery Tour of the LowCardinality Data Type](https://www.altinity.com/blog/2019/3/27/low-cardinality).
+- [Reducing Clickhouse Storage Cost with the Low Cardinality Type – Lessons from an Instana Engineer](https://www.instana.com/blog/reducing-clickhouse-storage-cost-with-the-low-cardinality-type-lessons-from-an-instana-engineer/).
+- [String Optimization (video presentation in Russian)](https://youtu.be/rqf-ILRgBdY?list=PL0Z2YDlm0b3iwXCpEFiOOYmwXzVmjJfEt). [Slides in English](https://github.com/yandex/clickhouse-presentations/raw/master/meetup19/string_optimization.pdf).

docs/ru/sql-reference/data-types/nullable.md

@@ -1,3 +1,8 @@
+---
+toc_priority: 55
+toc_title: Nullable
+---
+
 # Nullable(TypeName) {#data_type-nullable}
 
 Позволяет работать как со значением типа `TypeName` так и с отсутствием этого значения ([NULL](../../sql-reference/data-types/nullable.md)) в одной и той же переменной, в том числе хранить `NULL` в таблицах вместе со значения типа `TypeName`. Например, в столбце типа `Nullable(Int8)` можно хранить значения типа `Int8`, а в тех строках, где значения нет, будет храниться `NULL`.

docs/ru/sql-reference/data-types/tuple.md

@@ -1,3 +1,8 @@
+---
+toc_priority: 54
+toc_title: Tuple(T1, T2, ...)
+---
+
 # Tuple(T1, T2, …) {#tuplet1-t2}
 
 Кортеж из элементов любого [типа](index.md#data_types). Элементы кортежа могут быть одного или разных типов.

docs/ru/sql-reference/functions/type-conversion-functions.md

@@ -508,7 +508,7 @@ SELECT parseDateTimeBestEffort('10 20:19')
 
 **См. также**
 
--   \[Информация о формате ISO 8601 от @xkcd\](https://xkcd.com/1179/)
+-   [Информация о формате ISO 8601 от @xkcd](https://xkcd.com/1179/)
 -   [RFC 1123](https://tools.ietf.org/html/rfc1123)
 -   [toDate](#todate)
 -   [toDateTime](#todatetime)
@@ -678,4 +678,43 @@ SELECT fromUnixTimestamp64Milli(i64, 'UTC')
 └──────────────────────────────────────┘
 ```
 
+## toLowCardinality {#tolowcardinality}
+
+Преобразует входные данные в версию [LowCardianlity](../data-types/lowcardinality.md) того же типа данных.
+
+Чтобы преобразовать данные из типа `LowCardinality`, используйте функцию [CAST](#type_conversion_function-cast). Например, `CAST(x as String)`.
+
+**Синтаксис**
+
+```sql
+toLowCardinality(expr)
+```
+
+**Параметры**
+
+- `expr` — [Выражение](../syntax.md#syntax-expressions), которое в результате преобразуется в один из [поддерживаемых типов данных](../data-types/index.md#data_types).
+
+
+**Возвращаемое значение**
+
+- Результат преобразования `expr`.
+
+Тип: `LowCardinality(expr_result_type)`
+
+**Example**
+
+Запрос:
+
+```sql
+SELECT toLowCardinality('1')
+```
+
+Результат:
+
+```text
+┌─toLowCardinality('1')─┐
+│ 1                     │
+└───────────────────────┘
+```
+
 [Оригинальная статья](https://clickhouse.tech/docs/ru/query_language/functions/type_conversion_functions/) <!--hide-->