NoSQL 与搜索 / 系统课时
使用 Analyze API
使用 Analyze API
当全文查询没有命中、短语顺序异常或高亮位置不正确时,最直接的排查方法是查看文本实际被分析成了什么。本课将通过 Analyze API 观察词元、位置和偏移量,并建立一套可复用的分析步骤。
学习目标
- 使用 Analyze API 测试内置分析器、字段分析器和临时分析器
- 解释
token、position、start_offset与end_offset - 根据索引端和查询端的词元差异定位匹配失败
Analyze API 能解决什么问题
Analyze API 只执行文本分析,不写入文档。它适合回答三个问题:原文最终产生了哪些词元、这些词元的顺序和位置是什么、每个词元对应原文的哪一段。
测试时应尽量使用真实索引和字段,因为字段可能配置了自定义 analyzer 或 search_analyzer。只有在验证某个独立分词规则时,才建议直接指定分析器名称或临时组合各组件。
查看完整词元信息
下面使用 standard 分析器处理一段英文文本,并要求返回详细属性。请求可在 Kibana Dev Tools 中执行。
POST /_analyze
{
"analyzer": "standard",
"text": "Search APIs are useful.",
"explain": true,
"attributes": [
"term",
"position",
"positionLength",
"startOffset",
"endOffset",
"type"
]
}预期结果中会出现 search、apis、are、useful 等词元。完整 JSON 的内部结构会因 Elasticsearch 版本和分析链配置有所差异,但核心词元及其先后顺序应一致。
position token start_offset end_offset
0 search 0 6
1 apis 7 11
2 are 12 15
3 useful 16 22token 是最终用于索引或查询的词项;position 表示词元在词元流中的逻辑位置;start_offset 和 end_offset 表示它在原始文本中的字符范围;type 则说明词元类别,例如单词、数字或其他分词器定义的类型。
使用索引字段的真实配置
直接指定 analyzer 只能验证某个分析器,不能保证与实际字段一致。若索引 articles 的 title 字段已经配置分析器,应通过 field 参数复用该字段的分析设置。
POST /articles/_analyze
{
"field": "title",
"text": "Elasticsearch 中文搜索"
}预期结果取决于 title 字段的实际映射。验证重点不是固定词元数量,而是确认响应中的词元与字段写入时使用的规则一致。
返回 title 字段分析器生成的词元列表;具体词元由该字段映射决定。当请求同时提供 field 和 analyzer 时,不应依赖含糊的优先级来排查问题。更稳妥的做法是一次只指定一种来源,避免误以为测试了字段配置,实际却使用了临时分析器。
用位置与偏移量判断异常
位置主要影响短语查询和词序判断。若同义词过滤器把多个词放在同一位置,可能出现两个词元共享同一个 position;若停用词被删除,后续词元的位置可能出现间隔。短语查询是否命中,不只看词元内容,还与位置增量和允许的 slop 有关。
偏移量主要服务于高亮和原文定位。例如词元 search 的范围是 [0, 6),表示从第 0 个字符开始,到第 6 个字符之前结束。字符过滤器若改变文本长度,需要正确维护偏移修正,否则可能出现高亮范围偏移。
词元类型通常不是查询命中的直接条件,但能帮助判断分词器是否把内容识别为预期类别。例如订单号被拆成多个普通单词,而业务希望整体保留,就应检查分词器和 pattern 规则。
对比索引分析与查询分析
定位“明明包含却搜不到”时,应分别测试索引分析器和查询分析器。下面假设字段使用 my_index_analyzer 写入,使用 my_search_analyzer 查询;这两个名称必须已经存在于目标索引设置中。
POST /articles/_analyze
{
"analyzer": "my_index_analyzer",
"text": "Quick Search"
}预期结果应记录索引端产生的词元,例如:
quick
search再执行查询端分析:
POST /articles/_analyze
{
"analyzer": "my_search_analyzer",
"text": "Quick Search"
}预期结果应与索引端至少存在可匹配词元。若查询端只生成 quick search 这个整体词元,而索引端保存的是两个独立词元,普通匹配就可能失败。
查询端词元应与索引端词元兼容;若完全无交集,需要调整分析器或查询方式。实际分析器名称、索引名和响应细节可能不同,应以当前环境的映射与设置为准。
排查顺序
先确认查询类型是否会分析输入,match 会分析,term 不会。再用字段方式测试真实索引配置,记录词元、位置和偏移量。最后分别模拟索引端与查询端,比较是否存在词元交集以及位置是否满足短语条件。
如果分析结果正确但仍未命中,应继续检查目标字段、布尔条件、最小匹配数、过滤器范围和文档是否已经重建。Analyze API 只能证明文本分析过程,不能替代完整查询诊断。
本课总结
- Analyze API 可以直接暴露文本最终生成的词元及其位置、偏移量
- 排查真实字段时优先使用索引级
field参数,避免脱离映射配置 - 匹配失败应同时比较索引端和查询端分析结果,并确认查询类型是否执行分析
下一课预告
下一课将进入中文分词,比较不同切分粒度对召回率与准确率的影响,并说明如何为中文字段选择合适的分析器。