partition by load

partition by load

ref:428aa11e2f3deb4ade6a173f12d1407b148b8b8c

3 files changed, 71 insertions, 11 deletions

diff --git a/build/mapping.conf.json b/build/mapping.conf.json
index d9e361ebc6a..3cedd9c6fbf 100644
--- a/build/mapping.conf.json
+++ b/build/mapping.conf.json
@@ -2924,6 +2924,12 @@
         "2786659959": "https://storage.mds.yandex.net/get-devtools-opensource/479623/2786659959", 
         "2786660754": "https://storage.mds.yandex.net/get-devtools-opensource/471749/2786660754", 
         "2786660966": "https://storage.mds.yandex.net/get-devtools-opensource/233854/2786660966", 
+        "2790068235": "https://storage.mds.yandex.net/get-devtools-opensource/250854/2790068235", 
+        "2790069100": "https://storage.mds.yandex.net/get-devtools-opensource/250854/2790069100", 
+        "2790069322": "https://storage.mds.yandex.net/get-devtools-opensource/479623/2790069322", 
+        "2790125584": "https://storage.mds.yandex.net/get-devtools-opensource/479623/2790125584", 
+        "2790127555": "https://storage.mds.yandex.net/get-devtools-opensource/250854/2790127555", 
+        "2790128197": "https://storage.mds.yandex.net/get-devtools-opensource/471749/2790128197", 
         "309054781": "https://storage.mds.yandex.net/get-devtools-opensource/250854/309054781", 
         "360916612": "https://storage.mds.yandex.net/get-devtools-opensource/233854/360916612", 
         "412716868": "https://storage.mds.yandex.net/get-devtools-opensource/233854/412716868", 
diff --git a/ya b/ya
index 6ee223ac482..62676d9d614 100755
--- a/ya
+++ b/ya
@@ -4,8 +4,8 @@ import sys
 import platform
 import json
 
-URLS = ["https://storage.mds.yandex.net/get-devtools-opensource/479623/d572a4841e2b2dcca14450f609635d2f"]
-MD5 = "d572a4841e2b2dcca14450f609635d2f"
+URLS = ["https://storage.mds.yandex.net/get-devtools-opensource/250854/f72b5038f470b6778aba44e5becd908b"]
+MD5 = "f72b5038f470b6778aba44e5becd908b"
 
 RETRIES = 5
 HASH_PREFIX = 10
