kwdb-performance-review Skill：四步闭环搞定数据库慢 SQL

数据库慢查询排查，向来是一项高度依赖工程师实战经验的工作。拿到一条 SQL 与对应的执行计划后，排查链路往往环环相扣：先要判断表的存储类型，再逐一校验过滤条件有效性、索引命中情况、数据扫描范围、分页实现逻辑，以及分布式节点间的数据交换开销，环节多、细节杂，稍有疏漏就可能定位偏差，甚至给出错误的优化方向。

时序数据库场景更是存在天然的认知壁垒：关系型数据库中被反复验证的索引优化思路，直接套用到时序表上常常完全失效，反而可能成为性能负担。这也是很多有传统数据库经验的工程师，切入时序场景时最容易踩的坑。

针对这一痛点，我们将 KaiwuDB/KWDB 体系下成熟的慢查询排查方法论，沉淀为了一套可复用的 Agent Skill：kwdb-performance-review。它面向 KaiwuDB/KWDB 的时序与关系型双模型查询场景，完整覆盖 EXPLAIN 执行计划解读、时序查询专项优化、深分页性能治理、跨模型联合查询调优，以及按需适配的存储参数配置建议。

解决什么问题

这个 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，并说明验证时应关注哪些执行计划节点。

结语

kwdb-performance-review 的核心价值，在于为 Agent 建立了标准化的判断链路：它要求 Agent 遵循「引擎确认→执行计划溯源取证→新执行计划改写验证」的固定分析流程，确保性能排查逻辑严谨有序。团队可持续在参考资料库中补充经校验的查询优化模式，无需将全部规则重复写入每一次提示词。

这套 Skill 的能力边界同样清晰：它无法替代生产环境的全量压测，也不会在资源信息缺失的前提下贸然调整集群参数。只有将真实 SQL、表结构摘要、数据规模与执行计划作为完整输入，Agent 才能输出可核验、可复现的性能优化建议。