Some fixes for table patitioning (KIKIMR-13934, YCDOCS-4091)

ref:e2640b1611a45604cc696e180f7a6544206522c7

1 files changed, 10 insertions, 12 deletions

diff --git a/ydb/docs/ru/core/concepts/_includes/datamodel/table.md b/ydb/docs/ru/core/concepts/_includes/datamodel/table.md
index 6ccb4b2879..a765201b0d 100644
--- a/ydb/docs/ru/core/concepts/_includes/datamodel/table.md
+++ b/ydb/docs/ru/core/concepts/_includes/datamodel/table.md
@@ -18,15 +18,15 @@ YDB использует типы данных [YQL]{% if audience != "external"
 ### Партиционирование таблиц {#partitioning}
 Таблица в БД может быть шардирована по диапазонам значений первичного ключа. Каждый шард таблицы отвечает за свой  диапазон первичных ключей. Диапазоны ключей, обслуживаемых разными шардами, не пересекаются. Различные шарды таблицы могут обслуживаться разными серверами распределенной БД (в том числе расположенными в разных локациях), а также могут независимо друг от друга перемещаться между серверами для перебалансировки или поддержания работоспособности шарда при отказах серверов или сетевого оборудования.
 
-При малом объеме данных или небольшой нагрузке таблица может состоять из одного шарда. При росте объема данных, обслуживаемых шардом, или нагрузки на шард, YDB автоматически разбивает его на два. Разбиение происходит по медианному значению первичного ключа.
+При малом объеме данных или небольшой нагрузке таблица может состоять из одного шарда. При росте объема данных, обслуживаемых шардом, или нагрузки на шард, YDB автоматически разбивает его на два. Разбиение происходит по медианному значению первичного ключа, если размер шарда превышает порог. В случае разбиения по нагрузке шард сначала собирает сэмпл запрашиваемых ключей (читаемых, записываемых и удаляемых), и на основании этого сэмпла выбирает для разбиения такой ключ, чтоб нагрузка распределилась поровну между новыми шардами. Таким образом в случае разбиения по нагрузке новые шарды могут иметь существенно отличающийся размер.
 
-Порог разделения шарда и включение/выключение автоматического разделения могут быть настроены индивидуально для каждой таблицы базы данных.
+Порог разделения шарда по размеру и включение/выключение автоматического разделения могут быть настроены индивидуально для каждой таблицы базы данных.
 
-Помимо автоматического разделения предоставляется возможность создать пустую таблицу с предопределённым количеством шардов. При этом можно вручную задать точные границы разделения ключей по шардам или указать равномерное разделение на предопределённое количество шардов. В этом случае границы создадутся по первой компоненте первичного ключа. Равномерное распределение можно указать для таблиц, у которых первая компонента первичного ключа — целое число.
+Помимо автоматического разделения предоставляется возможность создать пустую таблицу с предопределённым количеством шардов. При этом можно вручную задать точные границы разделения ключей по шардам или указать равномерное разделение на предопределённое количество шардов. В этом случае границы создадутся по первой компоненте первичного ключа. Равномерное распределение можно указать для таблиц, у которых первая компонента первичного ключа — целое число Uint64 или Uint32.
 
-Параметры партиционирования относятся как к самой таблице, так и построенным на её данных вторичным индексам. Каждый индекс обслуживается своим набором шардов, и решения о разделении или объединении его партиций принимаются независимо на основании тех же параметров.
+Параметры партиционирования относятся к самой таблице, но не к построенным на её данных вторичным индексам. Каждый индекс обслуживается своим набором шардов, и решения о разделении или объединении его партиций принимаются независимо на основании настроек по умолчанию. В будущем эти настройки могут быть сделаны доступными пользователям, аналогично настройкам основной таблицы.
 
-Одна операция разделения или объединения занимает несколько секунд, и на это время вовлеченные в операцию данные становятся недоступны для чтения и записи. Спциализированные методы-обертки в YDB SDK автоматически выполняют повторные попытки при получении информации о том что шард находится в состоянии разделения или объединения, не поднимая её до уровня приложения.
+Характерное время операции разделения или объединения - порядка 500 милисекунд. На это время вовлеченные в операцию данные становятся кратковременно недоступны для чтения и записи. Специализированные методы-обертки в YDB SDK автоматически выполняют повторные попытки при получении информации о том, что шард находится в состоянии разделения или объединения, не поднимая её до уровня приложения. Стоит отметить, что если система по каким-то причинам перегружена (например, из-за общей нехватки CPU или пропускной способности выделенных базе дисковых ресурсов) то операции разделения и объединения могут длиться дольше. 
 
 В схеме данных определяются следующие параметры партиционирования таблицы:
 
@@ -35,23 +35,25 @@ YDB использует типы данных [YQL]{% if audience != "external"
 * Тип: Enum (`ENABLED`, `DISABLED`)
 * Значение по-умолчанию: `ENABLED`
 
-Режим автоматического партиционирования по размеру партиции. Если размер партиции превысил значение, заданное параметром [`AUTO_PARTITIONING_PARTITION_SIZE_MB`](#auto_partitioning_partition_size_mb), то она встает в очередь на разделение (split). Если суммарный размер двух соседних партиции меньше 50% от значения параметра [`AUTO_PARTITIONING_PARTITION_SIZE_MB`](#auto_partitioning_partition_size_mb), то они встают в очередь на объединение (merge).
+Режим автоматического партиционирования по размеру партиции. Если размер партиции превысил значение, заданное параметром [`AUTO_PARTITIONING_PARTITION_SIZE_MB`](#auto_partitioning_partition_size_mb), то она встает в очередь на разделение (split). Если суммарный размер двух или более соседних партиции меньше 50% от значения параметра [`AUTO_PARTITIONING_PARTITION_SIZE_MB`](#auto_partitioning_partition_size_mb), то они встают в очередь на объединение (merge).
 
 #### AUTO_PARTITIONING_BY_LOAD
 
 * Тип: 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), чтобы спады нагрузки не приводили к снижению количества партиций ниже необходимого, и не было потребности их заново делить при появлении нагрузки.
 
+При выборе минимального количества партиций имеет смысл руководствоваться соображениями, что одна партиция таблицы может находиться только на одном сервере и использовать не более 1 ядра CPU для операций изменения данных. Исходя из этого, для таблицы на которой может ожидаться высокая нагрузка, можно указывать минимальное количество партиций не менее количества узлов (серверов), а лучше порядка количества ядер CPU, выделенных базе.
+
 #### AUTO_PARTITIONING_PARTITION_SIZE_MB
 
 * Тип: Uint64
 * Значение по-умолчанию: 2000 MB ( 2ГБ )
 
-Предпочитаемый размер каждой партиции в мегабайтах, имеет значение при включенном режиме [`AUTO_PARTITIONING_BY_SIZE`](#auto_partitioning_by_size).
+Порог размера партиции в мегабайтах, при превышении которого шард будет разделён, имеет значение при включенном режиме [`AUTO_PARTITIONING_BY_SIZE`](#auto_partitioning_by_size).
 
 #### AUTO_PARTITIONING_MIN_PARTITIONS_COUNT
 
@@ -76,8 +78,6 @@ YDB использует типы данных [YQL]{% if audience != "external"
 
 При включенном автоматическом партиционировании необходимо также не забыть установить корректное значение параметра [`AUTO_PARTITIONING_MIN_PARTITIONS_COUNT`](#auto_partitioning_min_partitions_count), чтобы все партиции не объединились в одну сразу после создания таблицы.
 
-В настоящее время не поддерживается возможность задания начального количества партиций для вторичных индексов.
-
 #### PARTITION_AT_KEYS
 
 * Тип: Expression
@@ -87,8 +87,6 @@ YDB использует типы данных [YQL]{% if audience != "external"
 
 При включенном автоматическом партиционировании необходимо также не забыть установить корректное значение параметра [`AUTO_PARTITIONING_MIN_PARTITIONS_COUNT`](#auto_partitioning_min_partitions_count), чтобы все партиции не объединились в одну сразу после создания таблицы.
 
-В настоящее время не поддерживается возможность задания начального разделения партиций по ключам для вторичных индексов.
-
 ### Чтение с реплик {#read_only_replicas}
 При выполнении запросов в YDB фактическое выполнение запроса к каждому шарду осуществляется в единой точке, обслуживающей протокол распределенных транзакций. Но благодаря хранению данных на разделяемом хранилище возможен запуск одного или нескольких фолловеров шарда, без выделения дополнительного места на сторадже - данные уже хранятся реплицированного и возможно обслуживание более одного читателя (но писатель при этом всё еще в каждый момент строго один).