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 中执行。

json
POST /_analyze
{
  "analyzer": "standard",
  "text": "Search APIs are useful.",
  "explain": true,
  "attributes": [
    "term",
    "position",
    "positionLength",
    "startOffset",
    "endOffset",
    "type"
  ]
}

预期结果中会出现 search、apis、are、useful 等词元。完整 JSON 的内部结构会因 Elasticsearch 版本和分析链配置有所差异,但核心词元及其先后顺序应一致。

text
position  token   start_offset  end_offset
0         search  0             6
1         apis    7             11
2         are     12            15
3         useful  16            22

token 是最终用于索引或查询的词项;position 表示词元在词元流中的逻辑位置;start_offset 和 end_offset 表示它在原始文本中的字符范围;type 则说明词元类别,例如单词、数字或其他分词器定义的类型。

使用索引字段的真实配置

直接指定 analyzer 只能验证某个分析器,不能保证与实际字段一致。若索引 articles 的 title 字段已经配置分析器,应通过 field 参数复用该字段的分析设置。

json
POST /articles/_analyze
{
  "field": "title",
  "text": "Elasticsearch 中文搜索"
}

预期结果取决于 title 字段的实际映射。验证重点不是固定词元数量,而是确认响应中的词元与字段写入时使用的规则一致。

text
返回 title 字段分析器生成的词元列表;具体词元由该字段映射决定。

当请求同时提供 field 和 analyzer 时,不应依赖含糊的优先级来排查问题。更稳妥的做法是一次只指定一种来源,避免误以为测试了字段配置,实际却使用了临时分析器。

用位置与偏移量判断异常

位置主要影响短语查询和词序判断。若同义词过滤器把多个词放在同一位置,可能出现两个词元共享同一个 position;若停用词被删除,后续词元的位置可能出现间隔。短语查询是否命中,不只看词元内容,还与位置增量和允许的 slop 有关。

偏移量主要服务于高亮和原文定位。例如词元 search 的范围是 [0, 6),表示从第 0 个字符开始,到第 6 个字符之前结束。字符过滤器若改变文本长度,需要正确维护偏移修正,否则可能出现高亮范围偏移。

词元类型通常不是查询命中的直接条件,但能帮助判断分词器是否把内容识别为预期类别。例如订单号被拆成多个普通单词,而业务希望整体保留,就应检查分词器和 pattern 规则。

对比索引分析与查询分析

定位“明明包含却搜不到”时,应分别测试索引分析器和查询分析器。下面假设字段使用 my_index_analyzer 写入,使用 my_search_analyzer 查询;这两个名称必须已经存在于目标索引设置中。

json
POST /articles/_analyze
{
  "analyzer": "my_index_analyzer",
  "text": "Quick Search"
}

预期结果应记录索引端产生的词元,例如:

text
quick
search

再执行查询端分析:

json
POST /articles/_analyze
{
  "analyzer": "my_search_analyzer",
  "text": "Quick Search"
}

预期结果应与索引端至少存在可匹配词元。若查询端只生成 quick search 这个整体词元,而索引端保存的是两个独立词元,普通匹配就可能失败。

text
查询端词元应与索引端词元兼容;若完全无交集,需要调整分析器或查询方式。

实际分析器名称、索引名和响应细节可能不同,应以当前环境的映射与设置为准。

排查顺序

先确认查询类型是否会分析输入,match 会分析,term 不会。再用字段方式测试真实索引配置,记录词元、位置和偏移量。最后分别模拟索引端与查询端,比较是否存在词元交集以及位置是否满足短语条件。

如果分析结果正确但仍未命中,应继续检查目标字段、布尔条件、最小匹配数、过滤器范围和文档是否已经重建。Analyze API 只能证明文本分析过程,不能替代完整查询诊断。

本课总结

  • Analyze API 可以直接暴露文本最终生成的词元及其位置、偏移量
  • 排查真实字段时优先使用索引级 field 参数,避免脱离映射配置
  • 匹配失败应同时比较索引端和查询端分析结果,并确认查询类型是否执行分析

下一课预告

下一课将进入中文分词,比较不同切分粒度对召回率与准确率的影响,并说明如何为中文字段选择合适的分析器。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

使用 Analyze API

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通