高亮 #

高亮用于在返回结果中突出显示命中的查询词，方便用户快速定位关键信息。

基础用法 #

在查询体中添加 highlight 段即可启用：

GET shakespeare/_search
{
  "query": {
    "match": { "text_entry": "life" }
  },
  "highlight": {
    "fields": {
      "text_entry": {}
    }
  }
}

响应中每条命中文档会带一个 highlight 对象，默认使用 <em> 标签包裹：

"highlight": {
  "text_entry": [
    "my <em>life</em>, except my <em>life</em>."
  ]
}

自定义标签 #

通过 pre_tags / post_tags 自定义包裹标签：

GET shakespeare/_search
{
  "query": {
    "match": { "play_name": "Henry IV" }
  },
  "highlight": {
    "pre_tags": ["<strong>"],
    "post_tags": ["</strong>"],
    "fields": {
      "play_name": {}
    }
  }
}

也可以使用 "tags_schema": "styled" 启用内置的多级标签样式（<em class="hlt1">、<em class="hlt2"> 等）。

高亮器类型（type） #

Easysearch 支持三种高亮器，通过 type 参数指定：

类型	说明	特点
`unified`	默认，基于 Lucene Unified Highlighter	性能好，支持所有字段类型
`plain`	标准高亮器	精确度高，适合小字段
`fvh`	Fast Vector Highlighter	需要 `term_vector` 设置，适合大文本字段

GET shakespeare/_search
{
  "query": {
    "match": { "text_entry": "life" }
  },
  "highlight": {
    "fields": {
      "text_entry": {
        "type": "unified"
      }
    }
  }
}

选择建议 #

场景	推荐类型
通用场景	`unified`（默认即可）
需要精确片段控制	`plain`
大文本字段（如文章正文）	`fvh`（需在 mapping 中设置 `"term_vector": "with_positions_offsets"`）

片段控制参数 #

参数	说明	默认值
`fragment_size`	每个高亮片段的最大字符数	100
`number_of_fragments`	返回的最大片段数量	5
`no_match_size`	无匹配时返回的字段内容长度（0 表示不返回）	0
`fragment_offset`	片段的起始偏移量（仅 `fvh`）	-
`order`	片段排序方式，`score` 表示按相关性排序	无特定排序

GET shakespeare/_search
{
  "query": {
    "match": { "text_entry": "life" }
  },
  "highlight": {
    "fields": {
      "text_entry": {
        "fragment_size": 150,
        "number_of_fragments": 3,
        "no_match_size": 50
      }
    }
  }
}

高级参数 #

参数	说明	默认值
`require_field_match`	是否只高亮查询中指定的字段	true
`highlight_query`	使用不同于主查询的查询来生成高亮	主查询
`matched_fields`	组合多个字段的匹配来生成高亮（仅 `fvh`）	-
`phrase_limit`	短语匹配的最大数量（仅 `fvh`）	256
`encoder`	输出编码方式	`default`（原文）或 `html`（HTML 转义）

边界扫描参数（boundary_scanner） #

控制高亮片段如何在句子/段落边界处截断：

参数	说明	默认值
`boundary_scanner`	边界扫描模式	`chars`（字符级）、`sentence`（句子级）、`word`（词级）
`boundary_chars`	作为边界的字符集	`.,!? \t\n`
`boundary_max_scan`	扫描边界字符的最大范围	20
`boundary_scanner_locale`	句子/词级分割的语言区域	系统默认

GET shakespeare/_search
{
  "query": {
    "match": { "text_entry": "question" }
  },
  "highlight": {
    "fields": {
      "text_entry": {
        "boundary_scanner": "sentence",
        "fragment_size": 200
      }
    }
  }
}

多字段高亮 #

可以同时高亮多个字段，每个字段可以有不同的配置：

GET shakespeare/_search
{
  "query": {
    "multi_match": {
      "query": "king",
      "fields": ["play_name", "text_entry"]
    }
  },
  "highlight": {
    "fields": {
      "play_name": {
        "number_of_fragments": 0
      },
      "text_entry": {
        "fragment_size": 150,
        "number_of_fragments": 3
      }
    }
  }
}

提示：number_of_fragments 设为 0 时返回整个字段内容而非片段，适合短字段（如标题）。

同义词/词干：即便查询时启用了同义词或词干还原，高亮依然会基于原始文本中的命中词来生成片段，保证展示对用户友好。