KaiwuDB Benchmark

KaiwuDB Benchmark 是一款专为 KaiwuDB 数据库设计的性能基准测试工具，支持高并发批量数据写入与查询两大核心功能。用户通过简单的 JSON 配置文件定义测试参数（如线程数、数据结构、写入/查询规则等），即可快速执行性能测试并生成结构化结果报告，适用于评估 KaiwuDB 在不同业务场景下的吞吐量、延迟等核心性能指标。

功能特性

多场景测试支持
- 写入测试
  - 支持时序/非时序数据写入，可配置并发线程数、批次提交量、模拟设备总数、每个设备的数据量数据乱序比例。
  - 支持定义数据时间戳的起始时间与数据生成间隔，精确控制时间序列。
- 查询测试
  - 支持多线程并发查询自定义 SQL 语句，自动统计查询延迟与吞吐量。
  - 支持查询全部设备、指定单个设备的最新一行或最新一列的数据。
  - 支持查询全部设备，指定单个设备、指定多个设备在特定时间窗口内的数据。
  - 支持对全表或指定设备在特定时间段进行聚合计算（COUNT、SUM、AVG、MIN、MAX）。
灵活的配置能力：通过 JSON 文件统一配置测试参数，包括：
- 数据库连接信息（如主机、端口、用户名、密码等）
- 测试类型（写入测试/查询测试）、并发线程数
- 表结构定义（如字段类型、标签、主键）、数据生成规则（时间戳范围、乱序比例）
- 测试结果输出路径
多维度性能统计
- 写入测试：总生成数据量、成功写入量、写入吞吐量（行/秒）、数据乱序比例、执行耗时
- 查询测试：查询总次数、失败/成功次数、每秒查询量（QPS）、最大/最小/平均延迟、错误率

工作原理

KaiwuDB Benchmark 通过配置驱动和多线程并发的方式模拟真实业务场景，实现对 KaiwuDB 数据库的性能测试。下图说明 KaiwuDB Benchmark 的核心工作原理：

指定测试配置文件路径：用户指定测试配置文件的路径。
解析与校验：KaiwuDB Benchmark 解析命令行参数，校验配置文件路径并启动测试流程。
读取配置：KaiwuDB Benchmark 读取配置文件，解析数据库连接信息、测试类型、并发参数、数据生成规则等内容。
准备环境：KaiwuDB Benchmark 根据配置信息，自动创建数据库（时序库/普通库）和表，确保测试环境的一致性。
说明
使用 C++ 语言运行 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	批量插入行数说明使用 C++ 语言运行 KaiwuDB Benchmark 基准测试工具时，如果每秒数据生成不足，以当前生成频率数据总量入库。	是	`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`

`tags` 节点配置

当写入数据表为时序表时，用户需要配置 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"]`

写入行为配置

参数	类型	说明	必选项	示例值
`num_of_records_per_req`	Long	数据入库周期内（默认为 `1s`），单个设备产生的总数据量。默认为 `1000`。说明该参数仅适用于使用 C++ 语言运行 KaiwuDB Benchmark 基准测试工具。	否	`1000`
`prepared_rand`	Long	批量插入行数时，产生的随机时间数量间隔。默认为 `50`。说明该参数仅适用于使用 C++ 语言运行 KaiwuDB Benchmark 基准测试工具。	否	`50`

查询测试配置

本节列出查询测试适用的配置参数。

`database` 节点配置

database 节点配置用于定义目标数据库的相关参数。下表列出 database 节点的配置参数。

参数	类型	说明	必选项	示例值
`name`	String	数据库的名称	是	`test_db`
`query_sql`	Array	查询 SQL 配置	是	-
`tablename`	String	待查询的表名说明该参数仅适用于使用 C++ 语言运行 KaiwuDB Benchmark 基准测试工具。	是	-

`query_sql` 节点配置

query_sql 节点配置用于支持多组 SQL 语句的并行查询。下表列出 query_sql 节点的配置参数。

说明

