Description of the parameter AUTO_PARTITIONING_PARTITION_SIZE_MB (#7975)

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

3 files changed, 26 insertions, 15 deletions

diff --git a/ydb/docs/en/core/concepts/_includes/datamodel/table.md b/ydb/docs/en/core/concepts/_includes/datamodel/table.md
index 26377f5bb0a..6b4dc337fcb 100644
--- a/ydb/docs/en/core/concepts/_includes/datamodel/table.md
+++ b/ydb/docs/en/core/concepts/_includes/datamodel/table.md
@@ -14,7 +14,9 @@ Often, when you design a table schema, you already have a set of fields, which c
 
 A database table can be sharded by primary key value ranges. Each shard of the table is responsible for a specific range of primary keys. Key ranges served by different shards do not overlap. Different table shards can be served by different distributed database servers (including ones in different locations). They can also move independently between servers to enable rebalancing or ensure shard operability if servers or network equipment goes offline.
 
-If there is not a lot of data or load, the table may consist of a single shard. As the amount of data served by the shard or the load on the shard grows, {{ ydb-short-name }} automatically splits this shard into two shards. The data is split by the median value of the primary key if the shard size exceeds the threshold. If partitioning by load is used, the shard first collects a sample of the requested keys (that can be read, written, and deleted) and, based on this sample, selects a key for partitioning to evenly distribute the load across new shards. So in the case of load-based partitioning, the size of new shards may significantly vary.
+If there is not a lot of data or load, the table may consist of a single shard. As the amount of data served by the shard or the load on the shard grows, {{ ydb-short-name }} automatically splits this shard into two shards. The data is split by the median value of the primary key if the shard size exceeds the [AUTO_PARTITIONING_PARTITION_SIZE_MB](#auto_partitioning_partition_size_mb) threshold. If partitioning by load is used, the shard first collects a sample of the requested keys (that can be read, written, and deleted) and, based on this sample, selects a key for partitioning to evenly distribute the load across new shards. So in the case of load-based partitioning, the size of new shards may significantly vary.
+
+Regardless of the value of the parameter [AUTO_PARTITIONING_PARTITION_SIZE_MB](#auto_partitioning_partition_size_mb), the system makes splits and merges 2 GB in size if this threshold is exceeded.
 
 The size-based shard split threshold and automatic splitting can be configured (enabled/disabled) individually for each database table.
 
diff --git a/ydb/docs/en/core/concepts/datamodel/_includes/table.md b/ydb/docs/en/core/concepts/datamodel/_includes/table.md
index 77f3933c9c0..2c0fb6f79cc 100644
--- a/ydb/docs/en/core/concepts/datamodel/_includes/table.md
+++ b/ydb/docs/en/core/concepts/datamodel/_includes/table.md
@@ -70,7 +70,9 @@ When choosing the minimum number of partitions, it makes sense to consider that
 * Type: `Uint64`.
 * Default value: `2000 MB` ( `2 GB` ).
 
-Partition size threshold in MB. If exceeded, a shard splits. Takes effect when the [`AUTO_PARTITIONING_BY_SIZE`](#auto_partitioning_by_size) mode is enabled.
+The desired partition size threshold in megabytes. Recommended values range from `10 MB` to `2000 MB`. If this threshold is exceeded, a shard may split. This setting takes effect when the [`AUTO_PARTITIONING_BY_SIZE`](#auto_partitioning_by_size) mode is enabled.
+
+This value serves as a recommendation for partitioning. Partitioning may sometimes not occur even if the configured size is exceeded.
 
 #### AUTO_PARTITIONING_MIN_PARTITIONS_COUNT {#auto_partitioning_min_partitions_count}
 
diff --git a/ydb/docs/ru/core/concepts/datamodel/_includes/table.md b/ydb/docs/ru/core/concepts/datamodel/_includes/table.md
index 84a3c9ba2f1..b09d96d9951 100644
--- a/ydb/docs/ru/core/concepts/datamodel/_includes/table.md
+++ b/ydb/docs/ru/core/concepts/datamodel/_includes/table.md
@@ -28,17 +28,22 @@ CREATE TABLE article (
 
 ### Партиционирование строковой таблицы {#partitioning_row_table}
 
-Строковая таблица в БД может быть шардирована по диапазонам значений первичного ключа. Каждый шард таблицы отвечает за свой диапазон первичных ключей. Диапазоны ключей, обслуживаемых разными шардами, не пересекаются. Различные шарды таблицы могут обслуживаться разными серверами распределенной БД (в том числе расположенными в разных локациях), а также могут независимо друг от друга перемещаться между серверами для перебалансировки или поддержания работоспособности шарда при отказах серверов или сетевого оборудования.
+Строковая таблица в БД может быть партиционированна по диапазонам значений первичного ключа. Каждая партиция таблицы отвечает за свой диапазон первичных ключей. Диапазоны ключей, обслуживаемых разными партициями, не пересекаются. Различные партиции таблицы могут обслуживаться разными серверами распределенной БД (в том числе расположенными в разных локациях), а также могут независимо друг от друга перемещаться между серверами для перебалансировки или поддержания работоспособности партиции при отказах серверов или сетевого оборудования.
 
-При малом объеме данных или небольшой нагрузке таблица может состоять из одного шарда. При росте объема данных, обслуживаемых шардом, или нагрузки на шард, {{ ydb-short-name }} автоматически разбивает его на два. Разбиение происходит по медианному значению первичного ключа, если размер шарда превышает порог. В случае разбиения по нагрузке шард сначала собирает сэмпл запрашиваемых ключей (читаемых, записываемых и удаляемых), и на основании этого сэмпла выбирает для разбиения такой ключ, чтоб нагрузка распределилась поровну между новыми шардами. Таким образом в случае разбиения по нагрузке новые шарды могут иметь существенно отличающийся размер.
+При малом объеме данных или небольшой нагрузке таблица может состоять из одной партиции. При росте объема данных партиции или нагрузки на партицию, {{ ydb-short-name }} автоматически разделяет её на две:
 
-Порог разделения шарда по размеру и включение/выключение автоматического разделения могут быть настроены индивидуально для каждой таблицы базы данных.
+- Если объем данных превышает [порог по размеру партиции](#auto_partitioning_by_size), то разделение происходит по медианному значению первичного ключа.
+- Если [увеличилась нагрузка](#auto_partitioning_by_load), то партиция сначала собирает сэмпл запрашиваемых ключей (читаемых, записываемых и удаляемых) и на основании этого сэмпла выбирает для разделения такой ключ, чтоб нагрузка распределилась поровну между новыми партициями. Таким образом в случае разделения по нагрузке новые партиции могут иметь существенно отличающийся размер.
 
-Помимо автоматического разделения предоставляется возможность создать пустую таблицу с предопределенным количеством шардов. При этом можно вручную задать точные границы разделения ключей по шардам или указать равномерное разделение на предопределенное количество шардов. В этом случае границы создадутся по первой компоненте первичного ключа. Равномерное распределение можно указать для таблиц, у которых первая компонента первичного ключа — целое число `Uint64` или `Uint32`.
+Порог разделения партиции по размеру и включение/выключение автоматического разделения могут быть настроены индивидуально для каждой таблицы базы данных.
 
-Параметры партиционирования относятся к самой таблице, но не к построенным на ее данных вторичным индексам. Каждый индекс обслуживается своим набором шардов, и решения о разделении или объединении его партиций принимаются независимо на основании настроек по умолчанию. В будущем эти настройки могут быть сделаны доступными пользователям, аналогично настройкам основной таблицы.
+Независимо от значения параметра [AUTO_PARTITIONING_PARTITION_SIZE_MB](#auto_partitioning_by_size), {{ ydb-short-name }} выполняет разделение и объединение партиций, ориентируясь на размер в 2000 MB. При этом {{ ydb-short-name }} не ограничивает пользовательские настройки, а работает параллельно с ними. Например, если задать [размер партиции](#auto_partitioning_by_size) 100 MB и [ограничение](#auto_partitioning_max_partitions_count) на 10 партиций, то, когда у таблицы станет 10 партиций по 100 MB, она перестанет делиться, и размер партиций начнет увеличиваться. Когда размер какой-либо партиции превысит 2000 MB, она разделится, и в таблице станет 11 партиций. Если размер двух соседних партиций уменьшится до 1000 MB, они объединятся, и в таблице снова станет 10 партиций.
 
-Характерное время операции разделения или объединения — порядка 500 мс. На это время вовлеченные в операцию данные становятся кратковременно недоступны для чтения и записи. Специализированные методы-обертки в {{ ydb-short-name }} SDK автоматически выполняют повторные попытки при получении информации о том, что шард находится в состоянии разделения или объединения, не поднимая ее до уровня приложения. Стоит отметить, что если система по каким-то причинам перегружена (например, из-за общей нехватки CPU или пропускной способности выделенных базе дисковых ресурсов) то операции разделения и объединения могут длиться дольше.
+Помимо автоматического разделения, предоставляется возможность создать пустую таблицу с заданным количеством партиций. При этом можно вручную задать точные границы разделения ключей по партициям или указать равномерное распределение на заданное количество партиций. В последнем случае границы будут созданы по первой компоненте первичного ключа. Равномерное распределение можно указать для таблиц, у которых первая компонента первичного ключа является целым числом с типом данных `Uint64` или `Uint32`.
+
+Параметры партиционирования относятся только к самой таблице, но не к вторичным индексам, построенным на её данных. Каждый индекс обслуживается своим набором партиций, и решения о разделении или объединении его партиций принимаются независимо, на основании настроек по умолчанию. В будущем эти настройки могут стать доступными пользователям, аналогично настройкам основной таблицы.
+
+Характерное время операции разделения или объединения составляет около 500 мс. В течение этого времени данные, вовлечённые в операцию, становятся кратковременно недоступны для чтения и записи. Специализированные методы-обёртки в {{ ydb-short-name }} SDK автоматически выполняют повторные попытки при обнаружении, что партиция находится в состоянии разделения или объединения, не поднимая эту информацию до уровня приложения. Важно отметить, что если система по каким-либо причинам перегружена (например, из-за нехватки CPU или пропускной способности выделенных дисковых ресурсов), операции разделения и объединения могут занимать больше времени.
 
 В схеме данных определяются следующие параметры партиционирования таблицы:
 
@@ -54,7 +59,7 @@ CREATE TABLE article (
 * Тип: `Enum` (`ENABLED`, `DISABLED`).
 * Значение по умолчанию: `DISABLED`.
 
-Режим автоматического партиционирования по нагрузке. Если в течение нескольких десятков секунд шард потребляет более 50% CPU, то он ставится в очередь на разделение (split). Если в течение часа суммарная нагрузка на два или более соседних шарда утилизировала менее 35% одного ядра CPU, то они ставятся в очередь на объединение (merge).
+Режим автоматического партиционирования по нагрузке. Если в течение нескольких десятков секунд партиция потребляет более 50% CPU, то он ставится в очередь на разделение (split). Если в течение часа суммарная нагрузка на два или более соседних партиций утилизировала менее 35% одного ядра CPU, то они ставятся в очередь на объединение (merge).
 
 Выполнение операций разделения или объединения само по себе утилизирует CPU, и занимает время. Поэтому, при работе с плавающей нагрузкой рекомендуется вместе с включением данного режима устанавливать отличное от 1 значение параметра минимального количество партиций [AUTO_PARTITIONING_MIN_PARTITIONS_COUNT](#auto_partitioning_min_partitions_count), чтобы спады нагрузки не приводили к снижению количества партиций ниже необходимого, и не было потребности их заново делить при появлении нагрузки.
 
@@ -65,7 +70,9 @@ CREATE TABLE article (
 * Тип: `Uint64`.
 * Значение по умолчанию: `2000 MB` ( `2 ГБ` ).
 
-Порог размера партиции в мегабайтах, при превышении которого шард будет разделен, имеет значение при включенном режиме [AUTO_PARTITIONING_BY_SIZE](#auto_partitioning_by_size).
+Желаемый порог размера партиции в мегабайтах. Рекомендуемые значения варьируются от `10 MB` до `2000 MB`. Если этот порог превышается, партиция может быть разделена.
+Указанное значение служит лишь рекомендацией для разделения. Возможны ситуации, когда разделение не произойдёт, даже если указанный размер превышен.
+Эта настройка применяется, когда включён режим [`AUTO_PARTITIONING_BY_SIZE`](#auto_partitioning_by_size).
 
 #### AUTO_PARTITIONING_MIN_PARTITIONS_COUNT
 
@@ -101,16 +108,16 @@ CREATE TABLE article (
 
 ### Чтение с реплик {#read_only_replicas}
 
-При выполнении запросов в {{ ydb-short-name }} фактическое выполнение запроса к каждому шарду осуществляется в единой точке, обслуживающей протокол распределенных транзакций. Но благодаря хранению данных на разделяемом хранилище возможен запуск одного или нескольких фолловеров шарда, без выделения дополнительного места на сторадже — данные уже хранятся реплицированно и возможно обслуживание более одного читателя (но писатель при этом все еще в каждый момент строго один).
+При выполнении запросов в {{ ydb-short-name }} фактическое выполнение запроса к каждой партиции осуществляется в единой точке, обслуживающей протокол распределенных транзакций. Но благодаря хранению данных на разделяемом хранилище возможен запуск одного или нескольких фолловеров партиции, без выделения дополнительного места на сторадже — данные уже хранятся реплицированно и возможно обслуживание более одного читателя (но писатель при этом все еще в каждый момент строго один).
 
 Применение чтения с фолловеров дает следующие возможности:
 
 * Обслуживать клиентов, критичных к минимальным задержкам, недостижимым иными способами в мульти-ДЦ кластере. Достигается за счет приближения точки выполнения запроса к точке задания запроса, что отсекает задержку на меж-ДЦ пересылки. В результате, сохраняя все гарантии мульти-ДЦ кластера по надежности хранения, отвечать на точечные читающие запросы за единицы миллисекунд.
-* Обслуживать читающие запросов с фолловеров без влияния на модифицирующие запросы, выполняющиеся на шарде. Это может быть полезно как для изоляции разных сценариев, так и для увеличения пропускной способности партиции.
+* Обслуживать читающие запросов с фолловеров без влияния на модифицирующие запросы, выполняющиеся на партиции. Это может быть полезно как для изоляции разных сценариев, так и для увеличения пропускной способности партиции.
 * Продолжать обслуживание при переездах лидера партиции (как штатной при балансировке, так и при сбоях). Позволяет переживать процессы в кластере без влияния на читающих клиентов.
-* В целом повышать предел производительности чтения шардов, если множество читающих запросов попадают на одни и те же ключи.
+* В целом повышать предел производительности чтения партиций, если множество читающих запросов попадают на одни и те же ключи.
 
-В схеме данных таблицы можно указать необходимость запуска реплик для чтения для каждого шарда таблицы. Обращения к репликам для чтения (фолловерам) типично происходят не покидая сети датацентра, что позволяет обеспечить время ответа в единицы миллисекунд:
+В схеме данных таблицы можно указать необходимость запуска реплик для чтения для каждой партиции таблицы. Обращения к репликам для чтения (фолловерам) типично происходят не покидая сети датацентра, что позволяет обеспечить время ответа в единицы миллисекунд:
 
 | Имя параметра | Описание | Тип | Допустимые значения | Возможность<br/>изменения | Возможность<br/>сброса |
 | ------------- | --------- | --- | ------------------- | --------------------- | ------------------ |
@@ -120,7 +127,7 @@ CREATE TABLE article (
 
 Кроме состояния данных в сторадже на фолловеров отправляется и поток обновлений с лидера. Обновления отправляются в реальном времени, сразу после коммита в лог. Но отправляются асинхронно, что приводит к некоторой задержке применения обновлений на фолловерах относительно их коммита на лидере (типично в десятки миллисекунд, но может увеличиваться в случае проблем связности в кластере). В связи с этим, чтение с фолловеров обеспечивается только в [режиме транзакций](../../transactions.md#modes) `StaleReadOnly()`.
 
-Если фолловеров несколько, то отставание их от лидера может различаться, т.е. хотя каждый фолловер каждого из шардов сохраняет внутреннюю консистентность, между разными шардами могут наблюдаться артефакты. Код приложения должен быть к этому готов. По этой же причине на данный момент невозможно и выполнение с фолловеров кроссшардовых транзакций.
+Если фолловеров несколько, то отставание их от лидера может различаться, т.е. хотя каждый фолловер каждой из партиции сохраняет внутреннюю консистентность, между разными партициями могут наблюдаться артефакты. Код приложения должен быть к этому готов. По этой же причине на данный момент невозможно и выполнение с фолловеров кроссшардовых транзакций.
 
 ### Автоматическое удаление устаревших данных (TTL) {#ttl}