Yql autopartitioning docs (#9383)

Co-authored-by: Ivan Blinkov <[email protected]>

Author: niksaveliev

ydb/docs/ru/core/yql/reference/yql-core/syntax/alter-topic.md

@@ -27,12 +27,16 @@ ALTER TOPIC topic_path SET (option = value[, ...]);
 Параметры топика:
 
 * `metering_mode` — способ метеринга ресурсов (`RESERVED_CAPACITY` - по выделенным ресурсам или `REQUEST_UNITS` - по фактическому использованию). Актуально для топиков в serverless базах данных. Тип значения - `String`.
-* `min_active_partitions` — минимальное количество активных партиций топика. Автоматическая балансировка нагрузки не будет уменьшать количество активных партиций ниже этого количества. Тип значения — `integer`, значение по умолчанию — `1`.
+* `min_active_partitions` — минимальное количество активных партиций топика. [Автопартиционирование](../../../../concepts/topic#autopartitioning) не будет уменьшать количество активных партиций ниже этого значения. Тип — `integer`, значение по умолчанию — `1`.
+* `max_active_partitions` — максимальное количество активных партиций топика. [Автопартиционирование](../../../../concepts/topic#autopartitioning) не будет увеличивать количество активных партиций выше этого значения. Тип — `integer`, по умолчанию равно `min_active_partitions`.
 * `retention_period` — время хранения данных в топике. Тип значения — `Interval`, значение по умолчанию — `18h`.
 * `retention_storage_mb` — ограничение на максимальное место на диске, занимаемое данными топика. При превышении этого значения старые данные будут удаляться, как по retention. Тип значения — `integer`, значение по умолчанию — `0` (не ограничено).
-* `partition_count_limit` — максимальное количество активных партиций топика. Тип значения — `integer`, значение по умолчанию: `0` (не ограничено).
 * `partition_write_burst_bytes` — размер запаса квоты на запись в партицию на случай всплесков записи. При выставлении в `0` фактическое значение write_burst принимается равным значению квоты (что позволяет всплески записи длительностью до 1 секунды). Тип значения — `integer`, значение по умолчанию: `0`.
 * `partition_write_speed_bytes_per_second` — максимальная разрешенная скорость записи в 1 партицию. Если поток записи в партицию превысит это значение, запись будет квотироваться. Тип значения — `integer`, значение по умолчанию — `2097152` (2 МБ).
+* `auto_partitioning_strategy` — [режим автопартиционирования](../../../../concepts/topic#autopartitioning_modes).
+Допустимые значения: `paused`, `scale_up`, значение по умолчанию — `disabled`.
+* `auto_partitioning_up_utilization_percent` — определяет порог загрузки партиции в процентах от максимальной скорости записи, при достижении которого будет инициировано автоматическое **увеличение** числа партиций. Тип значения — `integer`, значение по умолчанию — `80`.
+* `auto_partitioning_stabilization_window` — определяет временной интервал, в течение которого уровень нагрузки должен оставаться выше установленного порога (`auto_partitioning_up_utilization_percent`), прежде чем будет выполнено автоматическое увеличение количества партиций. Тип значения — `Interval`, значение по умолчанию — `5m`.
 
 {% if feature_topic_codecs %}
 
@@ -49,6 +53,34 @@ ALTER TOPIC `my_topic` SET (
 );
 ```
 
+### Включение и приостановка автопартиционирования {#autopartitioning}
+
+Следующая команда включает [автопартиционирование](../../../../concepts/topic#autopartitioning):
+
+```yql
+ALTER TOPIC `my_topic` SET (
+    min_active_partitions = 1,
+    max_active_partitions = 5,
+    auto_partitioning_strategy = 'scale_up'
+);
+```
+
+Следующая команда ставит [автопартиционирование](../../../../concepts/topic#autopartitioning) на паузу:
+
+```yql
+ALTER TOPIC `my_topic` SET (
+    auto_partitioning_strategy = 'paused'
+);
+```
+
+Следующая команда снимает [автопартиционирование](../../../../concepts/topic#autopartitioning) с паузы:
+
+```yql
+ALTER TOPIC `my_topic` SET (
+    auto_partitioning_strategy = 'scale_up'
+);
+```
+
 {% if feature_topic_settings_reset %}
 
 ### Сбросить параметры топика {#reset-topic}
@@ -68,7 +100,7 @@ ALTER TOPIC topic_path RESET (option[, option2, ...]);
 ```yql
 ALTER TOPIC `my_topic` RESET (
     min_active_partitions,
-    partition_count_limit
+    max_active_partitions
 );
 ```
 

ydb/docs/ru/core/yql/reference/yql-core/syntax/create-topic.md

@@ -30,12 +30,16 @@ CREATE TOPIC topic_path (
 Параметры топика:
 
 * `metering_mode` — способ метеринга ресурсов (`RESERVED_CAPACITY` - по выделенным ресурсам или `REQUEST_UNITS` - по фактическому использованию). Актуально для топиков в serverless базах данных. Тип значения - `String`.
-* `min_active_partitions` — минимальное количество активных партиций топика. Автоматическая балансировка нагрузки не будет уменьшать количество активных партиций ниже этого количества. Тип значения — `integer`, значение по умолчанию — `1`.
+* `min_active_partitions` — минимальное количество активных партиций топика. [Автопартиционирование](../../../../concepts/topic#autopartitioning) не будет уменьшать количество активных партиций ниже этого количества. Тип значения — `integer`, значение по умолчанию — `1`.
+* `max_active_partitions` — максимальное количество активных партиций топика. [Автопартиционирование](../../../../concepts/topic#autopartitioning) не будет увеличивать количество активных партиций выше этого количества. Тип значения — `integer`, по умолчанию равно `min_active_partitions`.
 * `retention_period` — время хранения данных в топике. Тип значения — `Interval`, значение по умолчанию — `18h`.
 * `retention_storage_mb` — ограничение на максимальное место на диске, занимаемое данными топика. При превышении этого значения старые данные будут удаляться, как по retention. Тип значения — `integer`, значение по умолчанию — `0` (не ограничено).
-* `partition_count_limit` — максимальное количество активных партиций топика. Тип значения — `integer`, значение по умолчанию: `0` (не ограничено).
 * `partition_write_burst_bytes` — размер запаса квоты на запись в партицию на случай всплесков записи. При выставлении в `0` фактическое значение write_burst принимается равным значению квоты (что позволяет всплески записи длительностью до 1 секунды). Тип значения — `integer`, значение по умолчанию: `0`.
 * `partition_write_speed_bytes_per_second` — максимальная разрешенная скорость записи в 1 партицию. Если поток записи в партицию превысит это значение, запись будет квотироваться. Тип значения — `integer`, значение по умолчанию — `2097152` (2 МБ).
+* `auto_partitioning_strategy` — [режим автопартиционирования](../../../../concepts/topic#autopartitioning_modes).
+Допустимые значения: `disabled`, `paused`, `scale_up`, значение по умолчанию — `disabled`.
+* `auto_partitioning_up_utilization_percent` — определяет порог загрузки партиции в процентах от максимальной скорости записи, при достижении которого будет инициировано автоматическое **увеличение** числа партиций. Тип значения — `integer`, значение по умолчанию — `80`.
+* `auto_partitioning_stabilization_window` — определяет временной интервал, в течение которого уровень нагрузки должен оставаться выше установленного порога (`auto_partitioning_up_utilization_percent`), прежде чем будет выполнено автоматическое увеличение количества партиций. Тип значения — `Interval`, значение по умолчанию — `5m`.
 
 {% if feature_topic_codecs %}