oushudb_explain — OushuDB EXPLAIN 执行计划可视化
概述
专为 OushuDB（原 Apache HAWQ）设计的 EXPLAIN 文本解析与可视化工具。解析 OushuDB 的 EXPLAIN 输出，生成自包含的交互式 HTML 可视化页面。完整支持 OushuDB 特有统计（段级 Rows out/in、Slice statistics、Dispatcher statistics、Data locality statistics、LM info 等）。
何时使用
当用户提出以下请求时加载此 skill：
- "分析这个 OushuDB EXPLAIN 计划"
- "把 EXPLAIN 输出做成可视化页面"
- "帮我看看这个查询为什么慢"
- "把这个执行计划渲染成 HTML"
- 用户贴出一段 OushuDB 的
EXPLAIN输出文本，要求分析或可视化 - 用户需要对比两个 EXPLAIN 计划的性能差异
- 涉及 OushuDB / HAWQ 的查询性能调优
技能内容
scripts/ — 核心脚本
位于 scripts/ 目录下，所有脚本以 scripts/ 为前缀引用：
| 文件 | 作用 |
|---|---|
scripts/main.py |
入口桥接，导入 app 模块的 main() 和 generate_html() |
scripts/app.py |
HTML 渲染引擎（526 行）— 解析 → 渲染 → 输出一站式 |
scripts/explain_parser.py |
EXPLAIN 文本解析器（361 行）— 两遍扫描，返回 PlanNode 树 |
scripts/start.sh |
快捷生成脚本：./start.sh [input.explain] [-o output.html] |
scripts/stop.sh |
帮助说明脚本（静态 HTML 无需停止服务） |
assets/ — 示例数据
| 文件 | 说明 |
|---|---|
assets/example.explain |
通用示例（OushuDB，64 节点，48.6s） |
assets/q01.explain |
A/B 对比组 A（24 节点，19.6s） |
assets/q02.explain |
A/B 对比组 B（24 节点，7.3s，与 q01 同结构不同性能） |
assets/q03.explain |
A/B 对比组 A（24 节点，33.9s，单表 GroupAggregate） |
assets/q33.explain |
A/B 对比组 B（24 节点，16.7s，与 q03 同查询不同性能） |
references/ — 参考文档
| 文件 | 说明 |
|---|---|
references/README.md |
项目完整文档（中文） |
使用方式
1. 从 EXPLAIN 文本生成 HTML
用户提供 EXPLAIN 输出文本时：
- 将 EXPLAIN 文本保存为
.explain文件（例如query.explain），放在当前工作目录或合适位置 - 使用 app.py 生成 HTML：
# 使用 Python 3.9+ 运行
python3 scripts/app.py query.explain -o query.html
或使用快捷脚本：
bash scripts/start.sh query.explain -o query.html
- 使用
present_files工具将生成的 HTML 文件呈现给用户
2. 使用示例数据生成
python3 scripts/app.py assets/example.explain -o outputs/example.html
3. 自定义输出路径
python3 scripts/app.py input.explain -o /path/to/output.html
功能视图说明
生成的 HTML 页面包含 5 个标签页：
| 视图 | 说明 |
|---|---|
| Plan | 树形流程图，点击节点展开详细属性（cost、rows、actual time、OushuDB 段统计等） |
| Grid | 表格展示所有节点，含 MaxSegTime / LastSegTime / MaxSegRows / LastSegRows 等段级指标 |
| Stats | 按节点类型和表名聚合统计，含可视化进度条 |
| Query | 查询基本信息展示 |
| Raw | 原始 EXPLAIN 文本 |
OushuDB 特有支持
- 解析
Rows out: Avg N rows x M workers. Max/Last(segX:host/segY:host)分布式段统计 - 解析
LM info、Predicate Info、MergeRead Info、Decompress Info、Cache Read等 OushuDB ORC 扫描层面板 - 识别
Orc Table Scan、Broadcast Motion、Redistribute Motion、Gather Motion等 OushuDB 特有节点 - 解析
Data locality statistics（本地性比率）、Dispatcher statistics（代理连接时延）、Slice statistics等分布式统计 - Grid 视图提供段级分布式性能指标，便于定位热点段和数据倾斜
依赖
- Python 3.9+（使用标准库，无需额外 pip 包）
- 渲染后的 HTML 页面无需任何服务端，直接在浏览器中打开
