社区佳作 | KaiwuDB 快速体验神器：开源工具 kwcli v0.1.1 功能全解析

kwcil 是 KaiwuDB 开源生态系统的 CLI 工具，可实现对 KWDB 组件（如 Playground 和单节点 KWDB）的一键安装、部署和生命周期管理。已于 5 月 3 日首发，指路👉kwcli：开源一个 KaiwuDB 社区版的 CLI 工具

这次 kwcli v0.1.1 更新，主要升级了三块内容：go 语言依赖升级版本；完善 SampleDB，新增了跨模查询场景、窗口函数示例；把 kwdb-tsbs 基准测试套件整个集成进了命令行，让性能压测也能一条命令启动。这篇文章，作者会从实测视角，带大家完整走一遍 kwcli v0.1.1 的新功能。

SampleDB 演示场景从 11 个扩充到 17 个，新增了一套完整的时序数据库基准测试工作流。

SampleDB 是 kwcli 里我个人最喜欢的一个组件。它不只是给你一张空表，而是直接搭好了一个智能电表的业务场景，从建库、造数到跑查询，一条龙服务。kwcli v0.1.1 在这个基础上，重点补了两块场景：跨模查询和窗口函数。

跨模查询是 KaiwuDB 的核心卖点，但之前的 SampleDB 里居然没有相关示例。kwcli v0.1.1 这次加了 4 个场景：

跨模查询的本质，就是在单条 SQL 里同时访问时序库（TSDB）和关系库（RDB）。KaiwuDB 的多模架构允许你在同一个实例里同时跑 CREATE TS DATABASE
 和 CREATE DATABASE
，然后直接写 JOIN。这在传统架构里，你可能需要 ETL 把时序数据抽到关系库，或者应用层做两次查询再拼装，复杂度完全不是一个量级。

贴一段 cross-mode-user-power
 场景背后的典型 SQL，感受一下：

SELECT
  mi.meter_id,
  u.user_name,
  a.area_name,
  COUNT(md.ts) AS reading_count,
  AVG(md.power) AS avg_power,
  SUM(md.energy) AS total_energy
FROM tsdb.meter_data md
JOIN rdb.meter_info mi ON md.meter_id = mi.meter_id
JOIN rdb.user_info u ON mi.user_id = u.user_id
JOIN rdb.area_info a ON mi.area_id = a.area_id
WHERE md.ts > NOW() - INTERVAL '1 day'
GROUP BY mi.meter_id, u.user_name, a.area_name, a.region
ORDER BY total_energy DESC
LIMIT 20;

窗口函数是时序分析的利器。v0.1.1 在原有 5 个场景的基础上，新增了 2 个，总计达到 7 个：

这里 KaiwuDB 支持的窗口函数类型非常丰富，不只是传统的时间窗口（time_bucket），还有会话窗口（session_window）、状态窗口（state_window）、事件窗口（event_window）、计数窗口（count_window）。对于设备告警、异常检测这类场景，状态窗口和事件窗口特别实用，能帮你把“连续异常"和“离散跳变"这两种模式都捕捉到。

场景多了，查找就成了问题。kwcli v0.1.1 给 sampledb list
 加了 --category
 参数，这是一个很贴心的体验优化：

# 查看所有基础查询场景
kwcli sampledb list --category basic

# 查看所有跨模查询场景
kwcli sampledb list --category cross-mode

# 查看所有窗口函数场景
kwcli sampledb list --category window

17 个场景现在被规整为三大类：

运行场景“窗口函数示例”。

[shawnyan@rl9 ~]# kwcli sampledb run count-window-example
=== 计数窗口函数示例 ===
-- 使用计数窗口进行滑动统计，每50条数据计算一次统计指标

  Executing: SELECT
Emulate Docker CLI using podman. Create etc/containers/nodocker to quiet msg.
meter_id        window_start    window_end      sample_count    avg_voltage     avg_current     avg_power
M1      2026-02-27 18:58:44.665+00:00   2026-04-02 19:38:44.665+00:00   50      220     5.5     1000
M1      2026-03-17 03:38:44.665+00:00   2026-04-20 04:18:44.665+00:00   50      220     5.49    1000
M1      2026-04-03 12:18:44.665+00:00   2026-05-07 12:58:44.665+00:00   50      220     5.51    1000
M1      2026-04-20 20:58:44.665+00:00   2026-05-07 12:58:44.665+00:00   25      220     5.52    1000
[shawnyan@rl9 ~]#

