KaiwuDB Agent Skills 使用指南：用 performance-review Skill 解读执行计划

开务数据库

436人浏览 · 2026-07-17 12:18:22

开务数据库 · 2026-07-17 12:18:22 发布

本文基于 KWDB 3.2.1 版本及 kwdb-performance-review Skill 实践编写。KWDB 是 KaiwuDB 的开源社区版，面向开发者免费开放，支持分布式部署、时序存储引擎和标准 SQL。如果你想体验 KWDB 的时序查询、跨模分析或 Agent Skill 工作流，可访问 KaiwuDB 官网获取完整文档、安装包和社区支持。

在KaiwuDB 社区版的使用过程中，慢 SQL 分析往往不只是“改一条 SQL”这么简单。尤其在 AIoT、工业物联网和时序数据场景下，查询性能与表类型、时间范围、主标签过滤、执行计划节点、跨模型 JOIN 方式都有关系。
为了让开发者更系统地完成 KWDB 慢 SQL 排查与性能优化，我们将执行计划解读、时序查询调优、深分页改写、跨模型查询优化等经验沉淀为 kwdb-performance-review Agent Skill。它通过“引擎识别、执行计划分析、反模式定位、改写验证”四步流程，帮助 Agent 输出可解释、可验证的 KWDB SQL 优化建议。

解决什么问题

这个 Skill 适合处理以下请求：

“帮我优化这条 KaiwuDB/KWDB 查询”；
“这条 SQL 为什么走全表扫描”；
“如何解读这份 EXPLAIN”；
“时序数据分页越来越慢”；
“关系表与时序表 JOIN 性能差”；
“查询已经优化过，是否需要调整存储参数”。

它不会接管所有数据库工作，建表、模式设计、部署、数据迁移和写入性能优化不在其职责内。Skill 还会要求 Agent 在推荐索引前确认表类型，避免把关系型数据库的经验套用到不支持二级索引的时序表上。

第一步永远是识别执行引擎

KaiwuDB/KWDB 的时序表与关系表使用不同的优化规则。kwdb-performance-review 把引擎识别放在工作流开头，信息不足时会先询问用户，而不是直接给出索引或 SQL 改写建议。

维度	时序表	关系表
数据组织	列式存储与时间分区	行式存储
索引能力	主标签自动使用哈希索引，不支持手工二级索引	支持 B-tree、倒排和复合索引
关键过滤条件	时间范围与主标签精确匹配	与索引匹配的过滤和连接条件
常见风险\|跨分区扫描、标签模糊匹配、深 OFFSET	大表顺序扫描、连接顺序不佳、缺少索引

这种分流很重要。比如看到时序表查询慢时，Skill 不会建议执行 CREATE INDEX，而是先检查时间范围能否触发分区裁剪，以及主标签是否使用等值条件命中哈希索引。

闭环式性能审查流程

Skill 的主流程只有四步：解析执行计划、识别反模式、提供改写 SQL、验证改写结果。配置调优是条件分支，只有用户明确提出参数调优，或 SQL 层面的检查已经完成但问题仍存在时才会进入。

标准输出也围绕这个闭环组织，包括优化意图、引擎类型、发现的反模式、原始 SQL、改写后的 SQL、预期执行计划变化和验证语句。这样的结构能减少"只贴一条新 SQL，却不解释为什么"的回答。

时序查询的五条核心规则

1. 给出明确的时间范围

时序查询需要时间过滤来触发分区裁剪。执行计划中出现 Partition Filter，说明引擎只扫描目标时间范围。缺少时间条件时，即使主标签过滤有效，查询仍可能跨越大量分区。

SELECT ts, temperature
FROM device_sensor
WHERE device_id = 'D001'
  AND ts >= '2026-04-01'
  AND ts < '2026-04-02';

2. 主标签使用精确匹配

时序表的主标签使用哈希索引。device_id = 'D001' 可以命中索引，LIKE '%001%' 或在标签列上包裹 SUBSTRING 等函数会破坏这一访问路径。执行计划里的 Tag Filter 是检查重点。

3. 明确列名，避免 `SELECT *`

时序表采用列式存储。只读取时间戳、温度等实际需要的列，可以减少不必要的列 IO。Skill 将 SELECT * 视为需要优先检查的反模式。

4. 用游标替代深 OFFSET

LIMIT 20 OFFSET 10000 仍需读取并丢弃前面的记录。Skill 推荐使用上一页最后一条记录的时间戳作为游标：

