高亮显示使您能够从包含匹配关键词的文档中获取高亮的文本片段（称为片段）。
SQL 中的 HIGHLIGHT() 函数，通过 HTTP 的 JSON 查询中的 "highlight" 属性，以及 PHP 客户端中的 highlight() 函数，均利用内置的文档存储来检索原始字段内容（默认启用）。
- SQL
- JSON
- PHP
- Python
- Python-asyncio
- Javascript
- Java
- C#
- Rust
- TypeScript
- Go
SELECT HIGHLIGHT() FROM books WHERE MATCH('try');+----------------------------------------------------------+
| highlight() |
+----------------------------------------------------------+
| Don`t <b>try</b> to compete in childishness, said Bliss. |
+----------------------------------------------------------+
1 row in set (0.00 sec)当使用 SQL 进行搜索结果高亮时，由于 MySQL 协议的限制，您将从多个字段接收合并为单个字符串的片段。您可以通过下面详细说明的 field_separator 和 snippet_separator 选项调整拼接分隔符。
当通过 HTTP 执行 JSON 查询或使用 PHP 客户端时，没有此类限制，结果集将包含一个字段数组，每个字段包含片段数组（无分隔符）。
请注意，生成片段的选项如 limit、limit_words 和 limit_snippets 默认是针对每个字段单独生效的。您可以通过 limits_per_field 选项更改此行为，但这可能导致不希望出现的结果。例如，某个字段有匹配的关键词，但因高亮引擎中该字段的片段排名不如其他字段高，导致该字段的片段未包含在结果集中。
当前的高亮算法优先考虑更好的片段（具有更接近的短语匹配），其次是包含当前结果中尚未出现的关键词的片段。通常，它旨在高亮查询的最佳匹配，并高亮全部查询关键词（受限制条件允许）。如果当前字段没有匹配，则根据限制剪裁文档开头并返回默认内容。若想返回空字符串，请将 allow_empty 选项设置为 1。
高亮是在所谓的 post limit 阶段执行的，这意味着片段生成被推迟，不仅直到整个最终结果集准备好，而且在应用 LIMIT 子句之后。例如，使用 LIMIT 20,10 子句时，HIGHLIGHT() 函数最多会被调用 10 次。
有若干可选高亮选项可用于微调片段生成，这些选项在 SQL、HTTP 和 PHP 客户端中通用。
插入到关键词匹配前的字符串。此字符串中可以使用 %SNIPPET_ID% 宏。宏的第一次出现会被替换成当前片段内递增的片段编号。编号默认从 1 开始，但可用 start_snippet_id 选项覆盖。%SNIPPET_ID% 在每个新文档开头重新计数。默认值是 <b>。
插入到关键词匹配后的字符串。默认值是 </b>。
片段最大大小，单位为符号（代码点）。默认值是 256。默认情况下此限制针对每个字段单独应用，具体见 limits_per_field。
限制结果中包含的最大单词数。注意此限制应用于所有单词，而不仅仅是要高亮的匹配关键词。例如，高亮 Mary，而选中的片段为 Mary had a little lamb，这将计入 5 个单词，而非仅 1。默认值是 0（无限制）。默认情况下此限制针对每个字段单独应用，具体见 limits_per_field。
限制结果中包含的最大片段数。默认值是 0（无限制）。默认情况下此限制针对每个字段单独应用，具体见 limits_per_field。
决定 limit、limit_words 和 limit_snippets 是在每个字段内分别独立限制，还是对整个文档作为全局限制。将此选项设置为 0 表示一个文档的所有合并高亮结果必须在指定限制内。缺点是如果高亮引擎判断某些片段更相关，某字段可能突出显示多个片段，而另一个字段可能没有片段。默认值是 1（使用每字段限制）。
每个匹配关键词块周围选择的单词数。默认值是 5。
决定是否通过在表设置中使用 phrase_boundary 指令配置的短语边界字符，额外拆分片段。默认值是 0（不使用边界）。
指定是否按相关性（权重递减）排序提取的片段，或者按在文档中出现的顺序（位置递增）排序。默认值是 0（不使用权重排序）。
忽略长度限制，直到结果包含所有关键词。默认值是 0（不强制包含所有关键词）。
设置 %SNIPPET_ID% 宏的起始值（该宏会在 before_match、after_match 字符串中被检测并展开）。默认值是 1。
定义HTML剥离模式设置。默认为index，表示将使用表设置。其他值包括none和strip，它们会强制跳过或应用剥离，无视表设置；以及retain，它会保留HTML标记并保护其不被高亮。retain模式仅在高亮完整文档时可用，因此要求不设置任何片段大小限制。允许的字符串值为none、strip、index和retain。
当当前字段无法生成任何片段（无关键词匹配或无片段符合限制）时，允许返回空字符串作为高亮结果。默认情况下，将返回原始文本的开头而不是空字符串。默认值为0（不允许空结果）。
确保片段不跨越句子、段落或区域边界（当与启用了相应索引设置的表一起使用时）。允许的值为sentence、paragraph和zone。
在每个片段前输出一个包含包围区域名称的HTML标签。默认值为0（不输出区域名称）。
决定即使限制允许高亮整个文本时，是否强制生成片段。默认值为0（不强制生成片段）。
- SQL
- JSON
- PHP
- Python
- Python-asyncio
- Javascript
- Java
- C#
- Rust
- TypeScript
- Go
SELECT HIGHLIGHT({limit=50}) FROM books WHERE MATCH('try|gets|down|said');+---------------------------------------------------------------------------+
| highlight({limit=50}) |
+---------------------------------------------------------------------------+
| ... , "It <b>gets</b> infantile pleasure ... to knock it <b>down</b>." |
| Don`t <b>try</b> to compete in childishness, <b>said</b> Bliss. |
| ... a small room. Bander <b>said</b>, "Come, half-humans, I ... |
+---------------------------------------------------------------------------+
3 rows in set (0.00 sec)HIGHLIGHT()函数可用于高亮搜索结果。语法如下：
HIGHLIGHT([options], [field_list], [query] )默认情况下，它无需参数即可工作。
- SQL
SELECT HIGHLIGHT() FROM books WHERE MATCH('before');+-----------------------------------------------------------+
| highlight() |
+-----------------------------------------------------------+
| A door opened <b>before</b> them, revealing a small room. |
+-----------------------------------------------------------+
1 row in set (0.00 sec)HIGHLIGHT()从文档存储中检索所有可用的全文字段，并根据提供的查询对它们进行高亮。查询中的字段语法受支持。字段文本由field_separator分隔，该分隔符可在选项中修改。
- SQL
SELECT HIGHLIGHT() FROM books WHERE MATCH('@title one');+-----------------+
| highlight() |
+-----------------+
| Book <b>one</b> |
+-----------------+
1 row in set (0.00 sec)HIGHLIGHT()中的可选第一个参数是选项列表。
- SQL
SELECT HIGHLIGHT({before_match='[match]',after_match='[/match]'}) FROM books WHERE MATCH('@title one');+------------------------------------------------------------+
| highlight({before_match='[match]',after_match='[/match]'}) |
+------------------------------------------------------------+
| Book [match]one[/match] |
+------------------------------------------------------------+
1 row in set (0.00 sec)可选的第二个参数是一个包含单个字段或逗号分隔字段列表的字符串。如果存在此参数，则仅从文档存储中获取并高亮指定的字段。空字符串作为第二个参数表示“获取所有可用字段”。
- SQL
SELECT HIGHLIGHT({},'title,content') FROM books WHERE MATCH('one|robots');+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| highlight({},'title,content') |
+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Book <b>one</b> | They followed Bander. The <b>robots</b> remained at a polite distance, but their presence was a constantly felt threat. |
| Bander ushered all three into the room. <b>One</b> of the <b>robots</b> followed as well. Bander gestured the other <b>robots</b> away and entered itself. The door closed behind it. |
+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
2 rows in set (0.00 sec)或者，您可以使用第二个参数指定不带引号的字符串属性或字段名称。在这种情况下，提供的字符串将根据给定的查询进行高亮，但字段语法将被忽略。
- SQL
SELECT HIGHLIGHT({}, title) FROM books WHERE MATCH('one');+---------------------+
| highlight({},title) |
+---------------------+
| Book <b>one</b> |
| Book five |
+---------------------+
2 rows in set (0.00 sec)可选的第三个参数是查询。这用于根据与搜索所用查询不同的查询来高亮搜索结果。
- SQL
SELECT HIGHLIGHT({},'title', 'five') FROM books WHERE MATCH('one');+-------------------------------+
| highlight({},'title', 'five') |
+-------------------------------+
| Book one |
| Book <b>five</b> |
+-------------------------------+
2 rows in set (0.00 sec)尽管HIGHLIGHT()设计用于处理存储的全文字段和字符串属性，但它也可用于高亮任意文本。请注意，如果查询包含任何字段搜索运算符（例如@title hello @body world），在这种情况下，其字段部分将被忽略。
- SQL
SELECT HIGHLIGHT({},TO_STRING('some text to highlight'), 'highlight') FROM books WHERE MATCH('@title one');+----------------------------------------------------------------+
| highlight({},TO_STRING('some text to highlight'), 'highlight') |
+----------------------------------------------------------------+
| some text to <b>highlight</b> |
+----------------------------------------------------------------+
1 row in set (0.00 sec)有几个选项仅当生成单个字符串作为结果（而不是片段数组）时才相关。这仅适用于SQL HIGHLIGHT()函数：
插入片段之间的字符串。默认为...。
插入字段之间的字符串。默认为|。
另一种高亮文本的方法是使用CALL SNIPPETS语句。这基本上复制了HIGHLIGHT()的功能，但无法使用内置文档存储。不过，它可以从文件加载源文本。
要通过HTTP在JSON查询中高亮全文搜索结果，字段内容必须存储在文档存储中（默认启用）。在示例中，全文字段content和title从文档存储中获取，并根据query子句中指定的查询进行高亮。
高亮的片段在hits数组的highlight属性中返回。
- JSON
- PHP
- Python
- Python-asyncio
- Javascript
- Java
- C#
- Rust
- TypeScript
- Go
POST /search
{
"table": "books",
"query": { "match": { "*": "one|robots" } },
"highlight":
{
"fields": ["content"]
}
}{
"took": 0,
"timed_out": false,
"hits": {
"total": 1,
"hits": [
{
"_id": 1,
"_score": 2788,
"_source": {
"title": "Books one",
"content": "They followed Bander. The robots remained at a polite distance, but their presence was a constantly felt threat. Bander ushered all three into the room. One of the robots followed as well. Bander gestured the other robots away and entered itself. The door closed behind it. "
},
"highlight": {
"content": [
"They followed Bander. The <b>robots</b> remained at a polite distance, ",
" three into the room. <b>One</b> of the <b>robots</b> followed as well. Bander",
" gestured the other <b>robots</b> away and entered itself. The"
]
}
}
]
}
}为了高亮所有可能的字段，请将空对象作为 highlight 属性传递。
- JSON
- PHP
- Python
- Python-asyncio
- Javascript
- Java
- C#
- Rust
- TypeScript
- Go
POST /search
{
"table": "books",
"query": { "match": { "*": "one|robots" } },
"highlight": {}
}{
"took": 0,
"timed_out": false,
"hits": {
"total": 1,
"hits": [
{
"_id": 1,
"_score": 2788,
"_source": {
"title": "Books one",
"content": "They followed Bander. The robots remained at a polite distance, but their presence was a constantly felt threat. Bander ushered all three into the room. One of the robots followed as well. Bander gestured the other robots away and entered itself. The door closed behind it. "
},
"highlight": {
"title": [
"Books <b>one</b>"
],
"content": [
"They followed Bander. The <b>robots</b> remained at a polite distance, ",
" three into the room. <b>One</b> of the <b>robots</b> followed as well. Bander",
" gestured the other <b>robots</b> away and entered itself. The"
]
}
}
]
}
}除了常见的高亮选项外，还可以通过 HTTP 查询 JSON 查询时使用一些同义词：
fields 对象包含属性名称及其选项。它也可以是一个字段名称的数组（没有选项）。
请注意，默认情况下，高亮尝试根据全文查询高亮结果。在一般情况下，如果不指定要高亮的字段，则高亮基于您的全文查询。但是，如果您指定了要高亮的字段，则仅在全文查询匹配选定字段时进行高亮。
encoder 可以设置为 default 或 html。设置为 html 时，高亮时保留 HTML 标记。这类似于 html_strip_mode=retain 选项。
- JSON
- PHP
- Python
- Python-asyncio
- Javascript
- Java
- C#
- Rust
- TypeScript
- Go
POST /search
{
"table": "books",
"query": { "match": { "content": "one|robots" } },
"highlight":
{
"fields": [ "content"],
"highlight_query": { "match": { "*":"polite distance" } }
}
}{'aggregations': None,
'hits': {'hits': [{u'_id': u'1',
u'_score': 1788,
u'_source': {u'content': u'They followed Bander. The robots remained at a polite distance, but their presence was a constantly felt threat. Bander ushered all three into the room. One of the robots followed as well. Bander gestured the other robots away and entered itself. The door closed behind it. ',
u'title': u'Books one'},
u'highlight': {u'content': [u'. The robots remained at a <b>polite distance</b>, but their presence was a']}}],
'max_score': None,
'total': 1},
'profile': None,
'timed_out': False,
'took': 0}- JSON
- PHP
- Python
- Python-asyncio
- Javascript
- Java
- C#
- Rust
- TypeScript
- Go
POST /search
{
"table": "books",
"query": { "match": { "*": "one|robots" } },
"highlight":
{
"fields": [ "content", "title" ],
"pre_tags": "before_",
"post_tags": "_after"
}
}Document: 1
title : Books one
content : They followed Bander. The robots remained at a polite distance, but their presence was a constantly felt threat. Bander ushered all three into the room. One of the robots followed as well. Bander gestured the other robots away and entered itself. The door closed behind it.
Highlight for content:
- They followed Bander. The before_robots_after remained at a polite distance,
- three into the room. before_One_after of the before_robots_after followed as well. Bander
- gestured the other before_robots_after away and entered itself. The
Highlight for title:
- Books before_one_after- JSON
- PHP
- Python
- Python-asyncio
- Javascript
- Java
- C#
- Rust
- TypeScript
- Go
POST /search
{
"table": "books",
"query": { "match": { "*": "one|robots" } },
"highlight":
{
"fields": [ "content", "title" ],
"no_match_size": 0
}
}Document: 1
title : Books one
content : They followed Bander. The robots remained at a polite distance, but their presence was a constantly felt threat. Bander ushered all three into the room. One of the robots followed as well. Bander gestured the other robots away and entered itself. The door closed behind it.
Highlight for content:
- They followed Bander. The <b>robots</b> remained at a polite distance,
- three into the room. <b>One</b> of the <b>robots</b> followed as well. Bander
- gestured the other <b>robots</b> away and entered itself. The
Highlight for title:
- Books <b>one</b>- JSON
- PHP
- Python
- Python-asyncio
- Javascript
- Java
- C#
- Rust
- TypeScript
- Go
POST /search
{
"table": "books",
"query": { "match": { "*": "one|robots" } },
"highlight":
{
"fields": [ "content", "title" ],
"order": "score"
}
}Document: 1
title : Books one
content : They followed Bander. The robots remained at a polite distance, but their presence was a constantly felt threat. Bander ushered all three into the room. One of the robots followed as well. Bander gestured the other robots away and entered itself. The door closed behind it.
Highlight for content:
- three into the room. <b>One</b> of the <b>robots</b> followed as well. Bander
- gestured the other <b>robots</b> away and entered itself. The
- They followed Bander. The <b>robots</b> remained at a polite distance,
Highlight for title:
- Books <b>one</b>- JSON
- PHP
- Python
- Python-asyncio
- Javascript
- Java
- C#
- Rust
- TypeScript
- Go
POST /search
{
"table": "books",
"query": { "match": { "*": "one|robots" } },
"highlight":
{
"fields": [ "content", "title" ],
"fragment_size": 100
}
}Document: 1
title : Books one
content : They followed Bander. The robots remained at a polite distance, but their presence was a constantly felt threat. Bander ushered all three into the room. One of the robots followed as well. Bander gestured the other robots away and entered itself. The door closed behind it.
Highlight for content:
- the room. <b>One</b> of the <b>robots</b> followed as well
- Bander gestured the other <b>robots</b> away and entered
Highlight for title:
- Books <b>one</b>number_of_fragments 限制结果中的最大片段数量。与 fragment_size 类似，它可以是全局的或字段特定的。这是可选的，默认值为 0（无限制）。它类似于 limit_snippets 选项。
- JSON
- PHP
- Python
- Python-asyncio
- Javascript
- Java
- C#
- Rust
- TypeScript
- Go
POST /search
{
"table": "books",
"query": { "match": { "*": "one|robots" } },
"highlight":
{
"fields": [ "content", "title" ],
"number_of_fragments": 10
}
}Document: 1
title : Books one
content : They followed Bander. The robots remained at a polite distance, but their presence was a constantly felt threat. Bander ushered all three into the room. One of the robots followed as well. Bander gestured the other robots away and entered itself. The door closed behind it.
Highlight for content:
- They followed Bander. The <b>robots</b> remained at a polite distance,
- three into the room. <b>One</b> of the <b>robots</b> followed as well. Bander
- gestured the other <b>robots</b> away and entered itself. The
Highlight for title:
- Books <b>one</b>选项如 limit、limit_words 和 limit_snippets 可以设置为全局或字段特定选项。全局选项会在字段特定选项未被覆盖时使用。在示例中，title 字段使用默认限制设置进行高亮显示，而 content 字段使用不同的限制。
- JSON
- PHP
- Python
- Python-asyncio
- Javascript
- Java
- C#
- Rust
- TypeScript
- Go
POST /search
{
"table": "books",
"query": { "match": { "*": "one|robots" } },
"highlight":
{
"fields":
{
"title": {},
"content" : { "limit": 50 }
}
}
}Document: 1
title : Books one
content : They followed Bander. The robots remained at a polite distance, but their presence was a constantly felt threat. Bander ushered all three into the room. One of the robots followed as well. Bander gestured the other robots away and entered itself. The door closed behind it.
Highlight for content:
- into the room. <b>One</b> of the <b>robots</b> followed as well
Highlight for title:
- Books <b>one</b>也可以通过设置 limits_per_field=0 来强制执行全局限制。设置此选项意味着所有组合的高亮结果必须在指定的限制内。缺点是，如果高亮引擎认为某些内容更相关，则可能会在一个字段中获得多个片段高亮显示而在另一个字段中没有任何片段高亮显示。
- JSON
- PHP
- Python
- Python-asyncio
- Javascript
- Java
- C#
- Rust
- TypeScript
- Go
POST /search
{
"table": "books",
"query": { "match": { "content": "and first" } },
"highlight":
{
"limits_per_field": false,
"fields":
{
"content" : { "limit": 50 }
}
}
}Document: 1
title : Books one
content : They followed Bander. The robots remained at a polite distance, but their presence was a constantly felt threat. Bander ushered all three into the room. One of the robots followed as well. Bander gestured the other robots away and entered itself. The door closed behind it.
Highlight for content:
- gestured the other robots away <b>and</b> entered itself. The door closedCALL SNIPPETS 语句使用提供的数据和查询以及指定的表设置构建一个片段。它不能访问内置文档存储，因此建议使用 HIGHLIGHT() 函数。
语法如下：
CALL SNIPPETS(data, table, query[, opt_value AS opt_name[, ...]])data 是从中提取片段的来源。它可以是一个字符串或用花括号包围的字符串列表。
table 是提供片段生成文本处理设置的表名。
query 是用于构建片段的全文查询。
opt_value 和 opt_name 表示 片段生成选项。
- SQL
CALL SNIPPETS(('this is my document text','this is my another text'), 'forum', 'is text', 5 AS around, 200 AS limit);+----------------------------------------+
| snippet |
+----------------------------------------+
| this <b>is</b> my document <b>text</b> |
| this <b>is</b> my another <b>text</b> |
+----------------------------------------+
2 rows in set (0.02 sec)大多数选项与HIGHLIGHT()函数中的相同。然而，有几个选项只能与CALL SNIPPETS一起使用。
以下选项可用于突出显示存储在单独文件中的文本：
启用此选项时，将第一个参数视为文件名，而不是用于提取片段的数据。服务器端指定的文件将被加载作为数据。当启用此标志时，每个请求将使用最多max_threads_per_query个工作线程来并行处理工作。默认值为0（无上限）。要在远程代理之间分发片段生成，请在仅包含一个本地代理和若干远程代理的分布式表中调用片段生成。snippets_file_prefix选项用于生成最终文件名。例如，当searchd配置为snippets_file_prefix = /var/data_且提供text.txt作为文件名时，片段将从/var/data_text.txt的内容中生成。
此选项仅适用于带有远程代理的分布式片段生成。片段生成的源文件可以分布在不同的代理上，主服务器将合并所有无错误的结果。例如，如果分布式表的一个代理拥有file1.txt，另一个代理拥有file2.txt，并且你使用包含这两个文件的CALL SNIPPETS，searchd将合并代理结果，因此你将获得来自file1.txt和file2.txt的结果。默认值为0。
如果同时启用了load_files选项，当任何文件在任何位置不可用时，请求将返回错误。否则（如果未启用load_files），所有缺失文件将返回空字符串。searchd不会将此标志传递给代理，因此如果文件不存在，代理不会生成严重错误。如果您想确保所有源文件都已加载，请将load_files_scattered和load_files都设置为1。如果某些代理缺少部分源文件不重要，则只需将load_files_scattered设置为1。
- SQL
CALL SNIPPETS(('data/doc1.txt','data/doc2.txt'), 'forum', 'is text', 1 AS load_files);+----------------------------------------+
| snippet |
+----------------------------------------+
| this <b>is</b> my document <b>text</b> |
| this <b>is</b> my another <b>text</b> |
+----------------------------------------+
2 rows in set (0.02 sec)