ydb docs add deprecated to some ds_pdisks system view fields, small how_to_edit clarifications

ref:fd95c4d4208b8d9b601fd3f2d0d7328c2183f149

7 files changed, 54 insertions, 74 deletions

diff --git a/ydb/docs/ru/core/best_practices/_includes/index.md b/ydb/docs/ru/core/best_practices/_includes/index.md
index 3e630ac691..316a4decc8 100644
--- a/ydb/docs/ru/core/best_practices/_includes/index.md
+++ b/ydb/docs/ru/core/best_practices/_includes/index.md
@@ -2,8 +2,7 @@
 
 В данном разделе собраны статьи, рассказывающие про назначение, особенности и лучшие практики применения инструментов YDB при разработке приложений.
 
-- [Проектирование схемы данных](../schema_design.md)
-- [Партиционирование таблиц](../table_sharding.md)
+- [Выбор первичного ключа для максимальной производительности](../pk_scalability.md)
 - [Вторичные индексы](../secondary_indexes.md)
 - [Постраничный вывод](../paging.md)
 - [Загрузка больших объемов данных](../batch_upload.md)
diff --git a/ydb/docs/ru/core/best_practices/_includes/pk_scalability.md b/ydb/docs/ru/core/best_practices/_includes/pk_scalability.md
new file mode 100644
index 0000000000..766e6c9c12
--- /dev/null
+++ b/ydb/docs/ru/core/best_practices/_includes/pk_scalability.md
@@ -0,0 +1,43 @@
+# Выбор первичного ключа для максимальной производительности
+
+Выбор колонок для первичного ключа таблицы оказывает определяющее влияние на возможности YDB по масштабированию нагрузки и повышению производительности.
+
+Общие рекомендации по выбору первичного ключа:
+
+* Следует избегать ситуаций, когда основная часть нагрузки приходится на одну [партицию](../../concepts/datamodel.md#partitioning) таблицы. Чем равномернее нагрузка распределяется по партициям, тем большая производительность может быть достигнута.
+* Следует уменьшать количество партиций, которые могут быть затронуты в одном запросе. Более того, если запрос затрагивает не более одной партиции, то он выполняется по специальному упрощенному протоколу, что существенно увеличивает скорость и экономит ресурсы.
+
+Все таблицы в {{ ydb-short-name }} отсортированы по возрастанию первичного ключа. Это означает, что запись в таблицу данных с монотонно возрастающим первичным ключом приведет к добавлению новых данные в конец таблицы. Так как {{ ydb-short-name }} разделяет таблицы на партиции по диапазонам ключей, вставки будут обрабатываться одним конкретным сервером, отвечающим за "последнюю" партицию. Сосредоточение нагрузки на одном сервере приведет к медленной загрузке данных и неэффективному использованию распределенной системы.
+В качестве примера рассмотрим запись лога пользовательских событий в таблицу со схемой ```( timestamp, userid, userevent, PRIMARY KEY (timestamp, userid) )```.
+
+```timestamp``` монотонно возрастает, как следствие, все записи будут записываться в конец таблицы и "последняя" партиция, которая отвечает за данный диапазон ключей, будет обслуживать все записи в таблицу. Это приведет к невозможности масштабирования нагрузки на запись, производительность будет ограничена одним процессом обслуживания этой партиции, и не будет расти с добавлением серверов в кластер.
+
+В {{ ydb-short-name }} поддерживается автоматическое разделение партиции при достижении порогового размера или нагрузки. Но в рассматриваемом случае после разделения новая партиция начнет опять принимать всю нагрузку на запись, и ситуация повторится.
+
+## Приемы, позволяющие равномерно распределить нагрузку по партициям таблицы {#balance-shard-load}
+
+### Изменение порядка следования компонент ключа {#key-order}
+
+Запись данных в таблицу со схемой ```( timestamp, userid, userevent, PRIMARY KEY (timestamp, userid) )``` приводит к неравномерной нагрузке на партиции таблицы из-за монотонно возрастающего первичного ключа. Изменение порядка следования компонент ключа таким образом, чтобы монотонно возрастающая часть не была первой компонентой, может помочь более равномерно распределить нагрузку. Если изменить схему таблицы на ```( timestamp, userid, userevent, PRIMARY KEY (userid, timestamp) )```, то при достаточном количестве пользователей, генерирующих события, запись в БД будет распределена по партициям более равномерно.
+
+### Использование хеша от значений ключевых колонок в качестве первичного ключа {#key-hash}
+
+Рассмотрим таблицу со схемой ```( timestamp, userid, userevent, PRIMARY KEY (userid, timestamp) )```. В качестве всего первичного ключа или его первой компоненты можно использовать хеш от исходного ключа, например так:
+
+```
+( HASH(timestamp, userid), timestamp, userid, userevent, PRIMARY KEY (HASH(userid), userid, timestamp) )
+```
+
+При правильном выборе функции хеширования строки будут распределены достаточно равномерно по всему пространству ключей, что в приведет к равномерной нагрузке на систему. При этом, наличие полей ```userid, timestamp``` в составе ключа после ```HASH(userid)``` сохраняет локальность и сортировку данных по времени для конкретного пользователя.
+
+### Уменьшение количества партиций, затрагиваемых в одном запросе {#decrease-shards}
+
+Предположим, что основной сценарий работы с данными таблицы — прочитать все события по конкретному ```userid```. Тогда при использовании схемы таблицы ```( timestamp, userid, userevent, PRIMARY KEY (timestamp, userid) )``` каждое чтение будет затрагивать все партиции таблицы. При этом, каждая партиция будет просканирована полностью, так как строки, относящиеся к конкретному ```userid```, расположены в заранее неизвестном порядке. Изменение порядка следования компонент ключа ```( timestamp, userid, userevent, PRIMARY KEY (userid, timestamp) )``` приведет к тому, что все строки, относящиеся к конкретному ```userid```, будут следовать друг за другом. Такое расположение строк положительно повлияет на скорость чтения информации по конкретному ```userid```.
+
+## Значение NULL в ключевой колонке {#key-null}
+
+В {{ ydb-short-name }} все колонки, включая ключевые, могут содержать значение NULL. Использование NULL в качестве значений в ключевых колонках не рекомендуется. По стандарту языка SQL (ISO/IEC 9075) значение NULL нельзя сравнивать с другими значениями, вследствие чего использование лаконичных конструкции SQL с простыми операторами сравнения может приводить, например, к тому что, строки, содержащие значение NULL, могут быть пропущены при фильтрации.
+
+## Ограничение размера строки {#limit-string}
+
+Для достижения хорошей производительности не рекомендуется записывать в БД строки размером более 8 МБ и ключевые колонки размером более 2 КБ.
diff --git a/ydb/docs/ru/core/best_practices/_includes/schema_design.md b/ydb/docs/ru/core/best_practices/_includes/schema_design.md
index 5f595cd388..f47c3a0ae4 100644
--- a/ydb/docs/ru/core/best_practices/_includes/schema_design.md
+++ b/ydb/docs/ru/core/best_practices/_includes/schema_design.md
@@ -1,49 +1 @@
-# Проектирование схемы
-
-В данном разделе приведены рекомендации по проектированию схемы БД для повышения производительности {{ ydb-short-name }}.
-
-## Проектирование первичного ключа {#pk-design}
-
-При проектировании схемы базы данных важно учитывать предполагаемые сценарии нагрузки. Одним из этапов проектирования является выбор первичных ключей таблиц. Правильный выбор первичных ключей важен, так как влияет на скорость чтения и записи данных в таблицу.
-
-Общие рекомендации по выбору первичного ключа:
-
-* Следует избегать ситуаций, когда основная часть нагрузки приходится на одну [партицию](../../concepts/datamodel.md#partitioning) таблицы. При равномерной нагрузке проще достигается высокая производительность.
-* Следует уменьшать количество партиций, которые могут быть затронуты в одном запросе. Более того, если запрос затрагивает не более одной партиции, то он выполняется по специальному упрощенному протоколу, что существенно увеличивает скорость и экономит ресурсы.
-
-Следует тщательно подходить к выбору первичного ключа и избегать ситуаций, при которых какая-то малая часть БД нагружена существенно больше, чем остальные части БД.
-
-Например, из-за того, что все таблицы в {{ ydb-short-name }} отсортированы по возрастанию первичного ключа, запись в таблицу данных с монотонно возрастающим первичным ключом приведет к тому, что новые данные будут записываться в конец таблицы. Так как {{ ydb-short-name }} разделяет таблицы на партиции по диапазонам ключей, вставки будут обрабатываться одним конкретным сервером, отвечающим за "последнюю" партицию. Сосредоточение нагрузки на одном сервере приведет к медленной загрузке данных и неэффективному использованию распределенной системы.
-В качестве примера рассмотрим запись лога пользовательских событий в таблицу со схемой ```( timestamp, userid, userevent, PRIMARY KEY (timestamp, userid) )```.
-
-```timestamp``` монотонно возрастает, как следствие, все записи будут записываться в конец таблицы и "последняя" партиция, которая отвечает за данный диапазон ключей, будет обслуживать все записи в таблицу. Это приведет к падению производительности записи.
-
-В {{ ydb-short-name }} поддерживается автоматическое разделение партиции при достижении порогового размера (обычно около 2 ГБ). Но в рассматриваемом случае после разделения новая партиция начнет принимать всю нагрузку на запись и ситуация повторится.
-
-## Приемы, позволяющие равномерно распределить нагрузку по партициям таблицы {#balance-shard-load}
-
-### Изменение порядка следования компонент ключа {#key-order}
-
-Запись данных в таблицу со схемой ```( timestamp, userid, userevent, PRIMARY KEY (timestamp, userid) )``` приводит к неравномерной нагрузке на партиции таблицы из-за монотонно возрастающего первичного ключа. Изменение порядка следования компонент ключа таким образом, чтобы монотонно возрастающая часть не была первой компонентой, может помочь более равномерно распределить нагрузку. Если изменить схему таблицы на ```( timestamp, userid, userevent, PRIMARY KEY (userid, timestamp) )```, то при достаточном количестве пользователей, генерирующих события, запись в БД будет распределена по партициям более равномерно.
-
-### Использование хеша от значений ключевых колонок в качестве первичного ключа {#key-hash}
-
-Рассмотрим таблицу со схемой ```( timestamp, userid, userevent, PRIMARY KEY (userid, timestamp) )```. В качестве всего первичного ключа или его первой компоненты можно использовать хеш от исходного ключа, например так:
-
-```
-( HASH(timestamp, userid), timestamp, userid, userevent, PRIMARY KEY (HASH(userid), userid, timestamp) )
-```
-
-При правильном выборе функции хеширования строки будут распределены достаточно равномерно по всему пространству ключей, что в приведет к равномерной нагрузке на систему. При этом, наличие полей ```userid, timestamp``` в составе ключа после ```HASH(userid)``` сохраняет локальность и сортировку данных по времени для конкретного пользователя.
-
-### Уменьшение количества партиций, затрагиваемых в одном запросе {#decrease-shards}
-
-Предположим, что основной сценарий работы с данными таблицы — прочитать все события по конкретному ```userid```. Тогда при использовании схемы таблицы ```( timestamp, userid, userevent, PRIMARY KEY (timestamp, userid) )``` каждое чтение будет затрагивать все партиции таблицы. При этом, каждая партиция будет просканирована полностью, так как строки, относящиеся к конкретному ```userid```, расположены в заранее неизвестном порядке. Изменение порядка следования компонент ключа ```( timestamp, userid, userevent, PRIMARY KEY (userid, timestamp) )``` приведет к тому, что все строки, относящиеся к конкретному ```userid```, будут следовать друг за другом. Такое расположение строк положительно повлияет на скорость чтения информации по конкретному ```userid```.
-
-## Значение NULL в ключевой колонке {#key-null}
-
-В {{ ydb-short-name }} все колонки, включая ключевые, могут содержать значение NULL. Использование NULL в качестве значений в ключевых колонках не рекомендуется. По стандарту языка SQL (ISO/IEC 9075) значение NULL нельзя сравнивать с другими значениями, вследствие чего использование лаконичных конструкции SQL с простыми операторами сравнения может приводить, например, к тому что, строки, содержащие значение NULL, могут быть пропущены при фильтрации.
-
-## Ограничение размера строки {#limit-string}
-
-Для достижения хорошей производительности не рекомендуется записывать в БД строки размером более 8 МБ и ключевые колонки размером более 2 КБ.
+Данная статья удалена, материал перемещен в статью [Влияние первичного ключа на производительность](../pk_scalability.md).
\ No newline at end of file
diff --git a/ydb/docs/ru/core/best_practices/_includes/table_sharding.md b/ydb/docs/ru/core/best_practices/_includes/table_sharding.md
index e059f0c795..c301e79b89 100644
--- a/ydb/docs/ru/core/best_practices/_includes/table_sharding.md
+++ b/ydb/docs/ru/core/best_practices/_includes/table_sharding.md
@@ -1,21 +1 @@
-# Партиционирование таблиц
-
-Таблицы в {{ ydb-short-name }} отсортированы по возрастанию первичного ключа. Партицирование таблиц осуществляется путём разбиения диапазона значений ключа на последовательные непересекающиеся диапазоны - партиции.
-
-Благодаря партицированию данные таблицы могут распределяться по множеству устройств хранения, а нагрузка при работе с таблицей может задействовать больше процессорных ядер и пропускной способности сети. Вместе с тем слишком большое количество партиций в таблице может добавлять накладные расходы по использованию памяти и процессорного времени. Таким образом оптимальное партиционирование прямым образом влияет на эффективность выполнения запросов. Для достижения оптимального партицирования в {{ ydb-short-name }} есть как средства для задания первоначального разбиения таблицы при её создании, так и способы последующего автоматического партиционирования.
-
-При создании таблицы можно задать первоначальное партицирование одним из 2 способов:
-* Задать равномерное партицирование по первой колонке первичного ключа, если эта колонка имеет тип UInt32 или UInt64. В этом случае необходимо явно задать количество партиций.
-* Задать точные ключи партицирования, которые определят количество и границы первоначальных партиций.
-
-{{ ydb-short-name }} поддерживает 2 способа автопартицирования таблиц:
-* по размеру данных;
-* по нагрузке на даташард (даташард - компонент системы обслуживающий партицию таблицы).
-
-Режимы автопартицирования могут быть включены как по отдельности, так и вместе. Оба режима могут производить разбиение одной партиции на две и слияние нескольких партиций в одну. Возможность разбиения или слияния ограничивается настройками таблицы ```MIN_PARTITIONS``` и ```MAX_PARTITIONS```. При разбиении партиции её диапазон ключей делится на 2 новых диапазона, и данные этих диапазонов образуют новые партиции. Слияние может происходить для нескольких соседних диапазонов, при этом данные нескольких партиций логически сливаются в одну партицию.
-
-Автопартицирование по размеру параметризуется настройкой размера партиции, при достижении которого происходит её разбиение. По умолчанию это значение равно 2ГБ. Выбор ключа для разбиения делается на основании гистограммы распределения размера данных в партиции по поддиапазонам ключей. Если же суммарный размер данных в смежных партициях становится меньше половины от настройки размера, то эти партиции сливаются.
-
-Срабатывание автопартицирования по нагрузке определяется потреблением CPU даташардом обслуживающим партицию. Все даташарды следят за своим потреблением CPU. Если в какой-то момент времени обнаруживается высокое (>50%) потребление, происходит разбиение партиции. Для выбора ключа используется статистика по обращениям к ключам своей партиции.
-
-Полный перечень параметров таблиц, включая параметры партиционирования, с комментариями об из применении, приведен в пункте [Партиционирование таблиц](../../concepts/datamodel.md#partitioning) статьи об объектах схемы данных в разделе "Концепции".
\ No newline at end of file
+Данная статья удалена, материал перемещен в пункт [Партиционирование таблиц](../../concepts/datamodel.md#partitioning) статьи об объектах схемы данных в разделе "Концепции".
\ No newline at end of file
diff --git a/ydb/docs/ru/core/best_practices/pk_scalability.md b/ydb/docs/ru/core/best_practices/pk_scalability.md
new file mode 100644
index 0000000000..7a4fb2e2af
--- /dev/null
+++ b/ydb/docs/ru/core/best_practices/pk_scalability.md
@@ -0,0 +1,2 @@
+
+{% include [pk_scalability.md](_includes/pk_scalability.md) %}
diff --git a/ydb/docs/ru/core/best_practices/toc_i.yaml b/ydb/docs/ru/core/best_practices/toc_i.yaml
index 07ed073a5a..04c5f8fad9 100644
--- a/ydb/docs/ru/core/best_practices/toc_i.yaml
+++ b/ydb/docs/ru/core/best_practices/toc_i.yaml
@@ -1,10 +1,14 @@
 items:
 - name: Обзор
   href: index.md
+- name: Выбор первичного ключа для максимальной производительности
+  href: pk_scalability.md
 - name: Проектирование схемы
   href: schema_design.md
+  hidden: true
 - name: Партиционирование таблиц
   href: table_sharding.md
+  hidden: true
 - name: Вторичные индексы
   href: secondary_indexes.md
 - name: Постраничный вывод
diff --git a/ydb/docs/ru/core/troubleshooting/_includes/system_views/distributed_storage.md b/ydb/docs/ru/core/troubleshooting/_includes/system_views/distributed_storage.md
index 745fea75f7..0e319abe8a 100644
--- a/ydb/docs/ru/core/troubleshooting/_includes/system_views/distributed_storage.md
+++ b/ydb/docs/ru/core/troubleshooting/_includes/system_views/distributed_storage.md
@@ -19,8 +19,8 @@
 | Path                  | String    |          | Путь к блочному устройству внутри машины                                                                                                                         |
 | Guid                  | Uint64    |          | Уникальный идентификатор, генерируемый случайно при добавлении диска в систему, предназначенный для предотвращения потери данных в случае перемены дисков местами |
 | BoxId                 | Uint64    |          | Идентификатор Box, в который входит данный PDisk                                                                                                                 |
-| SharedWithOs          | Bool      |          | Булевой признак, который используется для фильтрации дисков при создании новых групп                                                                             |
-| ReadCentric           | Bool      |          | Булевой признак, который используется для фильтрации дисков при создании новых групп                                                                             |
+| SharedWithOs          | Bool      |          | Наличие метки "SharedWithOs", устанавливаемой вручную при создании PDisk. Может использоваться для фильтрации дисков при создании новых групп.                   |
+| ReadCentric           | Bool      |          | Наличие метки "ReadCentric", устанавливаемой вручную при создании PDisk. Может использоваться для фильтрации дисков при создании новых групп.                    |
 | AvailableSize         | Uint64    |          | Число доступных для выделения байт на PDisk                                                                                                                      |
 | TotalSize             | Uint64    |          | Общее число байт на PDisk                                                                                                                                        |
 | Status                | String    |          | Режим работы PDisk, который влияет на его участие в выделении групп (ACTIVE, INACTIVE, BROKEN, FAULTY, TO_BE_REMOVED)                                            |