Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

clickhouse-benchmark

View as MarkdownEdit this pageReport an issueSet up docs MCP

连接到 ClickHouse 服务器，并重复发送指定查询。

语法

$ clickhouse-benchmark --query ["single query"] [keys]

或

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

或

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

如果要发送一组查询，请创建一个文本文件，并将每条查询分别写在文件中的单独一行。例如：

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

然后将此文件传给 clickhouse-benchmark 的标准输入：

clickhouse-benchmark [keys] < queries_file;

命令行选项

  • --query=QUERY — 要执行的查询。若未传入此参数，clickhouse-benchmark 将从标准输入读取查询。
  • --query_id=ID — 查询 ID。
  • --query_id_prefix=ID_PREFIX — 查询 ID 前缀。
  • --queries-format=FORMAT — 从标准输入读取查询时使用的格式。可能的值：tsv (默认值，每行一个经过制表符转义的查询) 和 script (将输入解析为由分号分隔的多查询脚本) 。script 的限制：INSERT ... FORMAT 查询必须写在单独一行。
  • -c N, --concurrency=N — clickhouse-benchmark 同时发送的查询数量。默认值：1。
  • -C N, --max_concurrency=N — 逐步将并发查询数提高到指定值，并针对每个并发级别生成一份报告。
  • --precise — 启用带加权指标的精确分时间间隔报告。
  • -d N, --delay=N — 中间报告之间的时间间隔 (秒) (要禁用报告，请设为 0) 。默认值：1。
  • -h HOST, --host=HOST — 服务器主机。默认值：localhost。在比较模式下，可以使用多个 -h 参数。
  • -i N, --iterations=N — 查询总数。默认值：0 (无限重复) 。
  • -r, --randomize — 如果输入查询多于一个，则按随机顺序执行查询。
  • -s, --secure — 使用 TLS 连接。
  • -t N, --timelimit=N — 时间限制 (秒) 。达到指定时间限制后，clickhouse-benchmark 将停止发送查询。默认值：0 (禁用时间限制) 。
  • --port=N — 服务器端口。默认值：9000。在比较模式下，可以使用多个 --port 参数。
  • --confidence=N — T 检验的置信水平。可能的值：0 (80%)、1 (90%)、2 (95%)、3 (98%)、4 (99%)、5 (99.5%)。默认值：5。在比较模式中，clickhouse-benchmark 会执行独立双样本 Student's t-test，以判断在所选置信水平下两个分布是否可视为无差异。
  • --cumulative — 输出累计数据，而非按时间间隔输出的数据。
  • --database=DATABASE_NAME — ClickHouse 数据库名称。默认值：default。
  • --user=USERNAME — ClickHouse 用户名。默认值：default。
  • --password=PSWD — ClickHouse 用户密码。默认值：空字符串。
  • --stacktrace — 输出堆栈跟踪。设置此参数后，clickhouse-benchmark 会输出异常的堆栈跟踪。
  • --stage=WORD — 服务器上的查询处理阶段。ClickHouse 会在指定阶段停止查询处理，并将结果返回给 clickhouse-benchmark。可能的值：complete、fetch_columns、with_mergeable_state。默认值：complete。
  • --roundrobin — 不再比较不同的 --host/--port，而是为每个查询随机选择一个 --host/--port 并将查询发送到该目标。
  • --reconnect=N — 控制重连行为。可能的值：0 (从不重连) 、1 (每个查询都重连) 或 N (每 N 个查询后重连) 。默认值：0。
  • --max-consecutive-errors=N — 允许的连续错误次数。默认值：0。
  • --ignore-error,--continue_on_errors — 即使查询失败也继续测试。
  • --client-side-time — 显示包含网络通信时间在内的耗时，而非服务器端时间；请注意，对于 22.8 之前的服务器版本，始终显示客户端时间。
  • --proto-caps — 启用/禁用数据传输中的分块。可选值 (可用逗号分隔) ：chunked_optional、notchunked、notchunked_optional、send_chunked、send_chunked_optional、send_notchunked、send_notchunked_optional、recv_chunked、recv_chunked_optional、recv_notchunked、recv_notchunked_optional。默认值：notchunked。
  • --help — 显示帮助信息。
  • --verbose — 提高帮助信息的详细程度。

