add kv documentation

8 files changed, 425 insertions, 7 deletions

diff --git a/ydb/docs/en/core/reference/ydb-cli/commands/workload/_includes/index.md b/ydb/docs/en/core/reference/ydb-cli/commands/workload/_includes/index.md
index e1430ca139..b9414d0ce4 100644
--- a/ydb/docs/en/core/reference/ydb-cli/commands/workload/_includes/index.md
+++ b/ydb/docs/en/core/reference/ydb-cli/commands/workload/_includes/index.md
@@ -22,4 +22,4 @@ See the description of the command to run the data load:
 The following types of load tests are supported at the moment:
 
 * [Stock](../stock.md): An online store warehouse simulator.
-
+* [Kv](../kv.md): Key-Value load.
diff --git a/ydb/docs/en/core/reference/ydb-cli/commands/workload/_includes/kv.md b/ydb/docs/en/core/reference/ydb-cli/commands/workload/_includes/kv.md
new file mode 100644
index 0000000000..8eb6b89e60
--- /dev/null
+++ b/ydb/docs/en/core/reference/ydb-cli/commands/workload/_includes/kv.md
@@ -0,0 +1,206 @@
+# Key-Value load
+
+A simple type of load that uses the YDB database as a Key-Value storage
+
+## Types of load {#workload_types}
+
+This load test contains 3 types of load:
+* [upsert](#upsertKv) - using the UPSERT operation, inserts rows into a table created in advance by the init command, which are tuples (key, value1, value2, ... valueN), the number N is set in the parameters
+* [insert](#insertKv) - the functionality is the same as that of the upsert load, but the INSERT operation is used for insertion
+* [select](#selectKv) - reads data using the SELECT * WHERE key = $key operation. The query always affects all columns of the table, but is not always point-based, the number of variations of the primary key can be controlled using parameters.
+
+## Load test initialization {#init}
+
+To get started, you need to create tables, when creating, you can specify how many rows you need to insert during initialization
+```bash
+{{ ydb-cli }} workload kv init [init options...]
+```
+
+* `init options` — [initialization parameters](#init_options).
+
+See the description of the command to initialize the table:
+
+```bash
+{{ ydb-cli }} workload kv init --help
+```
+
+### Available parameters {#init_options}
+
+Parameter name | Parameter Description
+---|---
+`--init-upserts <value>` | The number of insertion operations to be performed during initialization. Default value: 1000.
+`--min-partitions` | Minimum number of shards for tables. Default value: 40.
+`--auto-partition` | Enabling/disabling autosharding. Possible values: 0 or 1. Default value: 1.
+`--max-first-key` | The maximum value of the primary key of the table. Default value: $2^{64} - 1$.
+`--len` | The size of the rows in bytes that are inserted into the table as values. Default value: 8.
+`--cols` | Number of columns in the table. Default value: 2, counting Key.
+`--rows` | The number of affected rows in a single request. Default value: 1.
+
+
+To create a table, use the following command:
+```sql
+CREATE TABLE `DbPath/kv_test`(
+    c0 Uint64,
+    c1 String,
+    c2 String,
+    ...
+    cN String,
+    PRIMARY KEY(c0)) WITH (
+        AUTO_PARTITIONING_BY_LOAD = ENABLED,
+        AUTO_PARTITIONING_MIN_PARTITIONS_COUNT = partsNum,
+        UNIFORM_PARTITIONS = partsNum,
+        AUTO_PARTITIONING_MAX_PARTITIONS_COUNT = 1000
+    )
+)
+```
+
+### Load initialization examples {#init-kv-examples}
+
+Example of a command to create a table with 1000 rows:
+
+```bash
+{{ ydb-cli }} workload kv init --init-upserts 1000
+```
+
+## Deleting a table {#clean}
+
+After completing the work, you can delete the table
+```bash
+{{ ydb-cli }} workload kv clean
+```
+
+The following YQL command is executed:
+```sql
+DROP TABLE `DbPath/kv_test`
+```
+
+### Examples of using clean {#clean-kv-examples}
+
+
+```bash
+{{ ydb-cli }} workload kv clean
+```
+
+## Running a load test {#run}
+
+To start the load, run the command:
+```bash
+{{ ydb-cli }} workload kv run [workload type...] [global workload options...] [specific workload options...]
+```
+During the test, load statistics for each time window are displayed on the screen.
+
+* `workload type` — [types of load](#workload_types).
+* `global workload options` - [general parameters for all types of load](#global_workload_options).
+* `specific workload options` - parameters of a specific type of load.
+
+See the description of the command to start the load:
+
+```bash
+{{ ydb-cli }} workload kv run --help
+```
+
+### Common parameters for all types of load {#global_workload_options}
+
+Parameter name | Short name | Parameter Description
+---|---|---
+`-- seconds <value>` | `-s <value>` | Duration of the test, sec. Default value: 10.
+`--threads <value>` | `-t <value>` | The number of parallel threads creating the load. Default value: 10.
+`--quiet` | - | Outputs only the final test result.
+`--print-timestamp` | - | Print the time together with the statistics of each time window.
+`--client-timeout` | - | [Transport timeout in milliseconds](../../../../../best_practices/timeouts.md).
+`--operation-timeout` | - | [Operation timeout in milliseconds](../../../../../best_practices/timeouts.md).
+`--cancel-after` | - | [Operation cancellation timeout in milliseconds](../../../../../best_practices/timeouts.md).
+`--window` | - | Duration of the statistics collection window in seconds. Default value: 1.
+`--max-first-key` | - | The maximum value of the primary key of the table. Default value: $2^{64} - 1$.
+`--cols` | - | Number of columns in the table. Default value: 2, counting Key.
+`--rows` | - |The number of affected rows in a single request. Default value: 1.
+
+
+## Load upsert {#upsertKv}
+
+This type of load inserts tuples (key, value1, value2, ..., valueN)
+
+YQL Query:
+```sql
+DECLARE r0 AS Uint64
+DECLARE c00 AS String;
+DECLARE c01 AS String;
+...
+DECLARE c0{N - 1} AS String;
+DECLARE r1 AS Uint64
+DECLARE c10 AS String;
+DECLARE c11 AS String;
+...
+DECLARE c1{N - 1} AS String;
+UPSERT INTO `kv_test`(c0, c1, ... cN) VALUES ( (r0, c00, ... c0{N - 1}), (r1, c10, ... c1{N - 1}), ... )
+```
+
+To start this type of load, you need to run the command:
+```bash
+{{ ydb-cli }} workload kv run upsert [global workload options...] [specific workload options...]
+```
+
+* `global workload options` - [general parameters for all types of load](#global_workload_options).
+* `specific workload options` - [parameters of a specific type of load](#upsert_options)
+
+### Parameters for upsert {#upsert_options}
+Parameter name | Parameter Description
+---|---
+`--len` | The size of the rows in bytes that are inserted into the table as values. Default value: 8.
+
+## Load insert {#insertKv}
+
+This type of load inserts tuples (key, value1, value2, ..., valueN)
+
+YQL Query:
+```sql
+DECLARE r0 AS Uint64
+DECLARE c00 AS String;
+DECLARE c01 AS String;
+...
+DECLARE c0{N - 1} AS String;
+DECLARE r1 AS Uint64
+DECLARE c10 AS String;
+DECLARE c11 AS String;
+...
+DECLARE c1{N - 1} AS String;
+INSERT INTO `kv_test`(c0, c1, ... cN) VALUES ( (r0, c00, ... c0{N - 1}), (r1, c10, ... c1{N - 1}), ... )
+```
+
+To start this type of load, you need to run the command:
+```bash
+{{ ydb-cli }} workload kv run insert [global workload options...] [specific workload options...]
+```
+
+* `global workload options` - [general parameters for all types of load](#global_workload_options).
+* `specific workload options` - [parameters of a specific type of load](#insert_options)
+
+### Parameters for insert {#insert_options}
+Parameter name | Parameter Description
+---|---
+`--len` | The size of the rows in bytes that are inserted into the table as values. Default value: 8.
+
+## Load select {#selectKv}
+
+This type of load creates SELECT queries that return rows based on the exact match of the primary key.
+
+YQL Query:
+```sql
+DECLARE r0 AS Uint64
+DECLARE r1 AS Uint64
+...
+DECLARE rM AS Uint64
+SELECT * FROM `kv_test`(c0, c1, ..., cN) WHERE (
+    c0 == r0 OR
+    c0 == r1 OR
+    ...
+    c0 == rM
+)
+```
+
+To start this type of load, you need to run the command:
+```bash
+{{ ydb-cli }} workload kv run select [global workload options...]
+```
+
+* `global workload options` - [general parameters for all types of load](#global_workload_options).
diff --git a/ydb/docs/en/core/reference/ydb-cli/commands/workload/kv.md b/ydb/docs/en/core/reference/ydb-cli/commands/workload/kv.md
new file mode 100644
index 0000000000..d501311cf7
--- /dev/null
+++ b/ydb/docs/en/core/reference/ydb-cli/commands/workload/kv.md
@@ -0,0 +1 @@
+{% include [kv.md](_includes/kv.md) %}
diff --git a/ydb/docs/en/core/reference/ydb-cli/toc_i.yaml b/ydb/docs/en/core/reference/ydb-cli/toc_i.yaml
index 919da92417..c2d01c9f43 100644
--- a/ydb/docs/en/core/reference/ydb-cli/toc_i.yaml
+++ b/ydb/docs/en/core/reference/ydb-cli/toc_i.yaml
@@ -77,5 +77,7 @@ items:
       href: commands/workload/index.md
     - name: Stock load
       href: commands/workload/stock.md
+    - name: Kv load
+      href: commands/workload/kv.md
 
 
diff --git a/ydb/docs/ru/core/reference/ydb-cli/commands/workload/_includes/index.md b/ydb/docs/ru/core/reference/ydb-cli/commands/workload/_includes/index.md
index f2c0a77433..52fe1703b5 100644
--- a/ydb/docs/ru/core/reference/ydb-cli/commands/workload/_includes/index.md
+++ b/ydb/docs/ru/core/reference/ydb-cli/commands/workload/_includes/index.md
@@ -20,4 +20,5 @@
 ## Доступные подкоманды {#subcommands}
 
 В данный момент поддерживаются следующие виды нагрузочных тестов:
-* [Stock](../stock.md) - симулятор склада интернет-магазина.
\ No newline at end of file
+* [Stock](../stock.md) - симулятор склада интернет-магазина.
+* [Kv](../kv.md) - Key-Value нагрузка
diff --git a/ydb/docs/ru/core/reference/ydb-cli/commands/workload/_includes/kv.md b/ydb/docs/ru/core/reference/ydb-cli/commands/workload/_includes/kv.md
new file mode 100644
index 0000000000..f0738146d0
--- /dev/null
+++ b/ydb/docs/ru/core/reference/ydb-cli/commands/workload/_includes/kv.md
@@ -0,0 +1,206 @@
+# Key-Value нагрузка
+
+Простой вид нагрузки, использующий YDB базу данных как Key-Value хранилище
+
+## Виды нагрузки {#workload_types}
+
+Данный нагрузочный тест содержит 3 вида нагрузки:
+* [upsert](#upsertKv) - при помощи операции UPSERT вставляет в заранее созданную командой init таблицу строки, которые представляют из себя кортежи (key, value1, value2, ... valueN), число N задается в параметрах
+* [insert](#insertKv) - функционал такой же, как у нагрузки upsert, но для вставки используется операция INSERT
+* [select](#selectKv) - читает данные при помощи операции SELECT * WHERE key = $key. Запрос всегда затрагивает все колонки таблицы, но не всегда является точечным, количеством вариаций primary ключа можно управлять с помощью параметров.
+
+## Инициализация нагрузочного теста {#init}
+
+Для начала работы необходимо создать таблицы, при создании можно указать, сколько строк необходимо вставить при инициализации
+```bash
+{{ ydb-cli }} workload kv init [init options...]
+```
+
+* `init options` — [параметры инициализации](#init_options).
+
+Посмотрите описание команды для инициализации таблицы:
+
+```bash
+{{ ydb-cli }} workload kv init --help
+```
+
+### Доступные параметры {#init_options}
+
+Имя параметра | Описание параметра
+---|---
+`--init-upserts <значение>` | Количество операций вставки, которые нужно сделать при инициализации. Значение по умолчанию: 1000.
+`--min-partitions` | Минимальное количество шардов для таблиц. Значение по умолчанию: 40.
+`--auto-partition` | Включение/выключение автошардирования. Возможные значения: 0 или 1. Значение по умолчанию: 1.
+`--max-first-key` | Максимальное значение primary ключа таблицы. Значение по умолчанию: $2^{64} - 1$.
+`--len` | Размер строк в байтах, которые вставляются в таблицу, как values. Значение по умолчанию: 8.
+`--cols` | Количество колонок в таблице. Значение по умолчанию: 2, считая Key.
+`--rows` | Количество затрагиваемых строк в одном запросе. Значение по умолчанию: 1.
+
+
+Для создания таблицы используется следующая команда:
+```sql
+CREATE TABLE `DbPath/kv_test`(
+    c0 Uint64,
+    c1 String,
+    c2 String,
+    ...
+    cN String,
+    PRIMARY KEY(c0)) WITH (
+        AUTO_PARTITIONING_BY_LOAD = ENABLED,
+        AUTO_PARTITIONING_MIN_PARTITIONS_COUNT = partsNum,
+        UNIFORM_PARTITIONS = partsNum,
+        AUTO_PARTITIONING_MAX_PARTITIONS_COUNT = 1000
+    )
+)
+```
+
+### Примеры инициализации нагрузки {#init-kv-examples}
+
+Пример команды создания таблицы с 1000 строками:
+
+```bash
+{{ ydb-cli }} workload kv init --init-upserts 1000
+```
+
+## Удаление таблицы {#clean}
+
+После завершения работы можно удалить таблицу
+```bash
+{{ ydb-cli }} workload kv clean
+```
+
+Исполняется следующая YQL команда:
+```sql
+DROP TABLE `DbPath/kv_test`
+```
+
+### Примеры использования clean {#clean-kv-examples}
+
+
+```bash
+{{ ydb-cli }} workload kv clean
+```
+
+## Запуск нагрузочного теста {#run}
+
+Для запуска нагрузки необходимо выполнить команду:
+```bash
+{{ ydb-cli }} workload kv run [workload type...] [global workload options...] [specific workload options...]
+```
+В течение теста на экран выводится статистика по нагрузке для каждого временного окна.
+
+* `workload type` — [виды нагрузки](#workload_types).
+* `global workload options` - [общие параметры для всех видов нагрузки](#global_workload_options).
+* `specific workload options` - параметры конкретного вида нагрузки.
+
+Посмотрите описание команды для запуска нагрузки:
+
+```bash
+{{ ydb-cli }} workload kv run --help
+```
+
+### Общие параметры для всех видов нагрузки {#global_workload_options}
+
+Имя параметра | Короткое имя | Описание параметра
+---|---|---
+`--seconds <значение>` | `-s <значение>` | Продолжительность теста, сек. Значение по умолчанию: 10.
+`--threads <значение>` | `-t <значение>` | Количество параллельных потоков, создающих нагрузку. Значение по умолчанию: 10.
+`--quiet` | - | Выводит только итоговый результат теста.
+`--print-timestamp` | - | Печатать время вместе со статистикой каждого временного окна.
+`--client-timeout` | - | [Транспортный таймаут в миллисекундах](../../../../../best_practices/timeouts.md).
+`--operation-timeout` | - | [Таймаут на операцию в миллисекундах](../../../../../best_practices/timeouts.md).
+`--cancel-after` | - | [Таймаут отмены операции в миллисекундах](../../../../../best_practices/timeouts.md).
+`--window` | - | Длительность окна сбора статистики в секундах. Значение по умолчанию: 1.
+`--max-first-key` | - | Максимальное значение primary ключа таблицы. Значение по умолчанию: $2^{64} - 1$.
+`--cols` | - | Количество колонок в таблице. Значение по умолчанию: 2, считая Key.
+`--rows` | - |Количество затрагиваемых строк в одном запросе. Значение по умолчанию: 1.
+
+
+## Нагрузка upsert {#upsertKv}
+
+Данный вид нагрузки вставляет кортежи (key, value1, value2, ..., valueN)
+
+YQL Запрос:
+```sql
+DECLARE r0 AS Uint64
+DECLARE c00 AS String;
+DECLARE c01 AS String;
+...
+DECLARE c0{N - 1} AS String;
+DECLARE r1 AS Uint64
+DECLARE c10 AS String;
+DECLARE c11 AS String;
+...
+DECLARE c1{N - 1} AS String;
+UPSERT INTO `kv_test`(c0, c1, ... cN) VALUES ( (r0, c00, ... c0{N - 1}), (r1, c10, ... c1{N - 1}), ... )
+```
+
+Для запуска данного вида нагрузки необходимо выполнить команду:
+```bash
+{{ ydb-cli }} workload kv run upsert [global workload options...] [specific workload options...]
+```
+
+* `global workload options` - [общие параметры для всех видов нагрузки](#global_workload_options).
+* `specific workload options` - [параметры конкретного вида нагрузки](#upsert_options)
+
+### Параметры для upsert {#upsert_options}
+Имя параметра | Описание параметра
+---|---
+`--len` | Размер строк в байтах, которые вставляются в таблицу, как values. Значение по умолчанию: 8.
+
+## Нагрузка insert {#insertKv}
+
+Данный вид нагрузки вставляет кортежи (key, value1, value2, ..., valueN)
+
+YQL Запрос:
+```sql
+DECLARE r0 AS Uint64
+DECLARE c00 AS String;
+DECLARE c01 AS String;
+...
+DECLARE c0{N - 1} AS String;
+DECLARE r1 AS Uint64
+DECLARE c10 AS String;
+DECLARE c11 AS String;
+...
+DECLARE c1{N - 1} AS String;
+INSERT INTO `kv_test`(c0, c1, ... cN) VALUES ( (r0, c00, ... c0{N - 1}), (r1, c10, ... c1{N - 1}), ... )
+```
+
+Для запуска данного вида нагрузки необходимо выполнить команду:
+```bash
+{{ ydb-cli }} workload kv run insert [global workload options...] [specific workload options...]
+```
+
+* `global workload options` - [общие параметры для всех видов нагрузки](#global_workload_options).
+* `specific workload options` - [параметры конкретного вида нагрузки](#insert_options)
+
+### Параметры для insert {#insert_options}
+Имя параметра | Описание параметра
+---|---
+`--len` | Размер строк в байтах, которые вставляются в таблицу, как values. Значение по умолчанию: 8.
+
+## Нагрузка select {#selectKv}
+
+Данный вид нагрузки создает SELECT запросы, возвращающие строки по точному совпадению primary ключа.
+
+YQL Запрос:
+```sql
+DECLARE r0 AS Uint64
+DECLARE r1 AS Uint64
+...
+DECLARE rM AS Uint64
+SELECT * FROM `kv_test`(c0, c1, ..., cN) WHERE (
+    c0 == r0 OR
+    c0 == r1 OR
+    ...
+    c0 == rM
+)
+```
+
+Для запуска данного вида нагрузки необходимо выполнить команду:
+```bash
+{{ ydb-cli }} workload kv run select [global workload options...]
+```
+
+* `global workload options` - [общие параметры для всех видов нагрузки](#global_workload_options).
diff --git a/ydb/docs/ru/core/reference/ydb-cli/commands/workload/kv.md b/ydb/docs/ru/core/reference/ydb-cli/commands/workload/kv.md
new file mode 100644
index 0000000000..d501311cf7
--- /dev/null
+++ b/ydb/docs/ru/core/reference/ydb-cli/commands/workload/kv.md
@@ -0,0 +1 @@
+{% include [kv.md](_includes/kv.md) %}
diff --git a/ydb/docs/ru/core/reference/ydb-cli/toc_i.yaml b/ydb/docs/ru/core/reference/ydb-cli/toc_i.yaml
index 5e6ced481e..c9e07d72c1 100644
--- a/ydb/docs/ru/core/reference/ydb-cli/toc_i.yaml
+++ b/ydb/docs/ru/core/reference/ydb-cli/toc_i.yaml
@@ -46,13 +46,13 @@ items:
     - name: Добавление читателя топика
       href: topic-consumer-add.md
     - name: Удаление читателя топика
-      href: topic-consumer-drop.md    
+      href: topic-consumer-drop.md
     - name: Чтение из топика
-      href: topic-read.md    
+      href: topic-read.md
     - name: Запись в топик
-      href: topic-write.md    
+      href: topic-write.md
     - name: Конвейерная обработка сообщений
-      href: topic-pipeline.md    
+      href: topic-pipeline.md
 #  - name: Утилиты
 #    items:
     # - name: Копирование таблиц
@@ -77,5 +77,6 @@ items:
       href: commands/workload/index.md
     - name: Stock нагрузка
       href: commands/workload/stock.md
-
+    - name: Kv нагрузка
+      href: commands/workload/kv.md