diff options
author | mdartemenko <mdartemenko@yandex-team.com> | 2022-09-22 19:24:37 +0300 |
---|---|---|
committer | mdartemenko <mdartemenko@yandex-team.com> | 2022-09-22 19:24:37 +0300 |
commit | 0462828a2b950b6805f65d2ec62dd6f1d5dfa5fa (patch) | |
tree | d4ae5a2cadaa83aaa52c56332287023232e9f582 | |
parent | e400a5bdcb6e1222ce1cc97fd8f77eae6ee5f8e0 (diff) | |
download | ydb-0462828a2b950b6805f65d2ec62dd6f1d5dfa5fa.tar.gz |
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 |