如果要对查询应用某些设置，请将它们作为参数 --<session setting name>= SETTING_VALUE 传入。例如，--max_memory_usage=1048576。

环境变量选项

可通过环境变量 CLICKHOUSE_USER、CLICKHOUSE_PASSWORD 和 CLICKHOUSE_HOST 设置用户名、密码和主机。 命令行参数 --user、--password 或 --host 的优先级高于环境变量。

输出

默认情况下，clickhouse-benchmark 会在每个 --delay 时间间隔输出一次报告。

报告示例：

Queries executed: 10.

localhost:9000, queries 10, QPS: 6.772, RPS: 67904487.440, MiB/s: 518.070, result RPS: 67721584.984, result MiB/s: 516.675.

0.000%      0.145 sec.
10.000%     0.146 sec.
20.000%     0.146 sec.
30.000%     0.146 sec.
40.000%     0.147 sec.
50.000%     0.148 sec.
60.000%     0.148 sec.
70.000%     0.148 sec.
80.000%     0.149 sec.
90.000%     0.150 sec.
95.000%     0.150 sec.
99.000%     0.150 sec.
99.900%     0.150 sec.
99.990%     0.150 sec.

在报告中，您可以看到：

  • Queries executed: 字段中的查询数量。

  • 状态字符串，依次包含以下内容：

    • ClickHouse 服务器的端点。
    • 已处理的查询数量。
    • QPS：在 --delay 参数指定的时间段内，服务器每秒执行的查询数。
    • RPS：在 --delay 参数指定的时间段内，服务器每秒读取的行数。
    • MiB/s：在 --delay 参数指定的时间段内，服务器每秒读取的 MiB 数。
    • result RPS：在 --delay 参数指定的时间段内，服务器每秒写入查询结果的行数。
    • result MiB/s. 在 --delay 参数指定的时间段内，服务器每秒写入查询结果的 MiB 数。

  • 查询执行时间的百分位数。

比较模式

clickhouse-benchmark 可以比较两个正在运行的 ClickHouse 服务器的性能。

要使用比较模式，请使用两组 --host 和 --port 选项指定两个服务器的端点。这些选项会按照它们在参数列表中的位置进行配对：第一个 --host 对应第一个 --port，依此类推。clickhouse-benchmark 会与两个服务器分别建立连接，然后发送查询。每个查询都会被发送到随机选中的一个服务器。结果将显示在表格中。

示例

$ echo "SELECT * FROM system.numbers LIMIT 10000000 OFFSET 10000000" | clickhouse-benchmark --host=localhost --port=9001 --host=localhost --port=9000 -i 10
Loaded 1 queries.

Queries executed: 5.

localhost:9001, queries 2, QPS: 3.764, RPS: 75446929.370, MiB/s: 575.614, result RPS: 37639659.982, result MiB/s: 287.168.
localhost:9000, queries 3, QPS: 3.815, RPS: 76466659.385, MiB/s: 583.394, result RPS: 38148392.297, result MiB/s: 291.049.

0.000%          0.258 sec.      0.250 sec.
10.000%         0.258 sec.      0.250 sec.
20.000%         0.258 sec.      0.250 sec.
30.000%         0.258 sec.      0.267 sec.
40.000%         0.258 sec.      0.267 sec.
50.000%         0.273 sec.      0.267 sec.
60.000%         0.273 sec.      0.267 sec.
70.000%         0.273 sec.      0.267 sec.
80.000%         0.273 sec.      0.269 sec.
90.000%         0.273 sec.      0.269 sec.
95.000%         0.273 sec.      0.269 sec.
99.000%         0.273 sec.      0.269 sec.
99.900%         0.273 sec.      0.269 sec.
99.990%         0.273 sec.      0.269 sec.

在99.5%置信度下未发现显著差异
Navigation