摘要ClickHouse 的 EXPLAIN 输出格式多、层次深排查慢查询时往往要在终端、文档和 system.query_log 之间来回切换。本文介绍在线工具ClickHouse EXPLAIN 可视化 AI 调优助手支持离线粘贴执行计划、直连集群采集指标并结合 AI 给出优化建议。在线体验https://ch.charunion.com关键词ClickHouse、EXPLAIN、慢查询、SQL 优化、执行计划、query_log、AI 调优一、为什么 ClickHouse 的 EXPLAIN 这么难读做过 ClickHouse 性能优化的同学大概都经历过这样的场景EXPLAINPLANSELECTevent_type,count()AScnt,uniq(user_id)ASuvFROMdemo.eventsWHEREevent_datetoday()-7GROUPBYevent_typeORDERBYcntDESC;终端里吐出来的是一棵树Expression (Project names) Sorting (ORDER BY cnt DESC) Expression ((Before ORDER BY Projection)) Aggregating Expression (WHERE) ReadFromMergeTree (demo.events) → 68,432 rows, 0.12s看着还行但当 SQL 变复杂、节点变多、再叠加 EXPLAIN PIPELINE、EXPLAIN JSON 时问题就来了格式不统一文本树、JSON、Pipeline 描述解析难度差很多缺少运行时数据EXPLAIN 告诉你「打算怎么扫」但真实读了多少行、耗时多久还得去 system.query_log 里翻优化靠经验看到 Aggregating 知道要警惕但具体该改索引、分区还是上物化视图往往要查文档 问同事协作成本高把终端截图发给 DBA对方还要你补 DDL、表结构、业务 SLA我日常也在用 ClickHouse被这些问题折腾久了索性做了一个 Web 工具把执行计划可视化、指标采集、规则诊断、AI 对话串成一条链路。二、工具能做什么在线地址https://ch.charunion.com能力说明执行计划树把 EXPLAIN 文本/JSON 解析成可折叠的树形结构多 EXPLAIN 类型支持 PLAN、PIPELINE、QUERY TREE、AST、SYNTAX离线 / 连接双模式可粘贴已有结果也可直连 ClickHouse 自动执行运行时指标连接模式下关联 query_log展示真实扫描行数、耗时AI 调优助手结合 SQL、DDL、执行计划上下文对话式给优化建议主界面分为输入区和结果区结果区用 Tab 组织概览关键指标汇总扫描行数、耗时、分析深度等执行计划树形展示扫描节点可挂载运行时数据诊断基于规则的初步问题识别优化建议结构化优化项索引、分区、改写方向等AI 助手针对当前 SQL 上下文的多轮对话配图建议首页整体截图、执行计划树展开截图三、两种使用方式3.1 离线模式无需连接数据库适合生产环境不方便开外网连接已经有一份 EXPLAIN 结果想快速解读内网审计严格只能手动复制粘贴操作步骤选择「离线模式」粘贴 SQL选择 EXPLAIN 类型默认 PLAN粘贴 EXPLAIN 输出结果可选补充表 DDL提升 AI 分析质量点击「开始分析」工具内置了 demo.events 的示例数据第一次使用可以直接点「加载示例」体验。3.2 连接模式自动采集适合测试环境 / 开发集群需要真实 query_log 指标想一键跑 EXPLAIN不想手动复制操作步骤选择「连接模式」填写 ClickHouse 地址、端口、用户名、库名可选开启拉取 query_log关联最近一次执行的运行时指标执行 SQL只读在服务端执行 SELECT 并采集 live 指标需谨慎开启点击「开始分析」注意连接模式下凭证只用于本次分析请求请勿在生产只读账号未隔离的情况下随意开启「执行 SQL」。四、一个完整的分析示例以如下 SQL 为例SELECTevent_type,count()AScnt,uniq(user_id)ASuvFROMdemo.eventsWHEREevent_datetoday()-7GROUPBYevent_typeORDERBYcntDESC;对应表结构CREATETABLEdemo.events(event_dateDate,event_timeDateTime,user_id UInt64,event_type String,properties String)ENGINEMergeTree()PARTITIONBYtoYYYYMM(event_date)ORDERBY(event_date,event_time,user_id);4.1 从执行计划看什么树形结构里重点关注叶子扫描节点如 ReadFromMergeTree预估/实际扫描行数是否命中分区裁剪聚合、排序是否发生在扫描之后常见性能瓶颈中间节点如 Expression、Distinct 往往不直接产生 IO指标显示为—是正常现象。4.2 结合 query_log 看什么如果开启了 query_log 采集可以看到read_rows / read_bytesquery_duration_msmemory_usageEXPLAIN 是计划query_log 是结果。两者对照才能判断是「计划就不优」还是「数据分布变了导致计划失效」。4.3 AI 助手怎么用在 AI Tab 里可以直接问7 天窗口能否再缩小uniq 和 count 哪个更适合这个场景要不要按 event_date 做预聚合帮我改写一版更清晰的 SQLAI 会基于当前 SQL、DDL、执行计划摘要来回答比裸聊 GPT 更贴近 ClickHouse 语境。五、后端实现的几处关键点工具采用Next.js 14 FastAPI前后端分离架构后端通过 clickhouse-connect 访问 ClickHouseMySQL 存储用户与历史记录。5.1 EXPLAIN 解析文本 vs JSONClickHouse 不同版本的 EXPLAIN 输出差异很大实践中至少处理了三类情况。1缩进文本树最常见Aggregating Expression (WHERE) ReadFromMergeTree (demo.events)按缩进层级还原父子关系即可。2JSON 格式EXPLAIN JSON 返回嵌套对象需要递归 unwrap把 Plan、Expression、Description 等字段统一映射到内部树节点。3多棵候选树打分有些输出会解析出多个候选结构通过打分函数选最合理的一棵避免 JSON 被误解析成无意义的扁平结构。5.2 运行时指标 enrichment解析出计划树后对 ReadFromMergeTree 等扫描节点尝试从以下来源 enrichment连接模式 live 指标执行后即时采集query_log 匹配按 query_id / 时间窗口匹配最近一次执行记录这样树上不再只有「计划」而是「计划 实际」对照。5.3 分析深度系统会根据输入完整度标记 analysis_depth只有 EXPLAIN 文本 → preliminary初步分析有 DDL query_log → 更深入的综合诊断5.4 架构简图┌─────────────┐ HTTPS ┌─────────────┐ │ Next.js │ ─────────────► │ FastAPI │ │ Web 前端 │ │ 后端 API │ └─────────────┘ └──────┬──────┘ │ ┌─────────────────┼─────────────────┐ ▼ ▼ ▼ ClickHouse MySQL Cursor AI API (EXPLAIN/query_log) (用户/历史) (调优对话)六、部署与使用说明前端https://ch.charunion.com后端 APIhttps://ch-api.charunion.com/api/v1使用权限访客可直接使用分析功能离线/连接模式登录用户可使用历史记录、AI 助手等需持久化的功能本地 Docker 部署也支持核心编排为 docker-compose.prod.yml前端构建时需注入 NEXT_PUBLIC_API_URL 等环境变量。七、适用场景与局限适合ClickHouse SQL 日常 Review慢查询初步定位先看计划再看 log新人学习 EXPLAIN 的可视化教具和 DBA / 同事分享分析结果比终端截图清晰当前局限AI 建议需人工审核不能直接等同于生产变更方案复杂分布式场景下query_log 匹配偶有偏差连接模式依赖网络可达生产集群建议优先离线模式中间算子节点暂不支持完整运行时指标聚焦扫描节点八、写在最后ClickHouse 的性能优化从来不是看一眼 EXPLAIN 就能结束的。它是一套「看懂计划 → 对照运行时 → 结合表结构 → 验证改写」的流程。这个工具的目标就是把这条链路尽量压缩到一个页面里粘贴 SQL → 看到树 → 看到指标 → 得到建议 → 继续追问 AI如果你也在做 ClickHouse 查询优化欢迎试用https://ch.charunion.com有任何问题或功能建议欢迎在评论区交流。