Suggesters
suggest的特性通过使用建议器suggester推荐给用户正在查找的term提供基于文本的相似term。部分 suggest 功能还在开发中。
在_search请求中,suggest request部分与查询部分一起定义。如果省略查询部分,则只返回建议。
注意: _suggest端点已被弃用,转而使用通过_search端点建议。 在5.0中,_search端点已经过优化,仅用于建议搜索请求。
POST twitter/_search
{
"query" : {
"match": {
"message": "tring out Elasticsearch"
}
},
"suggest" : {
"my-suggestion" : {
"text" : "tring out Elasticsearch",
"term" : {
"field" : "message"
}
}
}
}
可以根据请求指定几个建议。 每个建议都以任意名称标识。 在下面的示例中,请求了两个建议。 my-suggest-1和my-sugges-2建议都使用term建议,但有不同的文本。
POST _search
{
"suggest": {
"my-suggest-1" : {
"text" : "tring out Elasticsearch",
"term" : {
"field" : "message"
}
},
"my-suggest-2" : {
"text" : "kmichy",
"term" : {
"field" : "user"
}
}
}
}
下面的 suggest 响应示例包括对于 my-suggest-1 和 my-suggestion-2 的 suggest 响应。 每个suggest 部分包含条目(entries)。 每个条目实际上是来自 suggest 文本的 token ,并且包含 suggest 条目文本,suggest 文本中的原始起始偏移(offset)和长度,以及如果找到任意数目的选项。
{
"_shards": ...
"hits": ...
"took": 2,
"timed_out": false,
"suggest": {
"my-suggest-1": [ {
"text": "tring",
"offset": 0,
"length": 5,
"options": [ {"text": "trying", "score": 0.8, "freq": 1 } ]
}, {
"text": "out",
"offset": 6,
"length": 3,
"options": []
}, {
"text": "elasticsearch",
"offset": 10,
"length": 13,
"options": []
} ],
"my-suggest-2": ...
}
}
每个选项数组(option array)包含一个选项对象,其中包括 suggest 文本,其文档频率和分数与 suggest 输入文本相比较。 分数的意义取决于使用的suggester。 Term suggester 的分数是基于编辑(edit)距离。
Global suggest text
为了避免重复 suggest 文本,可以定义全局文本。 在下面的示例中,suggest 文本是全局定义的,并适用于 my-suggest-1 和 my-suggest-2 建议。
POST _search
{
"suggest": {
"text" : "tring out Elasticsearch",
"my-suggest-1" : {
"term" : {
"field" : "message"
}
},
"my-suggest-2" : {
"term" : {
"field" : "user"
}
}
}
}
在上述示例中,suggest 文本也可以被指定为 suggest 特定选项。 在 suggestion 级别上指定的 suggest 文本覆盖全局级别上的 suggest 文本。
term suggester
注意:为了理解 suggestions 的形式,请先阅读 suggestions 第一页。
term suggester根据编辑距离建议terms。 在建议terms之前分析提供的建议文本。 建议的terms是根据分析的建议文本token提供的。 term suggester不会将查询作为请求的一部分。
Common suggest options:
text
suggest 文本,suggest 文本是必须选项,需要被设定为全局或者对每个进行suggestion
field
获取候选suggestions 的字段(field)。这是一个必需的选项,需要全局设置或按 suggestion 设置。
analyzer
analyzer 跟 suggest 文本一起进行分析,默认为 suggest 字段的搜索 analyzer。
size
每个 suggest 文本token(token)返回的最大更正值。
sort
定义每个 suggest text terms中 suggestions 该如何排序。 两个可能的值: Score:首先按分数排序,然后是文档频率,最后是terms本身。
Frequency:首先按文档频率排序,然后是相似度评分,最后是terms本身。
suggest_mode
suggest_mode控制包含哪些suggestions,或者控制应该suggest哪些text terms。可以指定三个可能的值:
Missing:仅为索引中没有的suggest text terms提供suggestions。这是默认值。
Popular: 只 suggest 出现在更多文档中的 suggestions,而不是原始 suggest text terms
always: 根据 suggest 文字中的字词 suggest 任何相符的 suggestions。
Other term suggest options:
lowercase_terms
在文本分析之后缩小suggest text terms
max_edits
可以认为是候选 suggestions 的最大编辑距离。只能是介于1和2之间的值。任何其他值都会导致抛出错误的请求错误。默认为2。
prefix_length
为了成为候选suggestions所必须匹配的最小前缀字符的数量。默认值为1.增加此数字可提高拼写检查性能。通常拼写错误不会出现在terms的开头。(旧名称 “prefix_len” 已弃用)
min_word_length
suggest text term 必须包含的最小长度。 默认值为4.(旧名称 “min_word_len” 已弃用)
shard_size
设置要从每个单独的分片检索的 suggestions 的最大数量。在减少阶段期间,仅基于 size 选项返回前N个 suggestions。默认为 size 选项。将其设置为大于该 size 的值可以是有用的,以便以性能为代价获得更准确的拼写校正的文档频率。由于terms在分片之间分割的事实,拼写校正的分片级文档频率可能不精确。增加这将使这些文档频率更精确。
max_inspections
用于乘以 shards_size 以便在碎片级别上检查更多候选拼写校正的因子。 可以以性能为代价提高精度。 默认为5。
min_doc_freq
suggestion 应该出现的文档数量的最小阈值。这可以指定为绝对数字或文档数量的相对百分比。 这可以通过仅 suggesting 高频项来提高质量。 默认值为 0f ,未启用。 如果指定的值大于1,则该数字不能为小数。 分片级文档频率用于此选项。
max_term_freq
suggest 文本token可以存在的文档数量中的最大阈值,以便包括。 可以是表示文档频率的相对百分比数字(例如0.4)或绝对数字。 如果指定的值大于1,则不能指定小数。 默认为 0.01f。 这可以用于排除高频terms的拼写检查。 高频项通常拼写正确,这也提高了拼写检查的性能。 分片级文档频率用于此选项。
string_distance
使用哪个字符串距离实现来比较类似的 suggested terms。 可以指定五个可能的值:
internal:
基于 damerau_levenshtein的默认值,但是高度优化用于比较索引中的项的字符串距离。
damerau_levenshtein:
基于 Damerau-Levenshtein 算法的字符串距离算法
levenshtein:
基于 Levenstein 编码距离算法的字符串距离算法。
jaro_winkler:
基于 Jaro-Winkler 算法的字符串距离算法。
ngram:
基于字符 n-gram 的字符串距离算法。
Phrase Suggester
注意:为了理解 suggestions 的形式,请先阅读 suggestions 第一页。
term suggester 提供了一种非常方便的 API ,可以根据每个 token 在一定的字符串距离内访问单词替代。 API 允许单独访问流中的每个 token ,而 suggest 选择由API使用者选择。 然而,通常需要预先选择的 suggestions 以呈现给最终用户。短语 suggester 在 term suggester 之上添加额外的逻辑以选择整个经校正的短语,而不是基于 ngram-language模型加权的单个 token 。 在实践中,这个 suggester 将能够基于共现和频率来做出关于选择哪些 token 的更好的决定。
API Example
一般来说,phrase suggester 需要前面的特殊映射。 此页面上的 phrase suggester 示例需要以下映射才能正常工作。 仅在最后一个示例中使用反向(reverse)分析器。
PUT test
{
"settings": {
"index": {
"number_of_shards": 1,
"analysis": {
"analyzer": {
"trigram": {
"type": "custom",
"tokenizer": "standard",
"filter": ["lowercase","shingle"]
},
"reverse": {
"type": "custom",
"tokenizer": "standard",
"filter": ["lowercase","reverse"]
}
},
"filter": {
"shingle": {
"type": "shingle",
"min_shingle_size": 2,
"max_shingle_size": 3
}
}
}
}
},
"mappings": {
"properties": {
"title": {
"type": "text",
"fields": {
"trigram": {
"type": "text",
"analyzer": "trigram"
},
"reverse": {
"type": "text",
"analyzer": "reverse"
}
}
}
}
}
}
POST test/_doc?refresh=true
{"title": "noble warriors"}
POST test/_doc?refresh=true
{"title": "nobel prize"}
一旦你设置了分析器和映射,你可以在同一个地方使用 phrase suggester,你可以使用 term suggester :
POST test/_search
{
"suggest": {
"text": "noble prize",
"simple_phrase": {
"phrase": {
"field": "title.trigram",
"size": 1,
"gram_size": 3,
"direct_generator": [ {
"field": "title.trigram",
"suggest_mode": "always"
} ],
"highlight": {
"pre_tag": "<em>",
"post_tag": "</em>"
}
}
}
}
}
回复中包含了最可能先纠正拼写的suggestions。在这种情况下,我们得到了预期的修正“诺贝尔奖”。
{
"_shards": ...
"hits": ...
"timed_out": false,
"took": 3,
"suggest": {
"simple_phrase" : [
{
"text" : "noble prize",
"offset" : 0,
"length" : 11,
"options" : [ {
"text" : "nobel prize",
"highlighted": "<em>nobel</em> prize",
"score" : 0.48614594
}]
}
]
}
}
Basic Phrase suggest API parameters
field
用于对语言模型进行n元语法查找的字段的名称,suggester 将使用此字段获取统计信息以对校正进行评分。此字段是必填字段。
gram_size
在字段中设置 n-gram(shingles)的最大大小。如果字段不包含 n-gram(shingles),则应省略或设置为1.请注意,Elasticsearch 尝试根据指定的字段检测克大小。如果字段使用 shingle 过滤器,gram_size 如果未明确设置设置为 max_shingle_size如果未明确设置。
real_word_error_likelihood
一个词即使在字典中存在也有拼写错误的可能性。默认值是0.95,这意味着5%的真实单词拼写错误。
confidence
置信水平定义了应用于输入短语分数的因子,其被用作其他 suggest 候选的阈值。只有得分高于阈值的候选人才会包括在结果中。例如,1.0的置信水平将仅返回得分高于输入短语的 suggestions 。如果设置为0.0,则返回前N个候选。默认值为1.0。
max_errors
为了形成校正,最多被认为是拼写错误的术语的最大百分比。此方法接受范围[0..1]中的浮点值作为实际查询项的分数或作为查询项的绝对数量的数字> = 1。默认值设置为1.0,对应于只返回最多1个拼写错误项的更正。请注意,将其设置过高可能会对性能产生负面影响。 推荐使用低值,例如1或2,否则 suggestions 调用的时间花费可能超过查询执行的时间花费。
separator
用于分隔 bigram 字段中的术语的分隔符。如果未设置,则使用空格字符作为分隔符
size
为每个查询项生成的候选项的数量。像3或5这样的低数字通常会产生好的结果。提高此值会带来具有更高编辑距离的terms。默认值是5
analyzer
将分析器设置为分析以使用 suggest 文本。 默认为通过字段传递的 suggest 字段的搜索分析器。
shard_size
设置要从每个单独的分片检索的 suggestions 字词的最大数量。 在减少阶段期间,基于size选项只返回前N个 suggestions 。默认为5。
text
设置文本/查询以提供 suggestions。
Highlight
设置 suggestion 高亮显示。如果未提供,则不返回高亮显示的字段。如果提供,必须包含完全pre_tag和post_tag包裹改变的token。如果一行中的多个token被改变,则改变的token的整个短语被包装,而不是每个token。
Collate
根据指定的查询检查每个suggestion,以删除索引中不存在匹配文档的suggestions。
对于 suggestion 的整理查询仅在从中生成 suggestion 的本地碎片上运行。必须指定查询,并将其作为模板查询运行。当前 suggestion 自动提供为 {{suggestion}}} 变量,应在您的查询中使用。 您仍然可以指定自己的模板 params-suggestions 值将添加到您指定的变量。此外,您可以指定一个 prune 以控制是否返回所有短语 suggestions ,设置为 true时,suggestions 将有一个附加选项 collate_match,如果找到匹配的短语文档,则为true,否则为false。prune的默认值为false。
POST _search
{
"suggest": {
"text" : "noble prize",
"simple_phrase" : {
"phrase" : {
"field" : "title.trigram",
"size" : 1,
"direct_generator" : [ {
"field" : "title.trigram",
"suggest_mode" : "always",
"min_word_length" : 1
} ],
"collate": {
"query": { ----------------1
"source" : {
"match": {
"{{field_name}}" : "{{suggestion}}" ------------------2
}
}
},
"params": {"field_name" : "title"}, ------------------3
"prune": true --------------------4
}
}
}
}
}
1: 对于每个suggestion,此查询将运行一次。
2: {{suggestion}} 变量将会被每个 suggestion 文本所代替。
3: 额外的 field_name 变量已经在 params 中被指定,并且被 match 查询所使用。
4: 所有的 suggestions 将和一个额外的 collate_match 选项一起返回,表示是否生成的短语匹配任何文档。
Smoothing Models
短语suggester支持多个平滑模型来平衡不频繁grams (grams (瓦)不存在于索引中)和频繁grams (至少在索引中出现一次)之间的权重。通过将平滑参数设置为以下选项之一,可以选择平滑模型。每个平滑模型都支持可配置的特定属性。
stupid_backoff
简单的回退模型,如果高阶计数为0并且通过常数因子折扣低阶n-gram模型,则回退到低阶n-gram模型。默认折扣为0.4。Stupid Backoff是默认模型。
Laplace
使用添加平滑的平滑模型,其中将常数(通常为1.0或更小)添加到所有计数以平衡权重。默认α为0.5。
linear_interpolation
平滑模型,其基于用户提供的权重(lambdas)获取单字组,双字组和三字母组的加权平均值。线性插值没有任何默认值。必须提供所有参数(trigram_lambda,bigram_lambda,unigram_lambda)。
POST _search
{
"suggest": {
"text" : "obel prize",
"simple_phrase" : {
"phrase" : {
"field" : "title.trigram",
"size" : 1,
"smoothing" : {
"laplace" : {
"alpha" : 0.7
}
}
}
}
}
}
Candidate Generators
短语 suggester 使用候选生成器来产生给定文本中每个术语的可能术语的列表。 单个候选生成器类似于对文本中的每个单独术语调用的术语 suggester 。 生成器的输出随后与来自其他项的候选一起被评分以用于 suggestions 候选。
目前只支持一种类型的候选生成器,direct_generator。 Phrase suggestions API接受在关键 direct_generator 下的生成器列表,列表中的每个生成器在原始文本中被称为每个term。
Direct Generators
直接生成器支持以下参数:
field
从中获取候选 suggestions 的字段。 这是必需的选项,需要设置全局或每个都suggestion
size
每个 suggestion 文本标记返回的最大更正值。
suggest_mode
suggest 模式控制在每个分片上生成的 suggestions 中包括哪些 suggestions 。 除了always之外的所有值都可以被认为是优化以生成更少的 suggestions 以在每个碎片上测试,并且在组合在每个碎片上生成的 suggestions 时不被重新检查。因此,对于不包含它们的分片,即使其他分片包含它们,也会生成对分片的 suggestions 。这些应该使用confidence过滤掉。可以指定三个可能的值:
missing: 只生成不在分片中的terms的suggestions。这是默认值。
popular: 只suggest出现在分片上的文档多于原始terms的terms。
always: 根据suggest文本suggest任何匹配的suggestions
max_edits
最大编辑距离候选suggestions可以具有,以便被视为一个建议。只能是1到2之间的值。任何其他值都会导致抛出错误的请求。默认为2。
prefix_length
候选suggestions必须匹配的最小前缀字符数。默认为1。增加这个数字可以提高拼写检查性能。盟友拼写错误不会出现在terms的开头。(不推荐使用旧名称prefix_len)
min_word_length
suggest 文本术语必须包含的最小长度。 默认值为4.(旧名称“min_word_len”已弃用)
max_inspections
用于乘以 shards_size 以便在分片级别上检查更多候选拼写校正的因子。 可以以性能为代价提高精度。 默认为5。
min_doc_freq
suggestion 应该出现的文档数量的最小阈值。这可以指定为绝对数字或文档数量的相对百分比。 这可以通过仅提示高频项来提高质量。 默认值为0f,未启用。 如果指定的值大于1,则该数字不能为小数。 分片级文档频率用于此选项。
max_term_freq
文本标记可以存在的文档数量中的最大阈值,以便包括。可以是表示文档频率的相对百分比数字(例如0.4)或绝对数字。如果指定的值大于1,则不能指定小数。 默认为0.01f。 这可以用于排除高频术语的拼写检查。 高频项通常拼写正确,这也提高了拼写检查的性能。分片级文档频率用于此选项。
pre_filter
应用于传递到该候选生成器的每个token的过滤器(分析器)。 在生成候选项之前,此过滤器应用于原始token。
post_filter
在它们被传递给实际短语记分器之前应用于每个生成的token的过滤器(分析器)。
下面的示例显示了一个短语suggest call,它有两个生成器:第一个使用一个包含普通索引项的字段,第二个使用一个字段,该字段使用带有反向过滤器的索引项(令牌是按反向顺序索引的)。这是用来克服直接生成器需要一个常量前缀来提供高性能建议的限制。pre_filter和post_filter选项接受普通的分析器名称。
POST _search
{
"suggest": {
"text" : "obel prize",
"simple_phrase" : {
"phrase" : {
"field" : "title.trigram",
"size" : 1,
"direct_generator" : [ {
"field" : "title.trigram",
"suggest_mode" : "always"
}, {
"field" : "title.reverse",
"suggest_mode" : "always",
"pre_filter" : "reverse",
"post_filter" : "reverse"
} ]
}
}
}
}
pre_filter 和 post_filter 也可以用于在生成候选项之后注入同义词。 例如,对于查询 caption usq,我们可以为项usq生成候选 usa,这是 america 的同义词,其允许如果该短语得分足够高则向用户呈现 captain america。