query_sql 节点配置中的 thread_count、query_times、和 query_interval 参数的优先级大于 database 节点下对应参数的优先级。如果 query_sql 节点配置参数存在，则使用 query_sql 节点配置参数。如果不存在，则使用上级节点的配置参数。
使用 C++ 语言运行 KaiwuDB Benchmark 基准测试工具时，不支持在 query_sql 节点配置 thread_count 参数。

参数	类型	说明	必选项	示例值
`sql`	String	查询 SQL 语句	是	`select last_row(*) from meters`
`thread_count`	Int	执行 SQL 语句的线程数	否	`3`
`query_times`	Int	单线程执行次数	否	`10`
`query_interval`	Long	SQL 语句执行间隔（单位：毫秒）	否	`1`

支持的数据类型

下表列出使用 C++ 语言运行 KaiwuDB Benchmark 基准测试工具时支持的数据类型。

类型	名称
二进制类型	BINARY
CHAR 类型	CHAR
NCHAR 类型	NCHAR
VARCHAR 类型	VARCHAR
VARBINARY 类型	VARBINARY
布尔类型	BOOL
整型一字节	TINYINT
无符号整型一字节	UTINYINT
整型二字节	SMALLINT
无符号整型二字节	USMALLINT
整型四字节	INT
无符号整型四字节	UINT
整型八字节	BIGINT
无符号整型八字节	UBIGINT
FLOAT 类型	FLOAT
DOUBLE 类型	DOUBLE

下表列出使用 Java 语言运行 KaiwuDB Benchmark 基准测试工具时支持的关系数据类型。

类型		名称
数值类型	整数类型	TINYINT INT2/SMALLINT INT4/INT/INTEGER INT8/INT64/BIGINT
	浮点类型	FLOAT8/DOUBLE/DOUBLE PRECISION/FLOAT FLOAT4/REAL
	定点类型	DECIMAL/DEC/NUMERIC
	SERIAL类型	SERIAL
时间和日期类型	时间戳	TIMESTAMP/TIMESTAMPTZ
	日期	DATE
	时间	TIME/TIME WITHOUT TIME ZONE
	间隔	INTERVAL
布尔类型		BOOL/BOOLEAN
字符类型		BIT/VARBIT BYTES/BYTEA/VARBYTES CHAR/CHARACTER/NCHAR/VARCHAR/NVARCHAR COLLATE/BLOB/CLOB
JSON 类型		JSONB/JSON
数组类型		INT ARRAY / STRING[] 等任意类型
INET 类型		INET
UUID 类型		UUID

下表列出使用 Java 语言运行 KaiwuDB Benchmark 基准测试工具时支持的时序数据类型。

类型		名称
数值类型	整数类型	INT2/SMALLINT INT4/INT/INTEGER INT8/INT64/BIGINT
	浮点类型	FLOAT8/DOUBLE/DOUBLE PRECISION/FLOAT FLOAT4/REAL
时间类型		TIMESTAMP/TIMESTAMPTZ
布尔类型		BOOL/BOOLEAN
字符类型		VARBYTES CHAR/CHARACTER/NCHAR/VARCHAR/NVARCHAR GEOMETRY

使用举例

本节说明如何使用 Java 或 C++ 语言运行 KaiwuDB Benchmark 基准测试工具，进行写入测试和查询测试。

前提条件

联系open in new window KaiwuDB 技术支持人员，获取 KaiwuDB Benchmark 安装包。
安装 KaiwuDB 数据库、配置数据库认证方式、创建数据库。
创建具有表级别及以上操作权限的用户。
安装 openJDKopen in new window（1.8 及以上版本）。该操作仅适用于使用 Java 语言运行 KaiwuDB Benchmark 基准测试工具。
安装 libpq。该操作仅适用于使用 C++ 语言运行 KaiwuDB Benchmark 基准测试工具。
```
# centos
yum install libpq-devel
# ubuntu
apt install libpq-dev
```

写入测试示例

准备写入测试配置文件。

以下是写入测试配置文件（insert_config.json）示例。该写入测试示例启动 10 个线程，平均分配 100 台设备，每个线程负责 10 台设备，根据配置的时间戳和递增步长，批量写入数据。

