olap tables documentation

11 files changed, 247 insertions, 4 deletions

diff --git a/ydb/docs/ru/core/_includes/olap-data-types.md b/ydb/docs/ru/core/_includes/olap-data-types.md
new file mode 100644
index 0000000000..e6d3c3c374
--- /dev/null
+++ b/ydb/docs/ru/core/_includes/olap-data-types.md
@@ -0,0 +1,24 @@
+|Тип данных|Можно использовать в колоночных таблицах|Можно использовать в качестве первичного ключа|
+|-----|------|------|
+|Bool|Нет|Нет|
+|Int8|Да|Нет|
+|Int16|Да|Нет|
+|Int32|Да|Да|
+|Int64|Да|Да|
+|Uint8|Да|Да|
+|Uint16|Да|Да|
+|Uint32|Да|Да|
+|Uint64|Да|Да|
+|Float|Да|Нет|
+|Double|Да|Нет|
+|Decimal|Нет|Нет|
+|String|Да|Да|
+|Utf8|Да|Да|
+|Json|Да|Нет|
+|JsonDocument|Да|Нет|
+|Yson|Да|Нет|
+|Uuid|Нет|Нет|
+|Date|Да|Да|
+|Datetime|Да|Да|
+|Timestamp|Да|Да|
+|Interval|Нет|Нет|
\ No newline at end of file
diff --git a/ydb/docs/ru/core/best_practices/_includes/pk_olap_scalability.md b/ydb/docs/ru/core/best_practices/_includes/pk_olap_scalability.md
new file mode 100644
index 0000000000..9769c77c8e
--- /dev/null
+++ b/ydb/docs/ru/core/best_practices/_includes/pk_olap_scalability.md
@@ -0,0 +1,24 @@
+# Выбор первичного ключа для максимальной производительности колоночных таблиц
+
+В отличие от строковых таблиц {{ ydb-short-name }}, колоночные таблицы партиционируют данные не по первичным ключам, а по специально выделенным ключам — ключам партиционирования. При этом внутри каждой партиции данные распределяются в порядке первичного ключа таблицы. 
+
+Поэтому для эффективной работы с колоночными таблицами {{ ydb-short-name }} необходимо правильно выбирать первичный ключ и ключ партиционирования таблиц.
+
+Так как ключ партиционирования определяет партицию, в которой данных хранятся, то ключ партиционирования следует выбирать так, чтобы Hash(partition_key) приводил к равномерному распределению данных по партициям. Оптимально, если ключ партиционирования содержит в 100-1000 раз больше уникальных значений, чем число партиций в таблице. 
+
+Ключи, у которых существует большое количество уникальных значений, называются высококардинальными, и, наоборот, если уникальных значений мало, то такие ключи называются низкокардинальными. Если в качестве ключа партиционирования используется низкокардинальный ключ, данные могут распределиться по партициями неравномерно, перегрузив часть партиций. Перегрузка партиций приведет к неоптимальной производительности запросов и/или ограничениям на максимальный поток вставляемых данных.
+
+Первичный ключ определяет порядок хранения данных внутри партиции, поэтому при выборе первичного ключа необходимо учитывать не только эффективность сценария чтения данных из партиции, но и эффективность вставки в партицию данных. Оптимальный сценарий вставки - запись данных в начало или в конец таблицы с редкими локальными обновлениями уже вставленных данных. Например, эффективен сценарий хранения журналов работы приложений, когда данные хранятся по временным меткам, а новые записи добавляются в конец партиции за счет использования текущего времени в первичном ключе.
+
+{% note warning %}
+
+В настоящий момент необходимо таким образом выбирать первичный ключ, чтобы в качестве первой колонки первичного ключа использовалась высококардинальная колонка. Примером эффективной первой колонки является колонка с типом Timestamp (временная метка). Примером неэффективной первой колонки является колонка с типом Uint16 и 1000 уникальных значений.
+
+{% endnote %}
+
+
+В настоящий момент колоночные таблицы не поддерживают автоматического решардирования, поэтому важно указывать правильное число партиций при создании таблицы. Оценить необходимое количество партиций можно по предполагаемому объему добавляемых в таблицу данных. Средняя пропускная способность партции на добавление данных — 1 МБ/c. При этом пропускная способность в первую очередь определяется выбранным первичным ключом (необходимостью сортировки данных внутри партиции при добавлении новых данных). Для небольших потоков данных не рекомендуется задавать больше 128 партиций.
+
+Пример:
+
+При потоке данных в 1ГБ/с оптимально использовать аналитическую таблицу с 1000 партиций. При этом создавать таблицы с значительным запасом партиций не стоит, т.к. это приведет к росту потребляемых ресурсов в кластере и итоговому замедлению скорости выполнения запросов. 
\ No newline at end of file
diff --git a/ydb/docs/ru/core/best_practices/pk_olap_scalability.md b/ydb/docs/ru/core/best_practices/pk_olap_scalability.md
new file mode 100644
index 0000000000..fd06159ce8
--- /dev/null
+++ b/ydb/docs/ru/core/best_practices/pk_olap_scalability.md
@@ -0,0 +1 @@
+{% include [pk_scalability.md](_includes/pk_olap_scalability.md) %}
\ No newline at end of file
diff --git a/ydb/docs/ru/core/best_practices/toc_i.yaml b/ydb/docs/ru/core/best_practices/toc_i.yaml
index e620698044..536acfc6b8 100644
--- a/ydb/docs/ru/core/best_practices/toc_i.yaml
+++ b/ydb/docs/ru/core/best_practices/toc_i.yaml
@@ -3,6 +3,8 @@ items:
   href: index.md
 - name: Выбор первичного ключа для максимальной производительности
   href: pk_scalability.md
