This document describes the detailed parameters of MatrixBench.
Note!
mxbench is now open-source. Code review and contributions are welcome. Please click here to read the README.
| Parameter | Default Value | Description |
|---|---|---|
| [Database] Category | ||
| --db-database | postgres | Database name. If it does not exist, MatrixBench will create it automatically; no error is raised if it already exists |
| --db-master-host | localhost | Hostname of the YMatrix Master instance |
| --db-master-port | 5432 | Port number of the YMatrix Master instance |
| --db-password | Password for the YMatrix user | |
| --db-user | mxadmin | Username for the YMatrix user |
| [Global] Category | ||
| --workspace | /tmp/mxbench | Directory for CSV data files and query files. Under the workspace directory, mxbench creates a subdirectory named with the UNIX timestamp when mxbench starts. DDL scripts, GUCs scripts, and query files are generated under this subdirectory. If --dump is set to true, exported CSV data files are also generated here |
| --dump | false | Whether to export CSV data files. If set to true, only data export occurs, without data loading or query execution |
| --watch | true | Whether to enable process monitoring. Enabled by default. Progress information from the Writer and Benchmark modules is printed every 5 seconds |
| --log-level | info | Log level. Supported values: debug / verbose / info / error |
| --skip-set-gucs | false | Whether to skip prompting and setting parameters. By default, mxbench prompts whether to reset and restart the database, and selects appropriate parameter settings based on the data characteristics defined in the configuration |
| --simultaneous-loading-and-query | false | Whether to perform data loading and querying simultaneously. By default, data is loaded first, followed by query execution. If set to true, mixed workload (loading and querying) is executed. In mixed workload mode, queries loop until data loading finishes |
| --ddl-file-path | Path to a custom DDL file. By default, DDL is auto-generated based on other configurations | |
| --metrics-type | float8 | Data type for metrics. Supported types: int4 / int8 / float4 / float8 |
| --metrics-descriptions | Metric descriptions. Must follow the syntax described in the "Multiple Data Types and Characteristics" section of the Basic Features documentation to generate data with customized characteristics | |
| --partition-interval-in-hour | 24 | Time interval (in hours) for table partitioning in generated DDL. Default is 24 (one day). Set to 0 to let mxbench choose randomly |
| --realtime | false | Real-time mode. If set to true, timestamps in generated data are based on the current runtime. Every --ts-step-in-second seconds, --tag-num rows are generated. --ts-start and --ts-end are used to create table partitions |
| --report-format | csv | Format of the SQL execution statistics report. Only CSV is supported |
| --report-path | /tmp | Output path for SQL execution statistics reports |
| --schema-name | public | Schema name |
| --table-name | Table name. Default is "", must be set manually | |
| --tag-num | 25000 | Number of devices |
| --total-metrics-count | 300 | Total number of metrics. If greater than 998, excess metrics are stored as JSON in a column named "ext" |
| --ts-start | Start timestamp for generated data. Due to delayed reporting, some data may have timestamps earlier than this | |
| --ts-end | End timestamp for generated data. --ts-end must be later than --ts-start; otherwise, an error occurs |
|
| --ts-step-in-second | 1 | Interval (in seconds) between metric samples |
| [Generator] Category | ||
| --generator | telematics | Data generator. Default is telematics (vehicle telemetry). Supported: telematics / file / nil. file reads data from CSV files; nil generates no data |
| generator = "telematics" | ||
| --generator-batch-size | 1 | Number of rows per device per timestamp sent to YMatrix. For example, if set to 5, data for device tag1 at timestamp 2022-04-25 09:00:03 is split into 5 rows, merged into one tuple. Default is 1 (no split) |
| --generator-disorder-ratio | 0 | Ratio of out-of-order (delayed) data. Range: 0～100. Default: 0 (no delayed data) |
| --generator-empty-value-ratio | 90 | Percentage of NULL values per row. Range: 0–100. Default: 90% |
| --generator-randomness | OFF | Data randomness level. Supported: OFF / S / M / L |
| --generator-num-goroutine | 1 | Number of concurrent goroutines for data generation |
| --generator-write-batch-size | 4 | Buffer size for generated data (in MB) |
| generator = "file" | ||
| --generator-file-paths | Absolute paths to CSV data files. Multiple files can be provided as an array | |
| --generator-batch-size | 1 | Same as generator = "telematics"'s --generator-batch-size parameter (optional; invalid if custom DDL is used) |
| --generator-empty-value-ratio | 90 | Same as generator = "telematics"'s --generator-empty-value-ratio parameter (optional; invalid if custom DDL is used) |
| generator = "nil" (no additional parameters) | ||
| [Writer] Category | ||
| --writer | Method to start mxgate and write data. Supported: http / stdin / nil |
|
| writer = "http" | ||
| --writer-use-gzip | false | Whether to compress HTTP messages with Gzip |
| --writer-parallel | 8 | Concurrency level for sending data to mxgate |
| --writer-mxgate-path | Environment variable path | Path to mxgate binary. Default uses the environment variable path |
| --writer-progress-format | list | Format of Writer progress output. Supported: list / json |
| --writer-progress-include-table-size | false | Whether Writer progress includes table size |
| --writer-progress-with-timezone | false | Whether Writer progress includes timezone information |
| --writer-interval | -1 | Sets mxgate's --interval parameter. Default -1 (auto-selected by mxbench; advanced debug parameter) |
| --writer-stream-prepared | -1 | Sets mxgate's --stream-prepared parameter. Default -1 (auto-selected by mxbench; advanced debug parameter) |
| writer = "stdin" | ||
| --writer-mxgate-path | Environment variable path | Same as writer = "http"'s --writer-mxgate-path parameter |
| --writer-progress-format | list | Same as writer = "http"'s --writer-progress-format parameter |
| --writer-progress-include-table-size | false | Same as writer = "http"'s --writer-progress-include-table-size parameter |
| --writer-progress-with-timezone | false | Same as writer = "http"'s --writer-progress-with-timezone parameter |
| --writer-interval | -1 | Same as writer = "http"'s --writer-interval parameter |
| --writer-stream-prepared | -1 | Same as writer = "http"'s --writer-stream-prepared parameter |
| writer = "nil" (no additional parameters) | ||
| [Benchmark] Category | ||
| --benchmark | telematics | Query generator and executor. Supported: telematics / nil |
| benchmark = "telematics" | ||
| --benchmark-run-query-names | List of Telematics query names to execute in order. Currently supported queries: 1. SINGLE_TAG_LATEST_QUERY: Get latest metrics for a single vehicle;2. MULTI_TAG_LATEST_QUERY: Randomly select 10 vehicles and get their latest metrics;3. SINGLE_TAG_DETAIL_QUERY: Get metrics for a single vehicle over a time range;Example: [ "SINGLE_TAG_LATEST_QUERY", "MULTI_TAG_LATEST_QUERY", "SINGLE_TAG_DETAIL_QUERY" ] executes all three queries in sequence. Other names are ignored. Default is empty (no queries executed) |
|
| --benchmark-custom-queries | Custom queries, separated by commas. Example: ["SELECT COUNT(*) from t1", "SELECT MAX(ts) from t1"]. Default is empty (no custom queries) |
|
| --benchmark-combination-queries | Expression for composite queries. Must follow the syntax described in the "Composite Queries" section of the Basic Features documentation | |
| --benchmark-progress-format | list | Format of Benchmark progress output. Supported: list / json |
| --benchmark-parallel | Query execution concurrency. Multiple concurrency levels can be specified, separated by commas. Example: [1, 8] runs queries first at concurrency 1, then at 8. Default is empty |
|
| --benchmark-run-times | 0 | Number of times each query runs at each concurrency level. mxbench uses multiple runs to calculate latency and TPS statistics |
| --benchmark-runtime-in-second | 60 | Duration (in seconds) each query runs at each concurrency level. Used for latency and TPS statistics. This parameter only takes effect when --benchmark-run-times = 0 |
| benchmark = "nil" |
| Command-line Option | Description |
|---|---|
| --run | Run mxbench from command line |
| --config | Print full configuration file template |
| --help | Show usage and parameter list |
| --version | Show version |
Note!
For main features, see MatrixBench Main Features.
For details on progress messages and statistical reports, see MatrixBench Understanding Progress Information and Reports.
