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 根据配置信息，自动创建数据库（时序库/普通库）和表，确保测试环境的一致性。
执行测试任务。
- 写入测试：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`

`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"]`

查询测试配置

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

`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 基准测试工具支持的关系数据类型。

类型		名称
数值类型	整数类型	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

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

使用举例

本节说明如何运行 KaiwuDB Benchmark 基准测试工具，进行写入测试和查询测试。

前提条件

联系open in new window KaiwuDB 技术支持人员，获取 KaiwuDB Benchmark 安装包。
安装 KaiwuDB 数据库、配置数据库认证方式、创建数据库。
创建具有表级别及以上操作权限的用户。
安装 openJDKopen in new window（1.8 及以上版本）。

写入测试示例

准备写入测试配置文件。

以下是写入测试配置文件（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 -jar kwdbBenchmark.jar /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 -jar kwdbBenchmark.jar /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` 节点配置

支持的数据类型

使用举例

前提条件

写入测试示例

查询测试示例