+- name: Выбор первичного ключа для максимальной производительности аналитических таблиц
+  href: pk_olap_scalability.md  
 - name: Проектирование схемы
   href: schema_design.md
   hidden: true
diff --git a/ydb/docs/ru/core/concepts/_includes/limits-ydb.md b/ydb/docs/ru/core/concepts/_includes/limits-ydb.md
index 994cd44e61..3300ad026c 100644
--- a/ydb/docs/ru/core/concepts/_includes/limits-ydb.md
+++ b/ydb/docs/ru/core/concepts/_includes/limits-ydb.md
@@ -30,6 +30,14 @@
 | Максимальный суммарный размер всех столбцов в первичном ключе | 1 Мб | GENERIC_ERROR |
 | Максимальный размер значения строкового столбца  | 8 Мб | GENERIC_ERROR |
 
+## Ограничения аналитических таблиц
+
+| Параметр | Значение | 
+| :--- | :--- | 
+| Максимальный размер строки | 8 Мб | 
+| Максимальный размер вставляемого блока данных | 8 Мб | 
+
+
 ## Ограничения при выполнении запросов
 
 В таблице ниже перечислены ограничения, действующие при выполнении запросов. В столбце _Вызов_ указан вызов public api, обращение к которому завершится со статусом ошибки, указанным в столбце _Статус_.
