Topic DDL docs

5 files changed, 235 insertions, 0 deletions

diff --git a/ydb/docs/ru/core/yql/reference/yql-core/syntax/alter_topic.md b/ydb/docs/ru/core/yql/reference/yql-core/syntax/alter_topic.md
new file mode 100644
index 0000000000..51ba4663d4
--- /dev/null
+++ b/ydb/docs/ru/core/yql/reference/yql-core/syntax/alter_topic.md
@@ -0,0 +1,141 @@
+# ALTER TOPIC
+
+При помощи команды `ALTER TOPIC` можно изменить настройки [топика](../../../../concepts/topic), добавить, изменить или удалить читателей.
+
+{% include [trunk](../../../_includes/trunk.md) %}
+
+В общем случае команда `ALTER TOPIC` выглядит так:
+
+```sql
+ALTER TOPIC topic_path action1, action2, ..., actionN;
+```
+
+`action` — это действие по изменению , из описанных ниже.
+
+## Изменение набора читателей
+
+`ADD CONSUMER` — добавляет [читателей](../../../../concepts/topic#consumer) для топика.
+
+Следующий пример добавит к топику читателя с настройками по умолчанию.
+
+```sql
+ALTER TOPIC `my_topic` ADD CONSUMER new_consumer;
+```
+
+При добавлении читателя можно указывать его настройки, например:
+
+```sql
+ALTER TOPIC `my_topic` ADD CONSUMER new_consumer2 WITH (important = false);
+```
+
+### Полный список доступных настроек читателей топика
+
+* `important` - определяет важного читателя. Никакие данные из топика не будут удалены, пока все важные читатели их не прочитали. Тип значения - `boolean`, значение по умолчанию: `false`.
+* `read_from` - определяет момент времени записи сообщений, начиная с которого читатель будет получать данные. Данные, записанные раньше этого момента прочитаны не будут. Тип значения: `Datetime` ИЛИ `Timestamp` или `integer` (unix-timestamp в виде числа). Значение по умолчанию - `now`
+
+{% if feature_topic_codecs %}
+* `supported_codecs` - список [кодеков](../../../../concepts/topic#message-codec), поддерживаемых читателем.
+
+{% endif %}
+
+`DROP CONSUMER` — удаляет читателя у топика.
+
+```sql
+ALTER TOPIC `my_topic` DROP CONSUMER old_consumer;
+```
+
+## Модификация настроек читателя
+
+`ALTER CONSUMER` — добавляет читателя для топика.
+
+Общий синтаксис действия `ALTER CONSUMER`:
+
+```sql
+ALTER TOPIC `topic_name` ALTER CONSUMER consumer_name consumer_action;
+```
+
+Поддерживаются следующие типы `consumer_action`:
+* `SET` - выставляет значение настроек читателя
+
+{% if feature_topic_settings_reset %}
+* `RESET` сбрасывает указанные настройки к значениям по умолчению.
+
+{% endif %}
+
+Следующий пример установит читателю параметр `important`.
+
+```sql
+ALTER TOPIC `my_topic` ALTER CONSUMER my_consumer SET (important = true);
+```
+
+{% if feature_topic_settings_reset %}
+Данный пример сбросит параметр `read_from` в default.
+
+```sql
+ALTER TOPIC `my_topic` ALTER CONSUMER my_consumer RESET (read_from);
+```
+
+{% endif %}
+
+Для одного читателя может быть указано несколько `ALTER CONSUMER` действий, однако настройки в них не должны 
+повторяться. 
+
+Пример ниже - валидный запрос
+
+```sql
+ALTER TOPIC `my_topic`
+    ALTER CONSUMER my_consumer SET (important = true)
+    ALTER CONSUMER my_consumer SET (read_from = 0);
+```
+
+А следующий запрос приведет к ошибке.
+
+```sql
+ALTER TOPIC `my_topic`
+    ALTER CONSUMER my_consumer SET (important = true)
+    ALTER CONSUMER my_consumer SET (important = false);
+```
+
+## Изменение настроек топика
+
+Действие `SET (option = value[, ...])` позволяет изменить настройки топика.
+
+Пример ниже изменит время хранения данных в топике и квоту на скорость записи в 1 партицию: 
+
+```sql
+ALTER TOPIC `my_topic` SET (
+    retention_period = Interval('PT36H'),
+    partition_write_speed_bytes_per_second = 3000000
+);
+```
+
+{% if feature_topic_settings_reset %}
+
+Действие `RESET (option[, option2, ...])` позволяет сбросить настройки топика в значение по умолчанию.
+
+**Пример**
+
+```sql
+ALTER TOPIC `my_topic` RESET (
+    min_active_partitions,
+    partition_count_limit    
+);
+```
+
+{% endif %}
+
+### Полный список доступных настроек топика
+
+* `min_active_partitions` - минимальное количество активных партиций топика. Автоматическая балансировка нагрузки не будет уменьшать количество активных партиций ниже этого количества. Тип значения - `integer`, значение по умолчанию: `1`.
+* `partition_count_limit` - максимальное количество активных партиций топика. `0` интерпретируется как unlimited. Тип значения - `integer`, значение по умолчанию: `0`.
+* `retention_period` - время хранения данных в топике. Тип значения - `Interval`, значение по умолчанию: `18h`.
+* `retention_storage_mb` - ограничение на максимальное место на диске, занимаемое данными топика. При превышении этого значения старые данные будут удаляться, как по retention. `0` интерпретируется как unlimited. Тип значения - `integer`, значение по умолчанию: `0`
+* `partition_write_speed_bytes_per_second` - максимальная разрешенная скорость записи в 1 партицию. Если поток записи в партицию превысит это значение, запись будет квотироваться. Тип значения - `integer`, значение по умолчанию: `2097152` (2MB).
+* `partition_write_burst_bytes` - размер "запаса" квоты на запись в партицию на случай всплесков записи. При выставлении в 0 фактическое значение write_burst принимается равным значению квоты (что позволяет всплески записи длительностью до 1 секунды). Тип значения - `integer`, значение по умолчанию: `0`.
+* `metering_mode` - способ метеринга ресурсов (RESERVED_CAPACITY или REQUEST_UNITS). Тип значения - `String`.
+
+{% if feature_topic_codecs %}
+* `supported_codecs` - список [кодеков](../../../../concepts/topic#message-codec), поддерживаемых топиком. Тип значения - `String`.
+
+{% endif %}
+
diff --git a/ydb/docs/ru/core/yql/reference/yql-core/syntax/create_topic.md b/ydb/docs/ru/core/yql/reference/yql-core/syntax/create_topic.md
new file mode 100644
index 0000000000..db94476f2b
--- /dev/null
+++ b/ydb/docs/ru/core/yql/reference/yql-core/syntax/create_topic.md
@@ -0,0 +1,68 @@
+# CREATE TOPIC
+
+Вызов `CREATE TOPIC` создает [топик](../../../../concepts/topic).
+
+{% include [trunk](../../../_includes/trunk.md) %}
+
+При создании можно указать [читаталей](../../../../concepts/topic#consumer) топика, которые будут созданы для него а так же настройки топика. 
+
+```
+    CREATE TOPIC topic_path (
+        CONSUMER consumer1,
+        CONSUMER consumer2 WITH (setting1 = value1)
+    ) WITH (
+        topic_setting2 = value2
+    );
+```
+
+Все параметры, кроме имени топика - опциональны. По умолчанию топик создается без читателей. Все
+не указанные явно настройки также выставляются по умолчанию (и для топика, и для читаталей).
+
+## Примеры
+
+Создание топика без читателей с настройками по умолчанию:
+
+```sql
+CREATE TOPIC `my_topic`;
+```
+
+Создание топика с одним читателем, с включением опции important:
+
+```sql
+CREATE TOPIC `my_topic` (
+    CONSUMER my_consumer WITH (important = true)
+);
+```
+
+### Полный список доступных настроек читателей топика
+
+* `important` - определяет важного читателя. Никакие данные из топика не будут удалены, пока все важные читатели их не прочитали. Тип значения - `boolean`, значение по умолчанию: `false`.
+* `read_from` - определяет момент времени записи сообщений, начиная с которого читатель будет получать данные. Данные, записанные раньше этого момента прочитаны не будут. Тип значения: `Datetime` ИЛИ `Timestamp` или `integer` (unix-timestamp в виде числа). Значение по умолчанию - `now`
+
+{% if feature_topic_codecs %}
+* `supported_codecs` - список [кодеков](../../../../concepts/topic#message-codec), поддерживаемых читателем.
+
+{% endif %}
+
+Создание топика с указанием времени хранения данных в 1 сутки:
+
+```sql
+CREATE TOPIC `my_topic` WITH(
+    retention_period = Interval('P1D')
+);
+```
+
+### Полный список доступных настроек топика
+
+* `min_active_partitions` - минимальное количество активных партиций топика. Автоматическая балансировка нагрузки не будет уменьшать количество активных партиций ниже этого количества. Тип значения - `integer`, значение по умолчанию: `1`.
+* `partition_count_limit` - максимальное количество активных партиций топика. `0` интерпретируется как unlimited. Тип значения - `integer`, значение по умолчанию: `0`.
+* `retention_period` - время хранения данных в топике. Тип значения - `Interval`, значение по умолчанию: `18h`.
+* `retention_storage_mb` - ограничение на максимальное место на диске, занимаемое данными топика. При превышении этого значения старые данные будут удаляться, как по retention. `0` интерпретируется как unlimited. Тип значения - `integer`, значение по умолчанию: `0`
+* `partition_write_speed_bytes_per_second` - максимальная разрешенная скорость записи в 1 партицию. Если поток записи в партицию превысит это значение, запись будет квотироваться. Тип значения - `integer`, значение по умолчанию: `2097152` (2MB).
+* `partition_write_burst_bytes` - размер "запаса" квоты на запись в партицию на случай всплесков записи. При выставлении в 0 фактическое значение write_burst принимается равным значению квоты (что позволяет всплески записи длительностью до 1 секунды). Тип значения - `integer`, значение по умолчанию: `0`.
+* `metering_mode` - способ метеринга ресурсов (RESERVED_CAPACITY или REQUEST_UNITS). Тип значения - `String`.
+
+{% if feature_topic_codecs %}
+* `supported_codecs` - список [кодеков](../../../../concepts/topic#message-codec), поддерживаемых топиком. Тип значения - `String`.
+
+{% endif %}
diff --git a/ydb/docs/ru/core/yql/reference/yql-core/syntax/drop_topic.md b/ydb/docs/ru/core/yql/reference/yql-core/syntax/drop_topic.md
new file mode 100644
index 0000000000..9ffebe8376
--- /dev/null
+++ b/ydb/docs/ru/core/yql/reference/yql-core/syntax/drop_topic.md
@@ -0,0 +1,18 @@
+# DROP TOPIC
+
+Вызов `DROP TOPIC` удаляет [топик](../../../../concepts/topic).
+
+{% include [trunk](../../../_includes/trunk.md) %}
+
+```
+    DROP TOPIC topic_path;
+```
+
+Имеет один обязательный параметр - имя топика.
+
+**Пример**
+
+```sql
+DROP TOPIC `my_topic`;
+```
+
diff --git a/ydb/docs/ru/core/yql/reference/yql-core/syntax/index.md b/ydb/docs/ru/core/yql/reference/yql-core/syntax/index.md
index 0cf7919f74..f465ed4e6f 100644
--- a/ydb/docs/ru/core/yql/reference/yql-core/syntax/index.md
+++ b/ydb/docs/ru/core/yql/reference/yql-core/syntax/index.md
@@ -53,3 +53,8 @@
 {% if feature_mapreduce %}
 * [EXPORT и IMPORT](export_import.md)
 {% endif %}
+{% if feature_topic_control_plane %}
+* [CREATE TOPIC](create_topic.md)
+* [ALTER TOPIC](alter_topic.md)
+* [DROP TOPIC](drop_topic.md)
+{% endif %}
diff --git a/ydb/docs/ru/core/yql/reference/yql-core/syntax/toc_i.yaml b/ydb/docs/ru/core/yql/reference/yql-core/syntax/toc_i.yaml
index a75d7f10a3..1914ba8503 100644
--- a/ydb/docs/ru/core/yql/reference/yql-core/syntax/toc_i.yaml
+++ b/ydb/docs/ru/core/yql/reference/yql-core/syntax/toc_i.yaml
@@ -5,15 +5,18 @@ items:
 - { name: ACTION,                       href: action.md }
 - { name: ALTER GROUP,                  href: alter-group.md,                when: feature_user_and_group }
 - { name: ALTER TABLE,                  href: alter_table.md,                when: feature_map_tables }
+- { name: ALTER TOPIC,                  href: alter_topic.md,                when: feature_topic_control_plane }
 - { name: ALTER USER,                   href: alter-user.md,                 when: feature_user_and_group }
 - { name: CREATE GROUP,                 href: create-group.md,               when: feature_user_and_group }
 - { name: CREATE TABLE,                 href: create_table.md }
+- { name: CREATE TOPIC,                 href: create_topic.md,               when: feature_topic_control_plane }
 - { name: CREATE USER,                  href: create-user.md,                when: feature_user_and_group }
 - { name: DECLARE,                      href: declare.md }
 - { name: DELETE,                       href: delete.md,                     when: feature_map_tables }
 - { name: DISCARD,                      href: discard.md }
 - { name: DROP GROUP,                   href: drop-group.md,                 when: feature_user_and_group }
 - { name: DROP TABLE,                   href: drop_table.md }
+- { name: DROP TOPIC,                   href: drop_topic.md,                 when: feature_topic_control_plane }
 - { name: DROP USER,                    href: drop-user.md,                  when: feature_user_and_group }
 - { name: GROUP BY,                     href: group_by.md }
 - { name: EXPORT и IMPORT,              href: export_import.md,              when: feature_mapreduce }