笔者实测，在一台已经装好 KaiwuDB 的测试机上，从 sampledb init
 到跑完所有 17 个场景，全程不到 10 分钟。对于做 Demo 或者快速验证 KaiwuDB 能力的场景，这个效率非常可以 。

如果说 SampleDB 解决的是“快速体验”的问题，那这次新增的 TSBS 组件解决的就是“性能验证"的问题。

TSBS（Time-Series Benchmark Suite）原本是 TimescaleDB 推出的时序数据库基准测试框架，后来被各大时序数据库厂商广泛采用。kwdb-tsbs 是 KaiwuDB 团队基于 TSBS 改编的专用版本，针对 KaiwuDB 社区版 的 SQL 方言和协议做了适配。

kwcli v0.1.1 把 kwdb-tsbs 整个打包进来了，而且安装包已经内置了 TSBS 二进制，不需要额外安装。提供五个子命令：

TSBS 内置了三种使用案例（Use Case），覆盖了最常见的时序场景：

• cpu-only：模拟服务器 CPU 监控场景，包含 16 种查询类型：

• devops：运维监控综合场景，同样包含 16 种查询类型，覆盖主机、指标、时间窗口的多维度组合。

• iot：物联网传感器场景，包含 13 种查询类型，更贴近车联网、设备追踪等业务：

下面是一段从数据生成到查询测试的完整流程，可以直接复制粘贴运行：

# 1. 初始化基准测试
#    use-case=cpu-only：CPU 监控场景
#    scale=10：10 个设备
#    queries=1000：生成 1000 条查询语句
kwcli tsbs init --use-case=cpu-only --scale=10 --queries=1000

# 2. 查看可用查询类型（可选，了解这次生成了哪些查询）
kwcli tsbs list

# 3. 加载数据到 KWDB
#    默认连接参数：host=127.0.0.1, port=26257, user=root, password=root
kwcli tsbs load --file=/tmp/tsbs_data --host=127.0.0.1 --port=26257 --user=root --password=root

# 4. 运行查询基准测试
kwcli tsbs run --file=/tmp/tsbs_queries --host=127.0.0.1 --port=26257

# 5. 清理测试文件及数据库（可选）
kwcli tsbs clean --drop-db

输出结果：

[shawnyan@DESKTOP-SHAWN kwcli]$ kwcli tsbs init --use-case=cpu-only --scale=10 --queries=1000
=== Step 1/2: Generating benchmark data ===
Executing: home/shawnyan/.kwcli/bin/tsbs_generate_data --use-case cpu-only --format kwdb --scale 10 --timestamp-start 2024-01-01T00:00:00Z --timestamp-end 2024-01-02T00:00:00Z --log-interval 10s --file tmp/tsbs_data

✓ Data generation completed!
  Data file: tmp/tsbs_data

=== Step 2/2: Generating query files ===
Executing: home/shawnyan/.kwcli/bin/tsbs_generate_queries --use-case cpu-only --format kwdb --scale 10 --timestamp-start 2024-01-01T00:00:00Z --timestamp-end 2024-01-02T00:00:00Z --queries 1000 --query-type double-groupby-5 --file tmp/tsbs_queries
KWDB mean of 5 metrics, all hosts, random 12h0m0s by 1h: 1000 points

✓ Query generation completed!
  Query file: tmp/tsbs_queries
  Meta file:  /tmp/tsbs_queries.meta

=== Initialization Complete ===
Use Case:     cpu-only
Scale:        10 devices
Time Range:   2024-01-01T00:00:00Z to 2024-01-02T00:00:00Z
Queries:      1000

Next steps:
  1. Load data:      kwcli tsbs load --file=/tmp/tsbs_data
  2. Run queries:   kwcli tsbs run --file=/tmp/tsbs_queries
[shawnyan@DESKTOP-SHAWN kwcli]$ kwcli tsbs list
Available TSBS Query Types:
------------------------------------------------------------
  cpu-max-all                    Maximum CPU usage across all devices
  cpu-max-by-host                Maximum CPU usage per host
  double-groupby                 Group by two fields
  groupby-time                   Group by time interval
  high-cpu-all                   Find all high CPU readings
  high-cpu-by-host               Find high CPU per host
  lastpoint                      Get last reading per device
  multi-measure-query-all        Query multiple measures
  multi-measure-where            Query with WHERE clause
  single-groupby-agg             Single group with aggregation
  single-groupby-agg-five        Five groupings with aggregation
  single-groupby-agg-max         Max aggregation per group
  single-groupby-agg-min         Min aggregation per group
  single-groupby-raw             Raw data per group
  time-range                     Query time range
  time-series-all                All time series data