diff --git a/ydb/docs/ru/core/concepts/datamodel/_includes/column_table.md b/ydb/docs/ru/core/concepts/datamodel/_includes/column_table.md
new file mode 100644
index 0000000000..47af5da9d9
--- /dev/null
+++ b/ydb/docs/ru/core/concepts/datamodel/_includes/column_table.md
@@ -0,0 +1,56 @@
+## Колоночные таблицы {#olap-tables}
+
+{% note warning %}
+
+Колоночные таблицы {{ ydb-short-name }} доступны в режиме Preview.
+
+{% endnote %}
+
+Колоночная таблица {{ ydb-short-name }} — это реляционная таблица, содержащая набор связанных данных, состоящий из строк и столбцов. В отличии от обычных, строковых, [таблиц {{ ydb-short-name }}](#table), предназначенных для [OLTP-нагрузки](https://ru.wikipedia.org/wiki/OLTP), колоночные таблицы оптимизированы для задач анализа данных, [OLAP-нагрузки](https://ru.wikipedia.org/wiki/OLAP). 
+
+На данный момент основной сценарий использования колоночных таблиц — запись данных с возрастающим первичным ключом (например, время события), анализ этих данных и удаление устаревших данных по TTL. Оптимальным способом добавления данных в колоночные таблицы является пакетная запись, выполяемая блоками в единицы мегабайт.
+
+Вставка пакетов данных производится атомарно: данные будут записаны или во все партиции, или ни в одну из. При чтении анализируются только полностью записанные в колоночные таблицы данные.
+
+
+### Особенности { #olap-vs-oltp-tables }
+В большинстве случаев все описание работы строковых таблиц {{ ydb-short-name }} подходит и для описания колоночных таблиц, ниже приведены отличия. 
+
+- В качестве ключевых колонок можно использовать только NOT NULL колонки.
+- Данные партицируются не по первичному ключу, а по Hash от [колонок партиционирования](#olap-tables-partitioning).
+- Поддерживается [ограниченный набор](#olap-data-types) типов данных.
+
+{% note info %}
+
+В настоящий момент не поддерживается: 
+  - Чтение с реплик.
+  - Вторичные индексы. 
+  - Фильтры Блума.
+  - Change Data Capture. 
+  - Переименование таблиц. 
+  - Пользовательские аттрибуты таблиц.
+  - Изменение списка колонок данных в колоночных таблицах.
+  - Добавление данных в колоночные таблицы с помощью SQL-команды `INSERT`.
+  - Удаление данных из колоночных таблиц с помощью SQL-команды `DELETE`. Фактически, удаление возможно только по истечению TTL времени хранения данных.
+
+{% endnote %}
+
+### Поддерживаемые типы данных { #olap-data-types }
+
+{% include [olap-data-types](../../../_includes/olap-data-types.md) %}
+
+### Партиционирование { #olap-tables-partitioning }
+
+В отличие от строковых таблиц {{ ydb-short-name }}, колоночные таблицы партиционируют данные не по первичным ключам, а по специально выделенным ключам — ключам партиционирования. Ключи партиционирования являются подмножеством первичных ключей таблицы. В отличие от партиционирования данных в строковых таблиц {{ ydb-short-name }}, партиционирование данных для колоночных таблиц выполняется не по значениям ключей, а по hash-значениям от ключей, что позволяет равномерно распределить данные во все существующие партиции.
+Такое партиционирование позволяет избежать хотспотов при вставке и ускоряет аналитические запросы, обрабатывающие (считывающие) большие объемы данных.
+
+Выбор ключей партиционирования существенно влияет на производительность колоночных таблиц. Подробнее про выбор ключей для партиционирования колоночных таблиц описано в разделе [Выбор ключа для максимальной производительности для колоночных таблиц](../../../best_practices/pk_olap_scalability.md).
+
+Для управления партиционированием данных используется параметр AUTO_PARTITIONING_MIN_PARTITIONS_COUNT. Остальные параметры партиционирования для колоночных таблиц игнорируются.
+
+#### AUTO_PARTITIONING_MIN_PARTITIONS_COUNT { #auto_partitioning_min_partitions_count }
+
+* Тип: `Uint64`.
+* Значение по умолчанию: `1`.
+
+Определяет минимальное физическое количество партиций для хранения данных. С учетом, что остальные параметры партиционирования игнорируются, фактически это же значение определяет и верхнее число партиций для партиционирования.
diff --git a/ydb/docs/ru/core/concepts/datamodel/_includes/table.md b/ydb/docs/ru/core/concepts/datamodel/_includes/table.md
index 634e7a29c0..eb38b6fc4e 100644
--- a/ydb/docs/ru/core/concepts/datamodel/_includes/table.md
+++ b/ydb/docs/ru/core/concepts/datamodel/_includes/table.md
@@ -169,3 +169,4 @@
 * максимальный общий размер атрибутов (сумма длин всех ключей и значений) — 10240 байт.
 
 О том, как добавить, изменить, получить текущие значения или удалить атрибуты читайте в статье [{#T}](../../../operations/manage-users-attr.md).
+
diff --git a/ydb/docs/ru/core/concepts/datamodel/column_table.md b/ydb/docs/ru/core/concepts/datamodel/column_table.md
new file mode 100644
index 0000000000..304d0db2dc
--- /dev/null
+++ b/ydb/docs/ru/core/concepts/datamodel/column_table.md
@@ -0,0 +1 @@
+{% include [column_table.md](_includes/column_table.md) %}
\ No newline at end of file
diff --git a/ydb/docs/ru/core/concepts/datamodel/toc_i.yaml b/ydb/docs/ru/core/concepts/datamodel/toc_i.yaml
index 636277756d..1a1f94a055 100644
--- a/ydb/docs/ru/core/concepts/datamodel/toc_i.yaml
+++ b/ydb/docs/ru/core/concepts/datamodel/toc_i.yaml
@@ -2,4 +2,5 @@ items:
 - { name: Обзор,                                  href: index.md }
 - { name: Директория,                             href: dir.md }
 - { name: Таблица,                                href: table.md }
+- { name: Колоночная таблица,                     href: column_table.md }
 - { name: Топик,                                  href: ../topic.md }
diff --git a/ydb/docs/ru/core/getting_started/_includes/yql.md b/ydb/docs/ru/core/getting_started/_includes/yql.md
index 727d66d8b4..d115be43ac 100644
--- a/ydb/docs/ru/core/getting_started/_includes/yql.md
+++ b/ydb/docs/ru/core/getting_started/_includes/yql.md
@@ -82,6 +82,36 @@ CREATE TABLE episodes (
 
 Для исполнения скрипта через {{ ydb-short-name }} CLI выполните инструкции, приведенные в пункте [Исполнение в {{ ydb-short-name }} CLI](#cli) данной статьи.
 
+### Создание колоночных таблиц {#create-olap-table}
+
+Таблица с заданными колонками создается [командой YQL `CREATE TABLE`](../../yql/reference/syntax/create_table.md). В таблице обязательно должен быть определен первичный ключ и ключ партиционирования. Типы данных для колонок приведены в статье [Типы данных YQL](../../yql/reference/types/index.md), а допустимые для использования в аналитических таблицах типы данных описаны в разделе [Поддерживаемые типы данных колоночных таблиц](../../concepts/datamodel/table.md#olap-data-types).
+
+Колонки, входящие в первичный ключ, должны быть описаны с ограничением `NOT NULL`. Остальные колонки по умолчанию опциональные и могут содержать `NULL`.  Ограничения `FOREIGN KEY` {{ ydb-short-name }} не поддерживает.
+
+Создайте таблицы каталога сериалов: `views` (Просмотры), выполнив следующий скрипт:
+
+```sql
+CREATE TABLE views (
+    series_id Uint64 NOT NULL,
+    season_id Uint64,
+    viewed_at Timestamp NOT NULL,
+    person_id Uint64 NOT NULL,
+    PRIMARY KEY (viewed_at, series_id, person_id)
+)
+PARTITION BY HASH(viewed_at, series_id)
+WITH (
+  STORE = COLUMN,
+  AUTO_PARTITIONING_MIN_PARTITIONS_COUNT = 10
+)
+```
+
+Описание всех возможностей работы с таблицами приведены в разделах документации по YQL:
+
+* [CREATE TABLE](../../yql/reference/syntax/create_table.md) — создание таблицы и определение начальных параметров.
+* [DROP TABLE](../../yql/reference/syntax/drop_table.md) — удаление таблицы.
+
+Для исполнения скрипта через {{ ydb-short-name }} CLI выполните инструкции, приведенные в пункте [Исполнение в {{ ydb-short-name }} CLI](#cli) данной статьи.
+
 ### Получение перечня существующих таблиц в БД {#scheme-ls}
 
 Проверьте, что таблицы фактически созданы в БД.
diff --git a/ydb/docs/ru/core/yql/reference/yql-core/syntax/_includes/create_table.md b/ydb/docs/ru/core/yql/reference/yql-core/syntax/_includes/create_table.md
index c9a78cdde0..7b6adc7d05 100644
--- a/ydb/docs/ru/core/yql/reference/yql-core/syntax/_includes/create_table.md
+++ b/ydb/docs/ru/core/yql/reference/yql-core/syntax/_includes/create_table.md
@@ -1,5 +1,12 @@
 # CREATE TABLE
 
+{% if feature_olap_tables %}
+{{ ydb-short-name }} поддерживает несколько видов таблиц: [строковые](../../../../concepts/datamodel/table.md) и в режиме превью [колоночные](../../../../concepts/datamodel/column_table.md). Тип таблицы определяется параметром `STORE`, где `ROW` означает [строковую таблицу](#row), а `COLUMN` означает [колоночную](#olap-tables). По умолчанию, если параметр `STORE` не указан, создается строковая таблица.
+
+
+{%endif%}
+
+{% if feature_olap_tables %}## Строковые таблицы {#row}{%endif%}
 {% if feature_bulk_tables %}
 
 Таблица создается автоматически при первом [INSERT INTO](insert_into.md){% if feature_mapreduce %}, в заданной оператором [USE](../use.md) базе данных{% endif %}. Схема при этом определяется автоматически.
@@ -28,7 +35,7 @@
     WITH ( key = value, ... )
 {% endif %}
 
-## Колонки {#columns}
+{% if feature_olap_tables %}#{%endif%}## Колонки {#columns}
 
 {% if feature_column_container_type == true %}
 Для неключевых колонок допускаются любые типы данных, для ключевых - только [примитивные](../../types/primitive.md). При указании сложных типов (например, `List<String>`) тип заключается в двойные кавычки.
@@ -64,7 +71,7 @@
 
 
 {% if feature_secondary_index %}
-## Вторичные индексы {#secondary_index}
+{% if feature_olap_tables %}#{%endif%}## Вторичные индексы {#secondary_index}
 
 Конструкция INDEX используется для определения {% if concept_secondary_index %}[вторичного индекса]({{ concept_secondary_index }}){% else %}вторичного индекса{% endif %} на таблице:
 
@@ -98,7 +105,7 @@ CREATE TABLE my_table (
 {% endif %}
 
 {% if feature_map_tables and concept_table %}
-## Дополнительные параметры {#additional}
+{% if feature_olap_tables %}#{%endif%}## Дополнительные параметры {#additional}
 
 Для таблицы может быть указан ряд специфичных для {{ backend_name }} параметров. При создании таблицы, используя YQL, такие параметры перечисляются в блоке ```WITH```:
 
@@ -131,7 +138,7 @@ WITH (
 );
 ```
 
-## Группы колонок {#column-family}
+{% if feature_olap_tables %}#{%endif%}## Группы колонок {#column-family}
 
 Колонки одной таблицы можно объединять в группы, для того чтобы задать следующие параметры:
 
@@ -169,3 +176,91 @@ CREATE TABLE series_with_families (
 {% endif %}
 
 {% endif %}
+
+{% if feature_olap_tables %}
+## Колоночные таблицы {#olap-tables}
+
+{% note warning %}
+
+Колоночные таблицы {{ ydb-short-name }} доступны в режиме Preview.
+
+{% endnote %}
+
+Вызов `CREATE TABLE` создает [колоночную таблицу](../../../../concepts/datamodel/column_table.md) с указанной схемой данных и ключевыми колонками (`PRIMARY KEY`). 
+
+```sql
+CREATE TABLE table_name (
+    column1 type1,
+    column2 type2 NOT NULL,
+    column2 type2,
+    ...
+    columnN typeN,
+    PRIMARY KEY ( column, ... ),
+    ...
+)
+PARTITION BY HASH(column1, column2, ...)
+WITH ( 
+    STORE = COLUMN,
+    key = value, 
+    ... 
+)
+```        
+
+### Колонки {#columns}
+
+Поддерживаемые типы данных в колоночных таблицах и ограничение на использование типов в первичных ключах или колонках данных описаны в разделе [поддерживаемые типы данных](../../../../concepts/datamodel/column_table.md#olap-data-types) колоночных таблиц.
+
+Обязательно указание `PRIMARY KEY` и `PARTITION BY` с непустым списком колонок. 
+
+Без дополнительных модификаторов колонка приобретает [опциональный тип](../../types/optional.md) тип, и допускает запись `NULL` в качестве значений. Для получения неопционального типа необходимо использовать `NOT NULL`.
+
+
+**Пример**
+
+```sql
+CREATE TABLE my_table (
+    a Uint64 NOT NULL,
+    b String,
+    c Float,
+    PRIMARY KEY (b, a)
+)
+PARTITION BY HASH(b)
+WITH (
+STORE = COLUMN
+)
+```
+
+
+### Дополнительные параметры {#additional}
+
+Для таблицы может быть указан ряд специфичных для {{ backend_name }} параметров. При создании таблицы, используя YQL, такие параметры перечисляются в блоке ```WITH```:
+
+```sql
+CREATE TABLE table_name (...)
+WITH (
+    key1 = value1,
+    key2 = value2,
+    ...
+)
+```
+
+Здесь key — это название параметра, а value — его значение.
+
+Поддерживаемые параметры колоночных таблиц:
+- [AUTO_PARTITIONING_MIN_PARTITIONS_COUNT](../../../../concepts/datamodel/column_table.md#auto_partitioning_min_partitions_count)
+
+Например, следующий код создает колоночную таблицу с 10-ю партициями:
+
+<small>Листинг 5</small>
+```sql
+CREATE TABLE my_table (
+    id Uint64,
+    title Utf8,
+    PRIMARY KEY (id)
+)
+PARTITION BY HASH(id)
+WITH (
+    AUTO_PARTITIONING_MIN_PARTITIONS_COUNT = 10
+);
+```
+{%endif%}
\ No newline at end of file