SELECT ts, temperature
FROM sensor_data
WHERE device_id = 'D001'
  AND ts > '2026-04-01 12:30:00'
ORDER BY ts
LIMIT 20;

5. 使用 `TIME_BUCKET` 做时间聚合

按小时或按天聚合时，Skill 推荐使用 KaiwuDB/KWDB 的 TIME_BUCKET，而不是用通用日期函数手工截断时间。

跨模型查询：先缩小关系数据，再访问时序数据

KaiwuDB/KWDB 支持关系数据与时序数据组合查询。Skill 对这类 SQL 的建议很明确：让较小、过滤选择性更高的关系表参与驱动，并给时序表补充时间范围，避免先扫描大规模时序数据。

SELECT s.ts, s.temp, d.name
FROM devices d
JOIN sensor_data s ON d.id = s.device_id
WHERE d.group_id = 'G001'
  AND s.ts >= '2026-04-01';

验证时需要关注 JOIN 类型、时序侧的 Partition Filter，以及执行计划是否出现代价较高的 Shuffle。

配置调优的安全边界

配置参数会影响内存、CPU、磁盘占用和后台任务。Skill 因此采用"按参数触发"的方式，而不是扫描并修改整套集群设置。

在建议缓存、压缩、内存段或 compaction 参数前，Agent 需要确认对应资源余量。查询配置时只读取目标参数，例如：

SHOW CLUSTER SETTING ts.block.lru_cache.max_limit;

Skill 明确禁止自动执行 SET CLUSTER SETTING。Agent 只能给出待审核的 SQL，并解释收益、风险和验证方式。它也禁止使用一次性读取全部配置的 SHOW CLUSTER SETTINGS。

安装与使用

推荐使用 skills.sh 安装：

npx skills add https://github.com/KWDB/KaiwuDB-Agent-Skills \
  --skill kwdb-performance-review

安装后，可以把 SQL、表类型和 EXPLAIN 输出一起交给 Agent。信息越完整，Agent 越容易区分正常扫描与真正的性能问题。

请使用 kwdb-performance-review 分析下面的 KaiwuDB 查询。

表类型：TIME SERIES
问题：翻到 500 页后响应明显变慢
SQL：...
EXPLAIN (ANALYZE)：...

请指出反模式、给出改写 SQL，并说明验证时应关注哪些执行计划节点。

本文FAQ

Q1：KWDB 慢 SQL 优化应该先看什么？

先确认表类型和执行计划。时序表重点看时间范围、主标签过滤、分区裁剪和列读取范围；关系表重点看索引命中、连接顺序和扫描方式。

Q2：kwdb-performance-review Skill 适合哪些场景？

适合分析 KWDB 查询性能、解读 EXPLAIN 执行计划、识别时序查询反模式、改写深分页 SQL，以及审查关系表与时序表的跨模型 JOIN。

Q3：KWDB 时序表为什么不建议直接套用关系型索引优化思路？

KWDB 时序表的数据组织、标签过滤和分区裁剪机制与传统关系表不同。时序表更依赖时间范围、主标签等值过滤和列式读取优化，不应直接把关系表的二级索引经验照搬过来。

Q4：KWDB 深分页查询如何优化？

对于 LIMIT … OFFSET … 这类深分页查询，可改成基于上一页最后一条记录的游标分页，减少无效扫描和丢弃数据的成本。

Q5：使用 Agent Skill 分析 KWDB SQL 时需要提供哪些信息？

需要议提供 SQL、表类型、表结构摘要、数据规模、过滤条件、EXPLAIN 或 EXPLAIN ANALYZE 输出。信息越完整，Agent 给出的优化建议越容易验证。

结语

kwdb-performance-review 的价值，不在于替代 DBA 或开发者做最终判断，而是把 KWDB 慢 SQL 分析中容易遗漏的步骤固化下来：先识别表类型，再阅读执行计划，再定位查询反模式，最后用改写 SQL 和新执行计划验证优化效果。
对于正在尝试把 AI Agent 接入数据库工作流的团队来说，这类 Skill 可以把一次性的经验提示沉淀为可复用的工程流程，让 KWDB 查询优化、时序分析和跨模型查询审查更容易标准化。

你最希望 Agent Skill 帮你沉淀哪类数据库工作流：执行计划分析、时序查询优化、跨模型 JOIN 调优，还是 SQL 生成与验证？欢迎在评论区分享你的使用场景，也可以告诉我们希望 KWDB Agent Skills 后续补充哪些能力。