diff --git a/ydb/docs/ru/core/concepts/_includes/datamodel/table.md b/ydb/docs/ru/core/concepts/_includes/datamodel/table.md
index 9b7a5439a4a..6ccb4b28799 100644
--- a/ydb/docs/ru/core/concepts/_includes/datamodel/table.md
+++ b/ydb/docs/ru/core/concepts/_includes/datamodel/table.md
@@ -18,22 +18,76 @@ YDB использует типы данных [YQL]{% if audience != "external"
 ### Партиционирование таблиц {#partitioning}
 Таблица в БД может быть шардирована по диапазонам значений первичного ключа. Каждый шард таблицы отвечает за свой  диапазон первичных ключей. Диапазоны ключей, обслуживаемых разными шардами, не пересекаются. Различные шарды таблицы могут обслуживаться разными серверами распределенной БД (в том числе расположенными в разных локациях), а также могут независимо друг от друга перемещаться между серверами для перебалансировки или поддержания работоспособности шарда при отказах серверов или сетевого оборудования.
 
-При малом объеме данных таблица может состоять из одного шарда. При росте объема данных, обслуживаемых шардом, YDB автоматически разбивает увеличившийся шард на два. Разбиение происходит по медианному значению первичного ключа и основано на объеме данных: при превышении заданного порога объемом данных шарда, происходит разделение шарда на два.
+При малом объеме данных или небольшой нагрузке таблица может состоять из одного шарда. При росте объема данных, обслуживаемых шардом, или нагрузки на шард, YDB автоматически разбивает его на два. Разбиение происходит по медианному значению первичного ключа.
 
 Порог разделения шарда и включение/выключение автоматического разделения могут быть настроены индивидуально для каждой таблицы базы данных.
 
 Помимо автоматического разделения предоставляется возможность создать пустую таблицу с предопределённым количеством шардов. При этом можно вручную задать точные границы разделения ключей по шардам или указать равномерное разделение на предопределённое количество шардов. В этом случае границы создадутся по первой компоненте первичного ключа. Равномерное распределение можно указать для таблиц, у которых первая компонента первичного ключа — целое число.
 
+Параметры партиционирования относятся как к самой таблице, так и построенным на её данных вторичным индексам. Каждый индекс обслуживается своим набором шардов, и решения о разделении или объединении его партиций принимаются независимо на основании тех же параметров.
+
+Одна операция разделения или объединения занимает несколько секунд, и на это время вовлеченные в операцию данные становятся недоступны для чтения и записи. Спциализированные методы-обертки в YDB SDK автоматически выполняют повторные попытки при получении информации о том что шард находится в состоянии разделения или объединения, не поднимая её до уровня приложения.
+
 В схеме данных определяются следующие параметры партиционирования таблицы:
 
-| Имя параметра | Описание  | Тип | Допустимые значения | Возможность изменения | Возможность сброса |
-| ------------- | --------- | --- | ------------------- | --------------------- | ------------------ |
-| ```AUTO_PARTITIONING_BY_SIZE```              | Режим автоматического партиционирования по размеру партиции  | Enum   | ```ENABLED```, ```DISABLED```                                 | Да                    | Нет                |
-| ```AUTO_PARTITIONING_PARTITION_SIZE_MB```    | Предпочитаемый размер каждой партиции, в мегабайтах          | Uint64 | Натуральные числа                                             | Да                    | Нет                |
-| ```AUTO_PARTITIONING_MIN_PARTITIONS_COUNT``` | Минимальное количество партиций, при достижении которого перестаёт работать автоматическое слияние партиций | Uint64 | Натуральные числа | Да                 | Нет                |
-| ```AUTO_PARTITIONING_MAX_PARTITIONS_COUNT``` | Максимальное количество партиций, при достижении которого перестаёт работать автоматическое разделение партиций | Uint64 | Натуральные числа | Да             | Нет                |
-| ```UNIFORM_PARTITIONS```                     | Количество партиций для равномерного начального разделения таблицы. Первая колонка первичного ключа должна иметь тип Uint64 или Uint32 | Uint64 | Натуральные числа | Нет | Нет    |
-| ```PARTITION_AT_KEYS```                      | Граничные значения ключей для начального разделения на партиции. Представляется списком граничных значений, разделенных запятыми и обрамленными в скобки. Каждое граничное значение может быть либо набором значений ключевых колонок (также разделенных запятыми и обрамленными в скобки), либо единичным значением, если указываются только значения первой ключевой колонки. Примеры: ```(100, 1000)```, ```((100, "abc"), (1000, "cde"))``` | Expression | | Нет | Нет |
+#### AUTO_PARTITIONING_BY_SIZE
+
+* Тип: 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_BY_LOAD
+
+* Тип: Enum (`ENABLED`, `DISABLED`)
+* Значение по-умолчанию: `DISABLED`
+
+Режим автоматического партиционирования по нагрузке. Если в течение нескольких десятков секунд шард потребляет более 50% CPU, то он ставится в очередь на разделение (split). Если в течение часа суммарная нагрузка на два соседних шарда утилизировала менее 35% CPU, то они ставятся в очередь на объединение (merge).
+
+Выполнение операций разделения или объединения само по себе утилизирует CPU, и занимает время. Поэтому, при работе с плавающей нагрузкой рекомендуется вместе с включением данного режима устанавливать отличное от 1 значение параметра минимального количество партиций [`AUTO_PARTITIONING_MIN_PARTITIONS_COUNT`](#auto_partitioning_min_partitions_count), чтобы спады нагрузки не приводили к снижению количества партиций ниже необходимого, и не было потребности их заново делить при появлении нагрузки.
+
+#### AUTO_PARTITIONING_PARTITION_SIZE_MB
+
+* Тип: Uint64
+* Значение по-умолчанию: 2000 MB ( 2ГБ )
+
+Предпочитаемый размер каждой партиции в мегабайтах, имеет значение при включенном режиме [`AUTO_PARTITIONING_BY_SIZE`](#auto_partitioning_by_size).
+
+#### AUTO_PARTITIONING_MIN_PARTITIONS_COUNT
+
+* Тип: Uint64
+* Значение по-умолчанию: 1
+
+Объединение партиций (merge) производится только в том случае, если их фактическое количество превышает заданное этим параметром значение. При использовании режима автоматического партиционирования по нагрузке рекомендуется устанавливать отличное от 1 значение данного параметра, чтобы периодический спад нагрузки не приводил к снижению количества партиций ниже необходимого.
+
+#### AUTO_PARTITIONING_MAX_PARTITIONS_COUNT
+
+* Тип: Uint64
+* Значение по-умолчанию: 50
+
+Разделение партиций (split) производится только в том случае, если их количество не превышает заданное этим параметром значение. При любых включенных режимах автоматического партиционирования рекомендуется устанавливать осмысленное значение этого параметра, а также отслеживать приближение фактического количества партиций к нему, иначе рано или поздно партиции перестанут разделяться при росте данных или нагрузке, что приведет к сбою.
+
+#### UNIFORM_PARTITIONS
+
+* Тип: Uint64
+* Значение по-умолчанию: Не применимо
+
+Количество партиций для равномерного начального разделения таблицы. Первая колонка первичного ключа должна иметь тип Uint64 или Uint32. Созданная таблица сразу будет разделена на указанное количество партиций. 
+
+При включенном автоматическом партиционировании необходимо также не забыть установить корректное значение параметра [`AUTO_PARTITIONING_MIN_PARTITIONS_COUNT`](#auto_partitioning_min_partitions_count), чтобы все партиции не объединились в одну сразу после создания таблицы.
+
+В настоящее время не поддерживается возможность задания начального количества партиций для вторичных индексов.
+
+#### PARTITION_AT_KEYS
+
+* Тип: Expression
+* Значение по-умолчанию: Не применимо
+
+Граничные значения ключей для начального разделения на партиции. Представляется списком граничных значений, разделенных запятыми и обрамленными в скобки. Каждое граничное значение может быть либо набором значений ключевых колонок (также разделенных запятыми и обрамленными в скобки), либо единичным значением, если указываются только значения первой ключевой колонки. Примеры: ```(100, 1000)```, ```((100, "abc"), (1000, "cde"))```.
+
+При включенном автоматическом партиционировании необходимо также не забыть установить корректное значение параметра [`AUTO_PARTITIONING_MIN_PARTITIONS_COUNT`](#auto_partitioning_min_partitions_count), чтобы все партиции не объединились в одну сразу после создания таблицы.
+
+В настоящее время не поддерживается возможность задания начального разделения партиций по ключам для вторичных индексов.
 
 ### Чтение с реплик {#read_only_replicas}
 При выполнении запросов в YDB фактическое выполнение запроса к каждому шарду осуществляется в единой точке, обслуживающей протокол распределенных транзакций. Но благодаря хранению данных на разделяемом хранилище возможен запуск одного или нескольких фолловеров шарда, без выделения дополнительного места на сторадже - данные уже хранятся реплицированного и возможно обслуживание более одного читателя (но писатель при этом всё еще в каждый момент строго один).