Examples:
  kwcli tsbs generate-queries --use-case=cpu --query-type=double-groupby
  kwcli tsbs generate-queries --use-case=iot --query-type=threshold
[shawnyan@DESKTOP-SHAWN kwcli]$ kwcli tsbs load --file=/tmp/tsbs_data --host=127.0.0.1 --port=26257 --user=root --password=root
Executing: home/shawnyan/.kwcli/bin/tsbs_load_kwdb --host 127.0.0.1 --port 26257 --user root --pass root --db-name benchmark --file tmp/tsbs_data --batch-size 10000 --workers 4 --partition false --insert-type insert
time,per. metric/s,metric total,overall metric/s,per. row/s,row total,overall row/s

Summary:
loaded 950400 metrics in 0.163sec with 4 workers (mean rate 5821293.53 metrics/sec)
loaded 86400 rows in 0.163sec with 4 workers (mean rate 529208.50 rows/sec)

Data loading completed!
[shawnyan@DESKTOP-SHAWN kwcli]$ kwcli tsbs run --file=/tmp/tsbs_queries --host=127.0.0.1 --port=26257
Auto-detected query type: double-groupby-5
Executing: home/shawnyan/.kwcli/bin/tsbs_run_queries_kwdb --host 127.0.0.1 --port 26257 --user root --pass root --db-name benchmark --file tmp/tsbs_queries --query-type double-groupby-5 --workers 4
SELECT time_bucket(k_timestamp, '3600s') as k_timestamp, hostname, avg(usage_user), avg(usage_system), avg(usage_idle), avg(usage_nice), avg(usage_iowait) FROM benchmark.cpu WHERE k_timestamp >= '2024-01-01 04:37:47.862' AND k_timestamp < '2024-01-01 16:37:47.862' GROUP BY hostname, time_bucket(k_timestamp, '3600s') ORDER BY hostname, time_bucket(k_timestamp, '3600s')
...
After 1000 queries with 4 workers:
Interval query rate: 461.73 queries/sec Overall query rate: 420.81 queries/sec
KWDB mean of 5 metrics, all hosts, random 12h0m0s by 1h:
min:     5.18ms, med:     9.01ms, mean:     9.43ms, max:   44.25ms, stddev:     2.78ms, sum:   9.4sec, count: 1000
all queries                                            :
min:     5.18ms, med:     9.01ms, mean:     9.43ms, max:   44.25ms, stddev:     2.78ms, sum:   9.4sec, count: 1000

Run complete after 1000 queries with 4 workers (Overall query rate 420.20 queries/sec):
KWDB mean of 5 metrics, all hosts, random 12h0m0s by 1h:
min:     5.18ms, med:     9.01ms, mean:     9.43ms, max:   44.25ms, stddev:     2.78ms, sum:   9.4sec, count: 1000
all queries                                            :
min:     5.18ms, med:     9.01ms, mean:     9.43ms, max:   44.25ms, stddev:     2.78ms, sum:   9.4sec, count: 1000
wall clock time: 2.385152sec

Query benchmark completed!
[shawnyan@DESKTOP-SHAWN kwcli]$ kwcli tsbs clean --drop-db
Deleted: tmp/tsbs_data
Deleted: tmp/tsbs_queries
Dropping database 'benchmark' on 127.0.0.1:26257...
Database 'benchmark' dropped.
TSBS clean completed.
[shawnyan@DESKTOP-SHAWN kwcli]$

注意几个细节：

# 默认不启用分区（单节点环境安全）
kwcli tsbs load --file=/tmp/tsbs_data

# 可手动开启
kwcli tsbs load --file=/tmp/tsbs_data --partition

笔者建议，生产环境压测时把 scale 拉到更大（比如 1000 甚至 10000），同时调整 --workers
 参数来控制并发度。硬件方面，压测节点建议至少 16 核 CPU、32GB 内存、SSD 存储，这样才能把 KaiwuDB 的吞吐能力压出来，而不是让测试机本身成为瓶颈。

本次更新 kwcli 还增加了命令补全功能。敲 kwcli sa<TAB>
 就能自动补全出 sampledb
，再敲 kwcli sampledb i<TAB>
 就能补全出 init
。对于子命令和参数比较多的 CLI 来说，这个体验提升是实实在在的。

kwcli 比较容易上手，help 信息也尽量补全了，希望后面有时间继续更新维护。欢迎大家转发、留言反馈。

本文作者