KaiwuDB Benchmark
KaiwuDB Benchmark 是一款专为 KaiwuDB 数据库设计的性能基准测试工具，支持高并发批量数据写入与查询两大核心功能。用户通过简单的 JSON 配置文件定义测试参数（如线程数、数据结构、写入/查询规则等），即可快速执行性能测试并生成结构化结果报告，适用于评估 KaiwuDB 在不同业务场景下的吞吐量、延迟等核心性能指标。
功能特性
- 多场景测试支持
- 写入测试：支持时序/非时序数据写入，可配置批量插入、多线程并发、数据乱序比例。
- 查询测试：支持多线程并发查询自定义 SQL 语句，自动统计查询延迟与吞吐量。
- 灵活的配置能力：通过 JSON 文件统一配置测试参数，包括：
- 数据库连接信息（如主机、端口、用户名、密码等）
- 测试类型（写入测试/查询测试）、并发线程数
- 表结构定义（如字段类型、标签、主键）、数据生成规则（时间戳范围、乱序比例）
- 测试结果输出路径
- 多维度性能统计
- 写入测试：总生成数据量、成功写入量、写入吞吐量（行/秒）、数据乱序比例、执行耗时
- 查询测试：查询总次数、失败/成功次数、每秒查询量（QPS）、最大/最小/平均延迟、错误率
工作原理
KaiwuDB Benchmark 通过配置驱动和多线程并发的方式模拟真实业务场景，实现对 KaiwuDB 数据库的性能测试。下图说明 KaiwuDB Benchmark 的核心工作原理：
指定测试配置文件路径：用户指定测试配置文件的路径。
解析与校验：KaiwuDB Benchmark 解析命令行参数，校验配置文件路径并启动测试流程。
读取配置：KaiwuDB Benchmark 读取配置文件，解析数据库连接信息、测试类型、并发参数、数据生成规则等内容。
准备环境：KaiwuDB Benchmark 根据配置信息，自动创建时序库和表，确保测试环境的一致性。
执行测试任务。
- 写入测试：KaiwuDB Benchmark 按规则生成随机数据（支持时间戳乱序），批量插入数据并记录每个线程的执行指标。
- 查询测试：KaiwuDB Benchmark 循环执行自定义 SQL 语句，控制查询间隔，记录每次查询的耗时与结果。
生成报告：KaiwuDB Benchmark 汇总所有线程的执行数据，计算吞吐量、延迟、错误率等关键指标，并输出可视化报告。
配置文件说明
KaiwuDB Benchmark 支持 insert（写入测试）和 query（查询测试）两种类型。用户需要分别通过 JSON 文件统一配置对应的测试参数。
通用配置
下表列出写入测试和查询测试均适用的配置参数。
| 参数 | 类型 | 说明 | 必选项 | 示例值 |
|---|---|---|---|---|
type | String | 测试类型，取值为 insert 或 query | 是 | insert |
host | String | KaiwuDB 数据库的 IP 地址 | 是 | 127.0.0.1 |
port | Int | KaiwuDB 数据库的端口号 | 是 | 26257 |
user | String | KaiwuDB 数据库的用户名 | 是 | test |
password | String | KaiwuDB 数据库的密码 | 是 | Password@123 |
cert_auth | Boolean | 是否启用证书认证 | 是 | false |
cert_path | String | 证书路径 | 否 | /home/kaiwudb/certs |
cert_type | String | 安全协议类型，取值为 TLS 或 TLCP | 否 | tls |
thread_count | Int | 全局并发线程数 | 是 | 10 |
query_times | Int | 单线程查询次数。该参数仅适用于 query 类型。 | 否 | 10 |
query_interval | Long | 两次查询的时间间隔。该参数仅适用于 query 类型。 | 否 | 1 |
result_file | String | 测试结果的输出文件路径，默认值为 ../file/result.txt | 是 | /home/kaiwudb/file/result.txt |
database | Object | 数据库配置（嵌套参数） | 否 | - |
写入测试配置
本节列出写入测试适用的配置参数。
database 节点配置
在通用配置的基础上，用户需要通过 database 节点定义写入测试和查询测试的相关参数。下表列出 database 节点的配置参数。
| 参数 | 类型 | 说明 | 必选项 | 示例值 |
|---|---|---|---|---|
name | String | 数据库的名称 | 是 | test_db |
time_series | Boolean | 是否为时序数据库，取值为 true 或者 false。默认为 false。 | 是 | false |
drop | Boolean | 测试前是否删除重建数据库，取值为 true 或者 false。默认为 false。 | 是 | false |
table | Object | 表结构配置（嵌套参数） | 是 | - |
table 节点配置
table 节点配置用于定义时序表/普通表的表结构创建与数据生成规则。下表列出 table 节点的配置参数。
| 参数 | 类型 | 说明 | 必选项 | 示例值 |
|---|---|---|---|---|
name | String | 表名 | 是 | meters |
child_prefix | String | 设备 ID 前缀 | 是 | dev |
child_count | Int | 设备总数 | 是 | 100 |
child_insert_rows | Int | 单设备写入行数 | 是 | 96369 |
batch_size | Int | 批量插入行数 | 是 | 1000 |
start_timestamp | String | 起始时间戳，格式为 yyyy-MM-dd HH:mm:ss | 是 | 2025-09-01 00:00:00 |
timestamp_step | Long | 时间戳递增步长（单位：毫秒） | 是 | 1 |
insert_interval | Long | 数据入库频率（单位：毫秒） | 是 | 1000 |
disorder_ratio | Int | 时间戳乱序比例（百分比，0-100）。取值为 0 时，表示不启用乱序功能。说明 该参数仅适用于时序表。 | 是 | 10 |
disorder_range | Array | 乱序时间范围，格式为 [min，max]（单位：毫秒） | 是 | [0, 50] |
columns | Array | 字段配置（嵌套参数） | 是 | - |
tags | Array | 标签配置。该参数仅适用于时序表。 | 否 | - |
columns 节点配置
下表列出每个 table 节点配置中的 columns 节点的配置参数。
说明
对于时序表，默认包含 ts 字段（TIMESTAMPTZ 类型），因此用户无需在 columns 节点中重复定义该字段。
| 参数 | 类型 | 说明 | 必选项 | 示例值 |
|---|---|---|---|---|
name | String | 字段名 | 是 | p1 |
type | String | 字段类型 | 是 | int4 |
non_null | Boolean | 是否非空，取值为 true 或者 false | 否 | false |
min | Int | 随机值最小值。该参数仅适用于数值类型。 | 否 | 0 |
max | Int | 随机值最大值。该参数仅适用于数值类型。 | 否 | 100 |
tag 节点配置
当写入数据表为时序表时，用户需要配置 tags 节点信息。下表列出每个 table 节点配置中的 tags 节点的配置参数。
说明
对于时序表，第一个标签列类型必须是 VARCHAR 类型，且第一个标签列必须是主标签并设置为非空列。标签列的值是由设备 ID 前缀（child_prefix）和设备 ID 拼接组成，例如 dev1、dev2、dev3。
| 参数 | 类型 | 说明 | 必选项 | 示例值 |
|---|---|---|---|---|
name | String | 标签名 | 是 | location |
type | String | 标签类型（支持字符串、数值等） | 是 | VARCHAR(20) |
primary | Boolean | 是否为主键标签，取值为 true 或者 false | 否 | false |
non_null | Boolean | 是否非空，取值为 true 或者 false | 否 | false |
values | Array | 标签可选值 [a,b,c] 中随机选取。该参数仅适用于非设备 ID 标签。 | 非设备 ID 标签时必选 | ["TianJin","Beijing"] |
查询测试配置
本节列出查询测试适用的配置参数。
database 节点配置
在通用配置的基础上，用户需要通过 database 节点定义写入测试和查询测试的相关参数。下表列出 database 节点的配置参数。
| 参数 | 类型 | 说明 | 必选项 | 示例值 |
|---|---|---|---|---|
name | String | 数据库的名称 | 是 | test_db |
query_sql | Array | 查询 SQL 配置。 | 是 | - |
query_sql 节点配置
query_sql 节点配置用于支持多组 SQL 语句的并行查询。下表列出 query_sql 节点的配置参数。
说明
query_sql 节点配置中的 thread_count、query_times、和 query_interval 参数的优先级大于 database 节点下对应参数的优先级。如果 query_sql 节点配置参数存在，则使用 query_sql 节点配置参数。如果不存在，则使用上级节点的配置参数。
| 参数 | 类型 | 说明 | 必选项 | 示例值 |
|---|---|---|---|---|
sql | String | 查询 SQL 语句 | 是 | select last_row(*) from meters |
thread_count | Int | 执行 SQL 语句的线程数 | 否 | 3 |
query_times | Int | 单线程执行次数 | 否 | 10 |
query_interval | Long | SQL 语句执行间隔（单位：毫秒） | 否 | 1 |
使用举例
本节说明如何使用 KaiwuDB Benchmark 进行写入测试和查询测试。
前提条件
联系 KaiwuDB 技术支持人员，获取 KaiwuDB Benchmark 安装包。
安装 KaiwuDB 数据库、配置数据库认证方式、创建数据库。
创建具有表级别及以上操作权限的用户。
安装 openJDK（1.8 及以上版本）。该操作仅适用于使用 Java 语言运行 KaiwuDB Benchmark 基准测试工具。
安装 libpq。该操作仅适用于使用 C++ 语言运行 KaiwuDB Benchmark 基准测试工具。
# centos yum install libpq-devel # ubuntu apt install libpq-dev
写入测试示例
准备写入测试配置文件。
根据测试需求，用户需要创建
insert_config.json（写入测试配置文件）。以下是写入测试配置文件示例。{ "type": "insert", "host": "127.0.0.1", "port": 26257, "user": "test", "password": "Password@2024", "cert_auth": false, "cert_path": "/home/kaiwudb/certs", "cert_type": "tls", "thread_count": 10, "result_file": "/home/kaiwudb/file/insert_result.txt", "database": { "name": "test_db", "time_series": true, "drop": true, "table": { "name": "meters", "child_prefix": "dev", "child_count": 100, "child_insert_rows": 96369, "batch_size": 1000, "start_timestamp": "2025-09-17 13:00:00.000", "timestamp_step": 1, "insert_interval": 1000, "disorder_ratio": 10, "disorder_range": [ 0, 50 ], "columns": [ { "name": "p1", "type": "BOOLEAN" }, { "name": "p2", "type": "INT4", "min": 10, "max": 100 }, { "name": "p3", "type": "FLOAT" } ], "tags": [ { "name": "device", "type": "VARCHAR(16)", "primary": true, "non_null": true }, { "name": "location", "type": "VARCHAR(20)", "primary": false, "non_null": false, "values": [ "TianJin", "BeiJing", "ShangHai" ] } ] } } }解压缩 KaiwuDB Benchmark 安装包，进入安装包目录，然后运行以下命令。
# Java 版本启动命令 java -jar kwdbBenchmark.jar /home/kaiwudb/insert_config.json # C++ 版本启动命令 ./kwdbBenchmark -f insert_config.json执行完成后，KaiwuDB Benchmark 会先删除并重建数据库，然后创建时序表/普通表，再启动多线程批量写入数据。写入完成后，KaiwuDB Benchmark 将统计结果打印到命令行输出日志，并写入由
result_file参数指定的文件中。以下是写入测试结果示例：===== Data Insert Summary ===== Total generated data: 9,636,900 rows # 总生成数据量（子表数×每个子表行数） Spent 97.171000 seconds to insert rows: 9,636,900 with 10 thread(s), real write time: 19.408000 seconds, average write rate: 496,542.663 rows/s, disordered rows: 958,790, actual ratio: 9.95%其中，
average write rate（写入吞吐量）表示总写入行数 / 执行时间，反映 KaiwuDB 数据库的写入性能。actual ratio（乱序比例）表示实际乱序行数占总生成行数的比例，验证乱序配置是否生效。
查询测试示例
准备查询测试配置文件。
根据测试需求，用户需要创建
query_config.json（写入测试配置文件）。以下是查询测试配置文件示例。{ "type": "query", "host": "127.0.0.1", "port": 26257, "user": "test", "password": "Password@2024", "cert_auth": false, "cert_path": "/home/kaiwudb/certs", "cert_type": "tls", "thread_count": 10, "query_times": 10, "query_interval": 1, "result_file": "/home/kaiwudb/file/query_result.txt", "database": { "name": "test_db", "query_sql": [ { "thread_count": 3, "query_times": 10, "query_interval": 1, "sql": "select last_row(*) from meters" } ] } }解压缩 KaiwuDB Benchmark 安装包，进入安装包目录，然后运行以下命令。
# Java 版本启动命令 java -jar kwdbBenchmark.jar /home/kaiwudb/query_config.json # C++ 版本启动命令 ./kwdbBenchmark -f query_config.json执行完成后，KaiwuDB Benchmark 连接已创建的数据库，启动多线程循环执行指定的 SQL 查询语句。查询完成后，系统将 QPS、延迟、错误率等指标打印到命令行输出日志，并写入由
result_file参数指定的文件中。以下是查询测试结果示例：===== Data Query Summary ===== Completed 30 queries with 3 threads in 1.433000 seconds. Min delay: 3 ms, Max delay: 1402 ms, Avg delay: 141.333 ms. SQL: select last_row(*) from meters Performance metrics: QPS=20.935, Total errors=0 (Error rate=0.000%)其中，
QPS表示总查询次数 / 执行时间，反映 KaiwuDB 数据库的查询吞吐量。Min delay或Max delay表示最小/最大查询耗时，反映查询响应速度。Total errors表示错误查询次数 / 总查询次数，反映查询稳定性。