{  
  "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": "/kwdb-benchmark/file/insert_result.txt",  // 结果输出路径  
  "database": {  
    "name": "test_db",  // 目标数据库名称  
    "time_series": true,  // 启用时序数据库模式  
    "drop": true,  // 测试前删除并重建数据库（确保环境清洁）  
    "table": {  
      "name": "meters",  // 目标表名  
      "child_prefix": "dev",  // 设备ID前缀（生成设备标识为dev1~dev100）  
      "child_count": 100,  // 设备总数  
      "child_insert_rows": 96369,  // 单设备写入行数  
      "batch_size": 1000,  // 批量插入行数（每1000行执行一次SQL）  
      "start_timestamp": "2025-09-17 13:00:00.000",  // 起始时间戳  
      "timestamp_step": 1,  // 时间戳递增步长（毫秒）  
      "insert_interval": 1000,  // 数据入库频率（毫秒）
      "disorder_ratio": 10,  // 时间戳乱序比例（10%的数据随机偏移，最大为 100%）  
      "disorder_range": [0, 50],  // 乱序时间范围（0~50毫秒）  
      "columns": [  // 表字段配置（含类型及取值范围）  
        {"name": "p1", "type": "BOOLEAN"},  
        {"name": "p2", "type": "INT4", "min": 10, "max": 100},  
        {"name": "p3", "type": "INT4", "min": 100, "max": 2000},  
        {"name": "p4", "type": "INT8", "min": 1000, "max": 50000},  
        {"name": "p5", "type": "FLOAT"},  
        {"name": "p6", "type": "BOOLEAN"},  
        {"name": "p7", "type": "INT4"},  
        {"name": "p8", "type": "FLOAT"},  
        {"name": "p9", "type": "INT8"},  
        {"name": "p10", "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", "JiNan"]  // 标签可选值（随机选取）  
        }  
      ]  
    }  
  }  
}

解压缩 KaiwuDB Benchmark 安装包，进入安装包目录，然后运行以下命令。
```
# Java 版本启动命令
java -jar kwdbBenchmark.jar /path/insert_config.json

# C++ 版本启动命令
./kwdbBenchmark -f /path/insert_config.json
```
执行完成后，KaiwuDB Benchmark 会先删除并重建数据库，然后创建时序表，再启动多线程批量写入数据。写入完成后，KaiwuDB Benchmark 将统计结果打印到命令行输出日志，并写入由 result_file 参数指定的文件中。以下是写入测试结果示例：
```
2025-10-24 15:37:18.610 [main] INFO  c.k.benchmark.service.DataStatistics - ===== Data Insert Summary =====
2025-10-24 15:37:18.626 [main] INFO  c.k.benchmark.service.DataStatistics - Total generated data: 9,636,900 rows
2025-10-24 15:37:18.630 [main] INFO  c.k.benchmark.service.DataStatistics - Using 10 threads, write total data: 9,636,900 rows execution time: 30.028000 s, average write rate: 320,930.465 rows/s, disordered rows: 958,790, actual ratio: 9.95%
```
其中，average write rate（写入吞吐量）表示总写入行数 / 总执行时间，反映 KaiwuDB 数据库的写入性能。actual ratio（乱序比例）表示实际乱序行数占总生成行数的比例，验证乱序配置是否生效。

查询测试示例

准备查询测试配置文件。

以下是查询测试配置文件（query_config.json）示例。该查询测试示例执行两条 SQL 查询语句。第一条查询语句启动 3 个线程，每个线程执行 10 次查询，两次查询间隔 1 毫秒。第二条查询语句启动 2 个线程，每个线程执行 15 次查询。每个线程单独记录每次查询的耗时（毫秒）和状态（成功 / 失败），失败时累计错误次数。

