clickhouse-benchmark

Connects to a ClickHouse server and repeatedly sends specified queries.

Syntax:

  1. $ echo "single query" | clickhouse-benchmark [keys]

or

  1. $ clickhouse-benchmark [keys] <<< "single query"

If you want to send a set of queries, create a text file and place each query on the individual string in this file. For example:

  1. SELECT * FROM system.numbers LIMIT 10000000
  2. SELECT 1

Then pass this file to a standard input of clickhouse-benchmark.

  1. clickhouse-benchmark [keys] < queries_file

Keys

  • -c N, --concurrency=N — Number of queries that clickhouse-benchmark sends simultaneously. Default value: 1.
  • -d N, --delay=N — Interval in seconds between intermediate reports (set 0 to disable reports). Default value: 1.
  • -h WORD, --host=WORD — Server host. Default value: localhost. For the comparison mode you can use multiple -h keys.
  • -p N, --port=N — Server port. Default value: 9000. For the comparison mode you can use multiple -p keys.
  • -i N, --iterations=N — Total number of queries. Default value: 0.
  • -r, --randomize — Random order of queries execution if there is more then one input query.
  • -s, --secure — Using TLS connection.
  • -t N, --timelimit=N — Time limit in seconds. clickhouse-benchmark stops sending queries when the specified time limit is reached. Default value: 0 (time limit disabled).
  • --confidence=N — Level of confidence for T-test. Possible values: 0 (80%), 1 (90%), 2 (95%), 3 (98%), 4 (99%), 5 (99.5%). Default value: 5. In the comparison mode clickhouse-benchmark performs the Independent two-sample Student’s t-test test to determine whether the two distributions aren’t different with the selected level of confidence.
  • --cumulative — Printing cumulative data instead of data per interval.
  • --database=DATABASE_NAME — ClickHouse database name. Default value: default.
  • --json=FILEPATH — JSON output. When the key is set, clickhouse-benchmark outputs a report to the specified JSON-file.
  • --user=USERNAME — ClickHouse user name. Default value: default.
  • --password=PSWD — ClickHouse user password. Default value: empty string.
  • --stacktrace — Stack traces output. When the key is set, clickhouse-bencmark outputs stack traces of exceptions.
  • --stage=WORD — Query processing stage at server. ClickHouse stops query processing and returns answer to clickhouse-benchmark at the specified stage. Possible values: complete, fetch_columns, with_mergeable_state. Default value: complete.
  • --help — Shows the help message.

If you want to apply some settings for queries, pass them as a key --<session setting name>= SETTING_VALUE. For example, --max_memory_usage=1048576.

Output

By default, clickhouse-benchmark reports for each --delay interval.

Example of the report:

  1. Queries executed: 10.
  3. localhost:9000, queries 10, QPS: 6.772, RPS: 67904487.440, MiB/s: 518.070, result RPS: 67721584.984, result MiB/s: 516.675.
  5. 0.000%      0.145 sec.  
  6. 10.000%     0.146 sec.  
  7. 20.000%     0.146 sec.  
  8. 30.000%     0.146 sec.  
  9. 40.000%     0.147 sec.  
  10. 50.000%     0.148 sec.  
  11. 60.000%     0.148 sec.  
  12. 70.000%     0.148 sec.  
  13. 80.000%     0.149 sec.  
  14. 90.000%     0.150 sec.  
  15. 95.000%     0.150 sec.  
  16. 99.000%     0.150 sec.  
  17. 99.900%     0.150 sec.  
  18. 99.990%     0.150 sec.

In the report you can find:

  • Number of queries in the Queries executed: field.

  • Status string containing (in order):

    • Endpoint of ClickHouse server.
    • Number of processed queries.
    • QPS: QPS: How many queries server performed per second during a period specified in the --delay argument.
    • RPS: How many rows server read per second during a period specified in the --delay argument.
    • MiB/s: How many mebibytes server read per second during a period specified in the --delay argument.
    • result RPS: How many rows placed by server to the result of a query per second during a period specified in the --delay argument.
    • result MiB/s. How many mebibytes placed by server to the result of a query per second during a period specified in the --delay argument.
  • Percentiles of queries execution time.

Comparison mode

clickhouse-benchmark can compare performances for two running ClickHouse servers.

To use the comparison mode, specify endpoints of both servers by two pairs of --host, --port keys. Keys matched together by position in arguments list, the first --host is matched with the first --port and so on. clickhouse-benchmark establishes connections to both servers, then sends queries. Each query addressed to a randomly selected server. The results are shown for each server separately.

Example

  1. $ echo "SELECT * FROM system.numbers LIMIT 10000000 OFFSET 10000000" | clickhouse-benchmark -i 10
  1. Loaded 1 queries.
  3. Queries executed: 6.
  5. localhost:9000, queries 6, QPS: 6.153, RPS: 123398340.957, MiB/s: 941.455, result RPS: 61532982.200, result MiB/s: 469.459.
  7. 0.000%      0.159 sec.  
  8. 10.000%     0.159 sec.  
  9. 20.000%     0.159 sec.  
  10. 30.000%     0.160 sec.  
  11. 40.000%     0.160 sec.  
  12. 50.000%     0.162 sec.  
  13. 60.000%     0.164 sec.  
  14. 70.000%     0.165 sec.  
  15. 80.000%     0.166 sec.  
  16. 90.000%     0.166 sec.  
  17. 95.000%     0.167 sec.  
  18. 99.000%     0.167 sec.  
  19. 99.900%     0.167 sec.  
  20. 99.990%     0.167 sec.  
  24. Queries executed: 10.
  26. localhost:9000, queries 10, QPS: 6.082, RPS: 121959604.568, MiB/s: 930.478, result RPS: 60815551.642, result MiB/s: 463.986.
  28. 0.000%      0.159 sec.  
  29. 10.000%     0.159 sec.  
  30. 20.000%     0.160 sec.  
  31. 30.000%     0.163 sec.  
  32. 40.000%     0.164 sec.  
  33. 50.000%     0.165 sec.  
  34. 60.000%     0.166 sec.  
  35. 70.000%     0.166 sec.  
  36. 80.000%     0.167 sec.  
  37. 90.000%     0.167 sec.  
  38. 95.000%     0.170 sec.  
  39. 99.000%     0.172 sec.  
  40. 99.900%     0.172 sec.  
  41. 99.990%     0.172 sec.