Skip to content

Commit 893a1ee

Browse files
iddqdexiddqdex
authored
Docs2 (#9458)
1 parent bf8761b commit 893a1ee

File tree

22 files changed

+730
-128
lines changed

22 files changed

+730
-128
lines changed

‎ydb/docs/en/core/recipes/ydb-cli/benchmarks.md

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
# Conducting load testing
2+
3+
{{ ydb-short-name }} CLI has a built-in toolkit for performing load testing using several standard benchmarks:
4+
5+
| Benchmark | Reference |
6+
|--------------------------------------|----------------------------------------------------------|
7+
| [TPC-H](https://tpc.org/tpch/) | [tpch](../../reference/ydb-cli/workload-tpch.md) |
8+
| [TPC-DS](https://tpc.org/tpcds/) | [tpcds](../../reference/ydb-cli/workload-tpcds.md) |
9+
| [ClickBench](https://benchmark.clickhouse.com/) | [clickbench](../../reference/ydb-cli/workload-click-bench.md) |
10+
11+
They all function similarly. For a detailed description of each, refer to the relevant reference via the links above. All commands for working with benchmarks are organized into corresponding groups, and the database path is specified in the same way for all commands:
12+
13+
```bash
14+
{{ ydb-cli }} workload clickbench --path path/in/database ...
15+
{{ ydb-cli }} workload tpch --path path/in/database ...
16+
{{ ydb-cli }} workload tpcds --path path/in/database ...
17+
```
18+
19+
Load testing can be divided into 3 stages:
20+
21+
1. [Data preparation](#data-preparation)
22+
1. [Testing](#testing)
23+
1. [Cleanup](#cleanup)
24+
25+
## Data preparation {#data-preparation}
26+
27+
It consists of two steps: initializing tables and filling them with data.
28+
29+
### Initialization
30+
31+
Initialization is performed by the `init` command:
32+
33+
```bash
34+
{{ ydb-cli }} workload clickbench --path clickbench/hits init --store=column
35+
{{ ydb-cli }} workload tpch --path tpch/s1 init --store=column
36+
{{ ydb-cli }} workload tpcds --path tpcds/s1 init --store=column
37+
```
38+
39+
At this stage, you can configure the tables to be created:
40+
41+
* Select the type of tables to be used: row, column, external, etc. (parameter `--store`);
42+
* Select the types of columns to be used: some data types from the original benchmarks can be represented by multiple {{ ydb-short-name }} data types. In such cases, it is possible to select a specific one with `--string`, `--datetime`, and `--float-mode` parameters.
43+
44+
You can also specify that tables should be deleted before creation if they already exist using the `--clear` parameter.
45+
46+
47+
For more details, see the description of the commands for each benchmark:
48+
49+
* [clickbench init](../../reference/ydb-cli/workload-click-bench.md#init)
50+
* [tpch init](../../reference/ydb-cli/workload-tpch.md#init)
51+
* [tpcds init](../../reference/ydb-cli/workload-tpcds.md#init)
52+
53+
### Data filling
54+
55+
Filling with data is performed using the `import` command. This command is specific to each benchmark, and its behavior depends on the subcommands. However, there are also parameters common to all benchmarks.
56+
57+
For a detailed description, see the relevant reference sections:
58+
59+
* [clickbench import](../../reference/ydb-cli/workload-click-bench.md#load)
60+
* [tpch import](../../reference/ydb-cli/workload-tpch.md#load)
61+
* [tpcds import](../../reference/ydb-cli/workload-tpcds.md#load)
62+
63+
Examples:
64+
65+
```bash
66+
{{ ydb-cli }} workload clickbench --path clickbench/hits import files --input hits.csv.gz
67+
{{ ydb-cli }} workload tpch --path tpch/s1 import generator --scale 1
68+
{{ ydb-cli }} workload tpcds --path tpcds/s1 import generator --scale 1
69+
```
70+
71+
## Testing {#testing}
72+
73+
The performance testing is performed using the `run` command. Its behavior is mostly the same across different benchmarks, though some differences do exist.
74+
75+
Examples:
76+
77+
```bash
78+
{{ ydb-cli }} workload clickbench --path clickbench/hits run --include 1-5,8
79+
{{ ydb-cli }} workload tpch --path tpch/s1 run --exсlude 3,4 --iterations 3
80+
{{ ydb-cli }} workload tpcds --path tpcds/s1 run --plan ~/query_plan --include 2 --iterations 5
81+
```
82+
83+
The command allows you to select queries for execution, generate various types of reports, collect execution statistics, and more.
84+
85+
For a detailed description, see the relevant reference sections:
86+
87+
* [clickbench run](../../reference/ydb-cli/workload-click-bench.md#run)
88+
* [tpch run](../../reference/ydb-cli/workload-tpch.md#run)
89+
* [tpcds run](../../reference/ydb-cli/workload-tpcds.md#run)
90+
91+
## Cleanup {#cleanup}
92+
93+
After all necessary testing has been completed, the benchmark's data can be removed from the database using the `clean` command:
94+
95+
```bash
96+
{{ ydb-cli }} workload clickbench --path clickbench/hits clean
97+
{{ ydb-cli }} workload tpch --path tpch/s1 clean
98+
{{ ydb-cli }} workload tpcds --path tpcds/s1 clean
99+
```
100+
101+
For a detailed description, see the corresponding sections:
102+
103+
* [clickbench clean](../../reference/ydb-cli/workload-click-bench.md#cleanup)
104+
* [tpch clean](../../reference/ydb-cli/workload-tpch.md#cleanup)
105+
* [tpcds clean](../../reference/ydb-cli/workload-tpcds.md#cleanup)

‎ydb/docs/en/core/recipes/ydb-cli/index.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ This section contains recipes for various tasks that can be solved with {{ ydb-s
55
Table of contents:
66

77
* [{#T}](convert-table-type.md)
8+
* [{#T}](benchmarks.md)
89

910
See also:
1011

‎ydb/docs/en/core/recipes/ydb-cli/toc_p.yaml

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
11
items:
22
- name: Convert table type
3-
href: convert-table-type.md
3+
href: convert-table-type.md
4+
- name: Benchmarks
5+
href: benchmarks.md

‎ydb/docs/en/core/reference/ydb-cli/_includes/workload/init_options_tpc.md

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
### Available parameters {#init_options}
2+
3+
| Name | Description | Default value |
4+
|-------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------|
5+
| `--store <value>` | Table storage type. Possible values: `row`, `column`, `external-s3`. | `row` |
6+
| `--external-s3-prefix <value>` | Relevant only for external tables. Root path to the dataset in S3 storage. | |
7+
| `--external-s3-endpoint <value>` or `-e <value>` | Relevant only for external tables. Link to the S3 bucket with data. | |
8+
| `--string` | Use the `String` type for text fields. | `Utf8` |
9+
| `--datetime` | Use for time-related fields of type `Date`, `Datetime`, and `Timestamp`. | `Date32`, `Datetime64`, `Timestamp64` |
10+
| `--float-mode <value>` | Specifies the data type to use for fractional fields. Possible values are `float`, `decimal`, and `decimal_ydb`. `float` uses the `Float` type, `decimal` uses `Decimal` with dimensions specified by the test standard, and `decimal_ydb` uses `Decimal(22,9)` — the only type currently supported by {{ ydb-short-name }}. | `float` |
11+
| `--clear` | If the table at the specified path already exists, it will be deleted. | |

‎ydb/docs/en/core/reference/ydb-cli/_includes/workload/load_options.md

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
### Common parameters of the import command {#load_options}
2+
3+
| Name | Description | Default value |
4+
|----------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------|
5+
| `--upload-threads <value>` or `-t <value>` | The number of execution threads for data preparation. | The number of available cores on the client. |
6+
| `--bulk-size <value>` | The size of the chunk for sending data, in rows. | 10000 |
7+
| `--max-in-flight <value>` | The maximum number of data chunks that can be processed simultaneously. | 128 |

‎ydb/docs/en/core/reference/ydb-cli/_includes/workload/run_options.md

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
### Common parameters for all load types {#run_options}
2+
3+
| Name | Description | Default value |
4+
|------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------|
5+
| `--output <value>` | The name of the file where the query execution results will be saved. | `results.out` |
6+
| `--iterations <value>` | The number of times each load query will be executed. | `1` |
7+
| `--json <name>` | The name of the file where query execution statistics will be saved in `json` format. | Not saved by default |
8+
| `--ministat <name>` | The name of the file where query execution statistics will be saved in `ministat` format. | Not saved by default |
9+
| `--plan <name>` | The name of the file to save the query plan. Files like `<name>.<query number>.explain` and `<name>.<query number>.<iteration number>` will be saved in formats: `ast`, `json`, `svg`. | Not saved by default |
10+
| `--query-settings <setting>` | Query execution settings. Each setting is added as a separate line at the beginning of each query. Use multiple times for multiple settings. | Not specified by default |
11+
| `--include` | Query numbers or segments to be executed as part of the load. | All queries executed |
12+
| `--exclude` | Query numbers or segments to be excluded from the load. | None excluded by default |
13+
| `--executer` | Query execution engine. Available values: `scan`, `generic`. | `generic` |
14+
| `--verbose` or `-v` | Print additional information to the screen during query execution. | |

‎ydb/docs/en/core/reference/ydb-cli/commands/workload/_includes/index.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,5 +25,6 @@ The following types of load tests are supported at the moment:
2525
* [Key-value](../../../workload-kv.md): Key-Value load.
2626
* [ClickBench](../../../workload-click-bench.md): [ClickBench analytical benchmark](https://github.com/ClickHouse/ClickBench).
2727
* [TPC-H](../../../workload-tpch.md): [TPC-H benchmark](https://www.tpc.org/tpch/).
28+
* [TPC-DS](../../../workload-tpcds.md): [TPC-DS benchmark](https://www.tpc.org/tpcds/).
2829
* [Topic](../../../workload-topic.md): Topic load.
2930
* [Transfer](../../../workload-transfer.md): Transfer load.

‎ydb/docs/en/core/reference/ydb-cli/toc_i.yaml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -125,5 +125,7 @@ items:
125125
href: workload-transfer.md
126126
- name: TPC-H load
127127
href: workload-tpch.md
128+
- name: TPC-DS load
129+
href: workload-tpcds.md
128130
- name: Configuration
129131
href: configs.md

0 commit comments

Comments
 (0)