{  
  "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,  // 默认并发线程数（可被SQL级配置覆盖）  
  "query_times": 10,  // 默认单线程查询次数（可被SQL级配置覆盖）  
  "query_interval": 1,  // 默认查询间隔（毫秒，可被SQL级配置覆盖）  
  "result_file": "/kwdb-benchmark/file/query_result.txt",  // 结果输出路径  
  "database": {  
    "name": "test_db",  // 目标数据库名称（与写入测试的数据库一致）  
    "query_sql": [  // 待执行的查询SQL列表  
      {  
        "thread_count": 3,  // 执行该SQL的线程数（覆盖默认值）  
        "query_times": 10,  // 单线程执行次数（覆盖默认值）  
        "query_interval": 1,  // 两次查询间隔（毫秒，覆盖默认值）  
        "sql": "select last_row(*) from meters"  // 查询表中最新数据  
      },  
      {  
        "thread_count": 2,  // 执行该SQL的线程数  
        "query_times": 15,  // 单线程执行次数  
        "sql": "select count(*) from meters where device='dev1'"  // 统计指定设备的数据量  
      }  
    ]  
  }  
}

解压缩 KaiwuDB Benchmark 安装包，进入安装包目录，然后运行以下命令。

# Java 版本启动命令
java -jar kwdbBenchmark.jar /path/query_config.json

# C++ 版本启动命令
./kwdbBenchmark -f /path/query_config.json

执行完成后，KaiwuDB Benchmark 连接已创建的数据库，启动多线程循环执行指定的 SQL 查询语句。查询完成后，系统将 QPS、延迟、错误率等指标打印到命令行输出日志，并写入由 result_file 参数指定的文件中。以下是查询测试结果示例：

2025-10-24 15:47:51.227 [main] INFO  c.k.benchmark.service.DataStatistics - ===== Data Query Summary =====
2025-10-24 15:47:51.232 [main] INFO  c.k.benchmark.service.DataStatistics - Completed 30 queries with 3 threads in 1.533000 seconds. Min delay: 2 ms, Max delay: 1508 ms, Avg delay: 152.500 ms. 
2025-10-24 15:47:51.233 [main] INFO  c.k.benchmark.service.DataStatistics - Execute SQL: select last_row(*) from meters
2025-10-24 15:47:51.233 [main] INFO  c.k.benchmark.service.DataStatistics - Performance metrics: QPS=19.569, Total errors=0 (Error rate=0.000%)

2025-10-24 15:47:51.275 [main] INFO  c.k.benchmark.service.DataStatistics - ===== Data Query Summary =====
2025-10-24 15:47:51.276 [main] INFO  c.k.benchmark.service.DataStatistics - Completed 30 queries with 2 threads in 0.030000 seconds. Min delay: 1 ms, Max delay: 8 ms, Avg delay: 1.867 ms. 
2025-10-24 15:47:51.276 [main] INFO  c.k.benchmark.service.DataStatistics - Execute SQL: select count(*) from meters where device='dev1'
2025-10-24 15:47:51.276 [main] INFO  c.k.benchmark.service.DataStatistics - Performance metrics: QPS=1000.000, Total errors=0 (Error rate=0.000%)

其中，QPS 表示总查询次数 / 总执行时间，反映 KaiwuDB 数据库的查询吞吐量。Min delay 或 Max delay 表示最小/最大查询耗时，反映查询响应速度。Total errors 表示错误查询次数 / 总查询次数，反映查询稳定性。

# KaiwuDB Benchmark

# 功能特性

# 工作原理

# 配置文件说明

# 通用配置

# 写入测试配置

# database 节点配置

# table 节点配置

# columns 节点配置

# tags 节点配置

# 写入行为配置

# 查询测试配置

# database 节点配置

# query_sql 节点配置

# 支持的数据类型

# 使用举例

# 前提条件

# 写入测试示例

# 查询测试示例

KaiwuDB Benchmark

功能特性

工作原理

配置文件说明

通用配置

写入测试配置

`database` 节点配置

`table` 节点配置

`columns` 节点配置

`tags` 节点配置

写入行为配置

查询测试配置

`database` 节点配置

`query_sql` 节点配置

支持的数据类型

使用举例

前提条件

写入测试示例

查询测试示例