遇到 unknown query [xxx]（部分版本报 No query registered for [xxx]）时，先别回头翻字段的 mapping。这条报错发生在查询解析阶段，意思是解析器读到了一个“查询类型”名字，但在当前节点已注册的查询类型里没找到实现。真正要盯着看的是方括号里的那个名字，而不是报错堆栈。
判断方向：先看方括号里是查询类型名还是字段名。是类型名，通常是拼写错误、该查询类型在当前集群版本不存在，或依赖插件；是字段名，多半是 JSON 嵌套层级放错，把字段名和 match 写反了。处理顺序建议为：留存原始请求 → 用 _validate/query 复现 → 逐层删减定位 → 对照集群版本替换写法。改动前备份 DSL，验证不通过时回退原请求，不要靠删掉 query 来绕过。
先确认当前场景和目标
这个报错在任何调用方式下都可能出现：curl 直接发 DSL、Kibana Dev Tools 里手写、应用通过客户端库拼装，或者由某个搜索中间层生成 JSON。先分清是哪一种，后面的排查路径差别很大。手工调用就报错，问题在 DSL 本身；只有应用报错、手工发同一份 DSL 却正常，问题更可能在客户端序列化或参数拼接。
动手前先补齐四项信息：集群版本（GET / 看 version.number）、报错完整原文（把方括号里的内容原样抄下来）、触发报错的完整请求 JSON，以及这条请求发往哪个索引。判断条件很简单——方括号里出现的是 match、bool、wildcard 这类查询类型词，还是你自己的业务字段名。括号里是字段名，说明结构写反了；括号里是类型词，说明该类型未被识别。
按这个顺序处理
第一步，用 _validate/query 在测试索引上把报错复现出来，不要直接在业务查询里改。这个接口只校验不执行，用来定位最省事：
GET /your_index/_validate/query?explain=true
{
"query": {
"match": { "title": "退款" }
}
}把原始 DSL 整段贴进 query 里执行，确认能稳定复现 unknown query，再开始改。如果复现不了，说明你贴的 DSL 与真实发出的请求不是同一份，先去应用日志或客户端抓真实请求体。
第二步，检查 JSON 层级。最常见的一类是把字段名和查询类型写反：
{ "query": { "title": { "match": "退款" } } }上面这种会报 unknown query [title]，正确写法是把查询类型放在外层、字段名放在内层：
{ "query": { "match": { "title": "退款" } } }同类问题还有几种：把 match 挂在 bool 的同一层，而不是放进 must/filter 的数组里；在 query 下面多套了一层自定义命名的对象；模板渲染时留了空对象，导致某个子句变成 {"": {...}}。从内往外逐层收括号，一般能比较快看出错位位置。
第三步，对照集群版本确认查询类型是否真的存在。不同大版本支持的查询类型集合不同，旧写法在新集群可能已被移除，新写法在旧集群也可能还没有提供。如果报错出现在升级、换集群或换客户端之后，优先怀疑这一类，改用等价写法，例如早期版本的过滤类写法通常可以用 bool 的 must/filter 组合表达。
第四步，嵌套很深时用二分法删减：先只保留最外层 bool，校验通过后逐块加回 must、should、nested 和 aggs 里的子句，哪一块加回去就报错，问题就在那一块。比反复通读整段 DSL 快得多。
第五步，确认只有应用侧报错时，检查客户端库的版本和拼装逻辑。有些客户端会把方法名映射成查询类型字符串，方法用错或版本不匹配都会生成集群不认识的名字。打开客户端的请求日志，把实际发出的 JSON 打出来，与手工校验通过的那一份逐字比对。
改完后怎么验证
先用同一个请求再跑一次 _validate/query?explain=true，预期返回 "valid": true，explanations 里能看到查询被正常重写，而不是报错信息。这一步只证明语法能解析，不证明语义正确。
然后真正执行一次查询，验证三件事：一是 hits.total 落在你预期的量级内，明显偏大要先怀疑条件被吞掉（比如误退化成匹配全部文档），明显偏小要怀疑字段类型不对；二是抽几条 hits.hits 看返回内容是否确实命中目标文档；三是如果带排序或聚合，检查 aggregations 结构是否完整。改前改后各跑一次，重点看命中条数的变化是否符合预期，而不是只看有没有报错。
最后回到应用侧，用同一批参数真实调用一次，确认日志里该报错不再出现，同时确认响应结构与前端消费的字段一致。有条件的话把这条 DSL 留成用例，后续升级版本时直接拿来做回归。
容易忽略的边界
查询类型解析和权限是两件事，不要混在一起验证。开启安全插件后，字段级权限通常表现为“查得到但匹配不到”，并不会报 unknown query；所以查询成功不代表权限和字段可见性没有问题。
版本以外的差异也要看：依赖插件的自定义查询类型只在装了该插件的节点上可用；客户端库版本高于集群版本时，可能生成当前集群尚不支持的查询类型，这类问题改 DSL 没用，需要对齐客户端版本。另外换写法时要注意字段类型，term 打在 text 字段上不会报错，但通常匹配不到预期结果，分词字段要改用 match 或指向 keyword 子字段。
还有一种看着省事的做法要避免：为了让报错消失，把整段 query 删掉或换成空对象，请求会退化成匹配全部文档，在数据量大的索引上代价很高。回退建议是，改动前把原始 DSL 和对应的客户端代码一起留档，新写法先在测试索引或校验接口上过一遍再替换线上请求；验证不通过就回退到原请求，不要继续在报错版本上叠加修改。