Topics autopartitioning (#9243)

Co-authored-by: Ivan Blinkov <ivan@ydb.tech>

Author: ElenaAfina

ydb/docs/ru/core/concepts/topic.md

@@ -8,7 +8,7 @@
 
 * Гарантиями at-least-once при чтении сообщений подписчиками.
 * Гарантиями exactly-once при публикации сообщений (дедупликация сообщений).
-* Гарантиями последовательной обработки сообщений ([FIFO](https://en.wikipedia.org/wiki/Message_queue))), опубликованных с одинаковым [идентификатором источника](#producer-id).
+* Гарантиями последовательной обработки сообщений ([FIFO](https://en.wikipedia.org/wiki/Message_queue)), опубликованных с одинаковым [идентификатором источника](#producer-id).
 * Масштабирование пропускной способности передачи сообщений, публикуемых с разными идентификаторами последовательности.
 
 ## Сообщения {#message}
@@ -27,19 +27,64 @@
 
 {% endnote %}
 
+Партиции бывают двух видов:
+
+- **Активные.** Все партиции по умолчанию, в них возможны как запись, так и чтение.
+- **Неактивные.** Из них можно только читать. Неактивные партиции появляются после разделения партиции при включенном [автопартиционировании](#autopartitioning). Неактивные партиции удаляются автоматически, когда все сообщения из такой партиции удалены по истечении времени хранения.
+
 ### Смещение (offset) {#offset}
 
 Все сообщения внутри партиции имеют уникальный порядковый номер, называемый `смещением` (offset). Смещение монотонно возрастает при записи новых сообщений.
 
+## Автопартиционирование {#autopartitioning}
+
+Количество партиций топика и их пропускная способность задаются при создании топика и определяют общую пропускную способность топика на запись. Если максимальная требуемая скорость записи в топик неизвестна при его создании или будет меняться со временем, можно воспользоваться автопартиционированием для динамического масштабирования топика. Если на топике включено автопартиционирование вверх, то количество партиций в таком топике автоматически увеличивается при возрастании скорости записи (подробнее см. [Режимы автопартиционирования](#autopartitioning_modes)).
+
+### Гарантии {#autopartitioning_guarantee}
+
+1. SDK и сервер обеспечивают гарантии записи exactly-once в случае разделения партиций. Это означает, что любое сообщение будет записано либо в родительскую партицию, либо в одну из дочерних. Сообщение не может быть записано одновременно и в родительскую, и в дочернюю партиции. Более того, сообщение не может быть записано в одну партицию несколько раз.
+2. SDK и сервер обеспечивают порядок чтения. Сначала данные будут вычитаны из родительских партиций, и только затем — из дочерних.
+3. Таким образом, гарантии exactly-once записи и порядка чтения продолжают выполняться для конкретного [идентификатора источника (producer-id)](#producer-id).
+
+### Режимы автопартиционирования {#autopartitioning_modes}
+
+Для любого топика возможны следующие режимы автопартиционирования.
+
+#### Выключено (DISABLED)
+
+Автопартиционирование отключено. В этом случае число партиций остаётся неизменным, и автоматическое масштабирование не происходит.  
+
+Исходное количество партиции указывается при создании топика. При ручном изменении числа партиций в этом режиме добавляются новые партиции. Все ранее существовавшие партиции остаются активными.
+
+#### Увеличение (UP)
+
+На топике включено автопартиционирование «вверх», то есть при увеличении скорости записи количество партиций увеличивается. При уменьшении скорости записи количество партиций остаётся неизменным.
+
+Алгоритм увеличения числа партиций: если в течение заданного времени скорость записи в какую-то партицию превышает указанный порог (в % от максимальной скорости записи в партицию), эта партиция делится на две. Исходная партиция становится неактивной, и из неё можно только читать данные. Когда истечёт срок хранения сообщений в этой партиции и все сообщения будут удалены, сама партиция также будет удалена. Две новые дочерние партиции становятся активными, и в них возможны как чтение, так и запись.
+
+#### Пауза (PAUSED)
+
+Автопартиционирование на топике приостановлено. Автоматическое увеличение числа партиций не происходит. При необходимости можно снова включить режим увеличения числа партиций.
+
+Примеры YQL-запросов для перевода топика в различные режимы автопартиционирования можно посмотреть [здесь](../yql/reference/syntax/alter-topic.md#autopartitioning).
+
+### Ограничения {#autopartitioning_constraints}
+
+При использовании автопартиционирования действуют следующие ограничения:
+
+1. Если на топике включено автопартиционирование, его нельзя отключить, можно только приостановить.
+2. Если на топике включено автопартиционирование, то запись или чтение в такой топик по [протоколу Kafka API](../reference/kafka-api/index.md) невозможны.
+3. Автопартиционирование не может быть включено на топике с режимом хранения по месту.
+
 ## Источники и группы сообщений {#producer-id}
 
-Идентификатор источника, `producer_id`, и идентификатор группы сообщений, `message_group_id`, — это способ упорядочить набор сообщений. Порядок записанных сообщений сохраняется в пределах пар: <идентификатор источника, идентификатор группы сообщений>.
+Идентификатор источника, `producer_id`, и идентификатор группы сообщений, `message_group_id`, — это способ упорядочить набор сообщений. Порядок записанных сообщений сохраняется в пределах пар: `<producer_id, message_group_id>`.
 
 При первом использовании пара <идентификатор источника, группа сообщений> привязывается к [партиции](#partitioning) топика по алгоритму round-robin и все сообщения с этой парой попадают в одну и ту же партицию. Привязка удаляется при отсутствии новых сообщений, использующих этот идентификатор источника, в течение 14 дней.
 
 {% note warning %}
 
-Рекомендуемое максимальное количество пар <идентификатор источника, идентификатор группы сообщений> - до 100'000 на одну партицию за последние 14 дней.
+Рекомендуемое максимальное количество пар `<producer_id, message_group_id>` - до 100'000 на одну партицию за последние 14 дней.
 
 {% endnote %}
 

ydb/docs/ru/core/reference/kafka-api/constraints.md

@@ -9,4 +9,5 @@
 1. Не поддержаны DDL операции. Для осуществления DDL-операций пользуйтесь [{{ ydb-short-name }} SDK](../ydb-sdk/index.md) или [{{ ydb-short-name }} CLI](../ydb-cli/index.md).
 1. Не поддержана проверка схемы данных.
 1. Не поддержана проверка crc.
-1. Работа Kafka Connect поддерживается только в режиме одного процесса-исполнителя (standalone mode).
+1. Работа Kafka Connect поддерживается только в режиме одного процесса-исполнителя (standalone mode).
+1. Если на топике включено автопартиционирование, то в такой топик нельзя писать или читать по протоколу Kafka API.