本文基于 KWDB 3.2.0 版本及 SampleDB 项目实践编写。KWDB 是 KaiwuDB 的开源社区版面向开发者免费开放支持分布式部署、时序存储引擎和标准 SQL。如果你在部署或使用中遇到问题或者想下载最新版本可访问 KaiwuDB 官网获取完整文档和社区支持。文章目录01 SampleDB 现在覆盖了什么02 最新变化快速体验变成了 Agent Skill03 为什么这对数据库示例很重要04 同批更新聚合函数示例补齐时序统计入口05 持续迭代SampleDB 的路线更清楚本文FAQQ1运行 KaiwuDB SampleDB 前需要准备什么Q2KaiwuDB 四类 SampleDB 示例应该如何选择Q3可以直接复用正在运行的 KWDB 实例吗结语相关推荐本文主要面向社区版开发者和 AIoT 应用人员解决 SampleDB 示例运行过程中环境检查、数据库准备、示例选择、数据导入和 SQL 验证步骤不清晰的问题。文章以 sampledb-quickstart Agent Skill 为入口介绍如何在本机或 Docker 环境中逐步运行智能电表、跨模查询、窗口函数和聚合函数 4 类示例。完成体验后读者可以理解 KWDB 时序建模、关系与时序数据联合分析、窗口划分及统计聚合等能力并了解每一步涉及的数据库和临时文件。01 SampleDB 现在覆盖了什么SampleDB 是 KWDB 的示例数据与场景展示项目目标是帮助开发者快速掌握 KWDB 数据库的使用方法并提供便捷的测试与学习环境。当前项目围绕 AIoT 和时序分析场景组织了四组可运行示例这些示例不是孤立 SQL 片段。每个目录都配套了数据生成、建库建表、数据导入和查询脚本如果已经通过容器部署 KWDB也可以直接使用容器模式体验。官网也把这条路径概括得很直接可以运行智能电表、跨模查询、窗口函数和聚合函数示例验证 KWDB 在 AIoT 场景下的建模与查询能力。02 最新变化快速体验变成了 Agent Skill这次最值得关注的更新是仓库新增了sampledb-quickstart Skill。只需简单的提示词帮助我根据当前环境快速体验 SampleDB 示例并解释每一步做了什么。也可以更短运行本示例项目。背后的流程并不只是把命令交给 Agent 执行。sampledb-quickstart的设计重点是“带着用户跑”而不是静默跑完整个 demo。它会先检查当前项目环境和 KWDB 运行状态再根据用户当前是容器部署还是本机部署来准备 KWDB之后让用户选择要体验的示例并在每一步开始前说明会做什么。这种交互式设计把几个容易踩坑的点前置了• 它会先确认是否已有 KWDB 在运行避免直接复用一个可能承载其他数据的实例。• 它不会默认跳到某个示例而是让用户在smart-meter、multi-mode、window、aggregate之间选择。• 到查询阶段它不只提供“运行完整query.sh”也允许用户只跑一个查询示例适合边看 SQL 边理解结果。• 用户输入stop时Skill 会清理本次快速体验创建的kwbase-data临时目录。这正是 Agent Skill 比传统脚本更适合示例项目的地方脚本擅长自动化重复动作Skill 则更擅长把“检查、解释、确认、执行、总结”串成一个学习流程。对于第一次接触 KWDB 的开发者来说这能减少很多“我现在该不该运行这条命令”的判断成本。03 为什么这对数据库示例很重要数据库示例天然带有副作用。建库建表、导入数据、删除并重建演示库、占用端口、写入本地数据目录这些动作如果被一键脚本直接执行体验会很快但边界也容易模糊。sampledb-quickstart把这个边界写进了流程里。检测到已运行的 KWDB 时它会提示复用现有实例可能影响演示库在 Host 模式下它会关注nodelocal://1/...所需的数据目录在容器模式下它会把容器名、SQL 端口、容器内kwbase路径和导入目录纳入上下文。换句话说Skill 并没有把数据库操作包装成一个“黑盒按钮”而是让 Agent 在执行前解释上下文。示例仍然是那些脚本和 SQL但用户看到的是一条更接近教学实验的路径。这对 SampleDB 的定位也很关键。它不只是告诉你“KWDB 支持跨模查询、窗口函数和聚合函数”而是让你在自己的环境里一步步跑出结果并理解每一步在验证什么能力。04 同批更新聚合函数示例补齐时序统计入口除了 Agent SkillSampleDB 也新增了聚合函数示例。aggregate/目录覆盖基础统计聚合和时序专属聚合两类能力包含 10 种核心函数这组示例补上的是时序分析里最常见的一层把多行传感器或设备数据收敛成统计结果。比如设备监测里的最小值、最大值、平均值环境采集里的周期统计以及非均匀采样数据里的时间加权平均。aggregate/README.md里也明确了几个使用边界time_bucket()需要搭配GROUP BY使用TWA()需要指定时间戳列和数值列分组聚合时SELECT中的非聚合列需要出现在GROUP BY子句中。这些规则放在可运行示例里比单独阅读语法说明更容易建立直觉。05 持续迭代SampleDB 的路线更清楚之前已有多篇博客介绍 SampleDB 项目的内容和进展这次更新没有改变这个方向而是继续补齐体验链路• 示例层面新增聚合函数把基础统计和时序专属统计纳入 SampleDB。• 入口层面新增sampledb-quickstartSkill让 AI Agent 能按环境引导用户跑示例。• 展示层面新建项目官网https://kwdb.tech/sampledb ) 把智能电表、跨模查询、窗口函数、聚合函数和快速开始入口集中到一个页面。对开发者来说最直接的体验路径可以是先让 Agent 通过sampledb-quickstart检查环境再从智能电表或跨模查询开始建立整体印象之后按兴趣切到窗口函数或聚合函数观察 KWDB 在时序事件边界和统计聚合上的具体表现。SampleDB 的价值正在从“给你一组脚本”升级为“陪你跑完一组实验”。这正是 Agent Skill 带来的变化让示例项目不只可运行而且更容易被理解。本文FAQQ1运行 KaiwuDB SampleDB 前需要准备什么需要获取 SampleDB 仓库并准备可用的 KWDB、Bash 环境和示例脚本。可以使用已经启动的 Docker 容器也可以使用本机 kwbase但复用现有数据库前必须确认其中没有重要演示同名库。Q2KaiwuDB 四类 SampleDB 示例应该如何选择智能电表适合了解完整的关系与时序数据应用跨模示例聚焦关系表和时序表联合查询窗口函数适合分析连续事件、会话和状态变化聚合函数适合学习统计、时间分桶和时间加权平均。Q3可以直接复用正在运行的 KWDB 实例吗可以但必须先确认。部分脚本会删除并重建 rdb、tsdb、db_monitor、monitor_r、ts_window 或 sensors 等演示数据库不应直接对包含业务数据的实例执行。结语SampleDB 将 KWDB 的建模、数据导入和查询能力整理为可运行示例sampledb-quickstart 则进一步把环境检查、操作确认、结果解释和临时目录清理组织成引导式流程。开发者可以先从智能电表示例建立整体认识再根据需要体验跨模查询、窗口函数或聚合函数。你最想通过 SampleDB 体验哪类能力智能电表、跨模查询、窗口函数还是聚合分析欢迎在评论区分享你正在关注的 AIoT 应用场景也可以告诉我们希望 SampleDB 后续增加哪些可运行示例。相关推荐KaiwuDB 社区版部署实战单机/Docker/集群三种模式全流程指南KaiwuDB Agent Skills 使用指南数据库查询、部署与智能运维工作流KaiwuDB SampleDB 实战五大分组窗口函数完整实操教程一文读懂 KWDB 聚合函数结合 SampleDB 实例详细拆解KaiwuDB 3.2.2 发布时序数据处理、高可用与安全能力全面升级更新日期2026-07-23