1. 前言
全文查询(Full text queries)能够搜索已分析的text字段,如电子邮件的正文。全文查询支持以下方式的查询:
- 匹配(match)查询
- 匹配布尔前缀(match_bool_prefix)查询
- 匹配短语(match_phrase)查询
- 匹配短语前缀(match_phrase_prefix)查询
- 多值匹配(multi_match)查询
- 查询字符串(query_string)查询
- 简单查询字符串(simple_query_string)查询
- 间隔(intervals)查询
2. 匹配查询
匹配(match)查询返回与字段匹配的文档,支持字段类型包括文本、数字、日期或布尔值,对于文本值,在匹配之前对所提供的文本需进行分析。简单示例如下:
PUT /my_index_01
{
"mappings": {
"properties": {
"content": {
"type": "text",
"store": true
},
"create_date": { "type": "date" },
"id": { "type": "keyword" },
"user": {
"properties": {
"name": { "type": "keyword" },
"age": { "type": "integer" }
}
},
"status": { "type": "keyword" }
}
}
}
POST /my_index_01/_doc/1
{"id":"00000001", "content":"Quick Brown Fox", "create_date": "2015-01-01", "user.name":"james jordan", "user.age": 35, "status": "enable" }
POST /my_index_01/_doc/2
{"id":"00000002", "content":"Quick White Fox", "create_date": "2015-01-02", "user.name":"fake li", "user.age": 26, "status": "disable" }
POST /my_index_01/_doc/3
{"id":"00000003", "content":"New York city", "create_date": "2015-01-03", "user.name":"mike li", "user.age": 39, "status": "disable" }
POST my_index_01/_search
{"query":{"match":{"content":{"query":"Quick Brown Fox"}}}}
顶级参数
- <field>
(必需的,object类型)所需查询字段
<field>子级参数
- query
(必需的)在提供的<field>中查找的文本、数字、布尔值或日期。
match查询在执行搜索之前分析所提供的任何文本。这意味着match查询可以在text字段中搜索已分析的分词,而不是精确的词条。 - analyzer
(可选的,string类型)分析器用于将查询值中的文本转换为分词。默认情况下,使用索引时的分析器(analyzer)。 - auto_generate_synonyms_phrase_query
(可选的,boolean类型)如果为true,将自动为多词条同义词创建匹配短语查询。默认值为true。 - fuzziness
(可选的,string类型)模糊性表示允许匹配的最大编辑距离。参数值包括:
(1)0,1,2:允许最大的编辑距离。
(2)AUTO:根据词条的长度生成一个编辑距离。低和高距离参数可通过形式AUTO:[low],[high]修改。如果没有指定,默认值是3和6,相当于AUTO:3,6。其中0..2字符必须完全匹配,3..5字符允许一个编辑,大于5的字符允许两个编辑。 - fuzzy_transpositions
(可选的,boolean类型)如果为true,用于模糊匹配的编辑包括两个相邻字符的换位(ab→ba)。默认值为true。 - max_expansions
(可选的,integer类型)查询将扩展到的最大词条数。默认值为50。 - prefix_length
(可选的,integer类型)为模糊匹配而保持不变的起始字符数。默认值为0。 - fuzzy_rewrite
(可选的,string类型)用于重写查询。如果fuzziness参数不是0,则匹配查询默认使用top_terms_blended_freqs_${max_expansions}的fuzzy_rewrite方法。 - lenient
(可选的,boolean类型)如果为true,则忽略输入值格式的错误,比如为数值字段提供文本查询值。默认值为false。 - operator
(可选的,string类型)用于解释查询值中文本的布尔逻辑。
(1)OR(默认):查询的文本值经过分析器分析后需匹配一个即可。
(2)AND:查询的文本值经过分析器分析后需匹配全部。 - minimum_should_match
(可选的,string类型)文档中子句必须匹配的最小数目。 - zero_terms_query
(可选的,string类型)表示如果分析器删除所有分词,是否不返回文档。
(1)none(默认):如果分析器删除所有分词,则不会返回文档。
(2)all:如果分析器删除所有分词,返回所有文档。
使用例子
查询文本值“Brown Fox”,字段经过分析器分析后的分词(Brown和Fox),在文档字段值上必须全部匹配,示例如下:
POST my_index_01/_search
{"query":{"match":{"content":{"query":"Brown Fox","operator":"and"}}}}
查询文本值“Foaax”,模糊匹配查询,允许2个编辑距离,可以匹配到“Fox”,示例如下:
POST my_index_01/_search
{"query":{"match":{"content":{"query":"Foaax","fuzziness":"2"}}}}
定义停止词过滤器“my_stop_words_filter”, 将zero_terms_query设置为all,match查询停用词,预期返回所有文档,示例如下:
PUT /my_index_02
{
"settings": {
"analysis": {
"analyzer": {
"default": {
"tokenizer": "whitespace",
"filter": [ "my_stop_words_filter" ]
}
},
"filter": {
"my_stop_words_filter": {
"type": "stop",
"ignore_case": true
}
}
}
},
"mappings": {
"properties": {
"content": {
"type": "text"
},
"create_date": { "type": "date" },
"id": { "type": "keyword" },
"user": {
"properties": {
"name": { "type": "keyword" },
"age": { "type": "integer" }
}
},
"status": { "type": "keyword" }
}
}
}
POST /my_index_02/_doc/1
{"id":"00000001", "content":"Quick Brown Fox", "create_date": "2015-01-01", "user.name":"james jordan", "user.age": 35, "status": "enable" }
#预期返回所有文档
POST my_index_02/_search
{
"query": {
"match": {
"content": {
"query": "a an",
"operator": "and",
"zero_terms_query": "all"
}
}
}
}
3. 匹配布尔前缀查询
匹配布尔前缀(match_bool_prefix)查询会首先分析输入的文本值,然后将分词后词条构造一个bool查询,除了最后一个词条外,每个词条都在term查询中使用,最后一个词条用于前缀查询。示例如下:
POST my_index_01/_search
{
"query": {
"match_bool_prefix" : {
"content" : "Quick Brow"
}
}
}
匹配文档字段content中包含“Quick”或前缀为“Brow”的文档,返回结果片段:
支持参数
- match_bool_prefix支持minimum_should_match、operator参数。
- fuzziness、prefix_length、max_expansions、fuzzy_transpositions和fuzzy_rewrite参数可以应用于term构造的term子查询,但不包括最后一个term,它们对为最后一个term构造的前缀查询没有任何影响。
4. 匹配短语查询
匹配短语(match_phrase)查询分析文本并且从分析的文本中创建一个短语查询。
匹配短语查询,在content字段中查询文本“White Fox”,不会拆分“White Fox”,如果文档中content字段包含“White Fox”,那么此文档匹配成功返回,示例如下:
POST my_index_01/_search
{"query":{"match_phrase":{"content":"White Fox"}}}
返回结果片段如下:
支持参数
- 匹配短语查询支持slop、analyzer、query参数。示例如下:
POST my_index_01/_search
{"query":{"match_phrase":{"content":{"query":"White Fox","slop":2}}}}
5. 匹配短语前缀查询
匹配短语前缀(match_phrase_prefix)查询返回包含所输入文本中单词的文档,其顺序与所输入的相同,所输入的文本的最后一个词被视为前缀,并且返回的文档必须包含与该词开头的匹配的词条。
POST my_index_01/_search
{
"query": {
"match_phrase_prefix": {
"content": { "query": "Quick Brown Fo" }
}
}
}
返回结果片段如下:
支持参数
- 匹配短语查询支持slop、analyzer、query、max_expansions、zero_terms_query参数。例如,指定分析器“standard”查询,示例如下:
POST my_index_01/_search
{
"query": {
"match_phrase_prefix": {
"content": {
"query": "Quick Brown Fo",
"analyzer": "standard"
}
}
}
}
6. 多值匹配查询
多值匹配(multi_match)查询建立在匹配(match)查询之上,允许多字段查询。
例如,在字段“content”或“user.name”上,查询文本“White Fox”,示例如下:
POST my_index_01/_search
{
"query": {
"multi_match" : {
"query": "White Fox",
"fields": [ "content", "user.name" ]
}
}
}
fields支持通配符查询。例如,在后缀为name的所有字段中查询,示例如下:
POST my_index_01/_search
{
"query": {
"multi_match" : {
"query": "fake li",
"fields": [ "content", "*name" ]
}
}
}
fields支持通过插入符号(^) 来提升单个字段。例如,content字段的相关性比字段user.name重要3倍,示例如下:
POST my_index_01/_search
{
"query": {
"multi_match" : {
"query": "fake li",
"fields": [ "content^3", "user.name" ]
}
}
}
type参数
multi_match查询内部执行的方式取决于类型参数,其类型参数值包括:
- best_fields:(默认)查找匹配任何字段的文档,但使用来自最佳字段的_score。
- most_fields:查找匹配任何字段的文档,并合并每个字段的_score。
- cross_fields:用同一个分析器(analyzer)处理字段,类似这些字段是一个大字段。
- phrase:在每个字段上运行match_phrase查询,并使用来自最佳字段的_score。
- phrase_prefix:在每个字段上运行match_phrase_prefix查询,并使用来自最佳字段的_score。
- bool_prefix:在每个字段上创建一个match_bool_prefix查询,并组合每个字段的_score。
使用示例
首先创建索引my_index_03并且索引数据,示例如下:
POST /my_index_03/_doc/1
{"message":"Brown", "content":"Quick Brown Fox" }
POST /my_index_03/_doc/2
{"message":"White", "content":"Quick White Fox" }
most_fields使用示例如下:
POST my_index_03/_search
{
"query": {
"multi_match": {
"query": "brown fox",
"type": "most_fields",
"fields": [ "content", "message" ],
"tie_breaker": 0.3,
"operator": "and"
}
}
}
phrase_prefix使用示例如下:
POST my_index_03/_search
{
"query": {
"multi_match": {
"query": "Quick White F",
"type": "phrase_prefix",
"fields": [
"content",
"message"
]
}
}
}
类似于
POST my_index_03/_search
{
"query": {
"dis_max": {
"queries": [
{ "match_phrase_prefix": { "content": "Quick White F" }},
{ "match_phrase_prefix": { "message": "Quick White F" }}
]
}
}
}
7. 查询字符串查询
查询字符串(query_string)查询根据操作符(如AND或NOT)来解析和分割所提供的查询字符串,然后独立分析每个分割文本,最后返回匹配的文档,query_string查询严格按照查询语法,如果查询字符串包含任何无效语法,则返回错误。
例如,在my_index_03索引content字段上,查询“Brown”或“Quick White”文本值,示例如下:
GET my_index_03/_search
{
"query": {
"query_string": {
"query": "(Brown) OR (Quick White)",
"default_field": "content"
}
}
}
支持参数
- query:(必需的,string)用于搜索的查询字符串。参见查询字符串语法。
- default_field:(可选的,string)如果查询字符串中没有提供字段,则使用该字段设置搜索的默认字段。默认值为index.query.default_field索引设置,其默认值为*,表示提取所有符合条件的词条查询字段,并过滤元数据字段。如果没有指定前缀,则将所有字段组合起来构建查询。一次可以查询的字段数量是有限制的,它由indices.query.bool.max_clause_count搜索设置,默认值为1024。
- allow_leading_wildcard:(可选的,boolean)如果为true,通配符*和?允许作为查询字符串的第一个字符。默认值为true。
- analyze_wildcard:(可选的,boolean)如果为true,查询将尝试分析查询字符串中的通配符词条。默认值为false。
- analyzer:(可选的,string)分析器用于将查询值中的文本转换为分词。默认情况下,使用索引时的分析器(analyzer)。
- auto_generate_synonyms_phrase_query:(可选的,boolean类型)如果为true,将自动为多词条同义词创建匹配短语查询。默认值为true。
- boost:(可选的,float)用于减少或增加查询的相关性分数,默认为1.0。
- default_operator:(可选的,string)如果没有指定操作符,默认布尔逻辑,用于解释查询字符串中的文本,有效值包含:
(1)OR (默认)
(2)AND - enable_position_increments:(可选的,boolean)如果为true,表示在query_string搜索构造的查询中启用位置增量。默认值为true。
- fields:(可选的,string数组)需要搜索的字段数组。可以使用此参数查询跨多个字段进行搜索。参见多字段查询。
- fuzziness:(可选的,string)允许匹配的最大编辑距离。
- fuzzy_max_expansions:(可选的,integer)用于在查询扩展时,模糊匹配的最大词条数。默认值为50。
- fuzzy_prefix_length:(可选的,integer)为模糊匹配而保持不变的起始字符数。默认值为0。
- fuzzy_transpositions:(可选的,boolean)如果为true,用于模糊匹配的编辑,两个相邻字符的换位(ab→ba)是模糊匹配的。默认值为true。
- lenient:(可选的,boolean)如果为true,则忽略输入值格式的错误,比如为数值字段提供文本值。默认值为false。
- max_determinized_states:(可选的,integer)查询所需的自动机状态的最大数目。默认是10000。Elasticsearch内部使用Apache Lucene来解析正则表达式。Lucene将每个正则表达式转换为一个有限自动机。
- minimum_should_match:(可选的,string)文档中子句必须匹配的最小数目。
- quote_analyzer:(可选的,string)分析器,用于将查询字符串中的引用文本转换为分词。默认为为default_field映射的search_quote_analyzer分析器,对于带引号的文本,此参数覆盖分析器参数中指定的分析器。
- phrase_slop:(可选的,integer)短语匹配分词之间允许的最大位置数。默认值为0,表示默认情况下需要精确的短语匹配。
- quote_field_suffix:(可选的,string)附加到查询字符串中引用文本的后缀。
- rewrite:(可选的,string)用于重写查询的方法。
- time_zone:(可选的,string)时区,用于将查询字符串中的日期值转换为世界调整时间(UTC)。
查询字符串查询语法
指定字段
- 字段content包含值White
content:White
- 字段content包含值White或Quick
(White or Quick)
- 字段content有任何非空值
_exists_:content
- 字段book.title、book.content或book.date包含Quick或Brown(注意需要用反斜杠转义保留字符*)
book.\*:(Quick OR Brown)
通配符查询
通配符搜索可以在单个词条上运行,使用?替换单个字符,*替换零个或多个字符:
Qu?ck Bro*
正则表达式查询
正则表达式模式可以嵌入到查询字符串中,使用前斜杠中("/")包装:
content:/Qu.c[ki]/
模糊查询
使用模糊操作符进行模糊查询,默认编辑距离是2:
Quikc~
可修改编辑距离来控制拼写错误范围,如下修改编辑距离为1:
Quikc~1
范围查询
可以为日期、数字或字符串字段指定范围。包含范围用方括号[min TO max]指定,排除范围用大括号{min TO max}指定。
- 2012年所有日期
date:[2012-01-01 TO 2012-12-31]
- 2012年之前
date:{* TO 2012-01-01}
- 字段count大于包括10以上
count:[10 TO *]
- 字段count大于等于1,小于5范围内
count:[1 TO 5}
- 可使用下列语法:
age:>10
age:>=10
age:<10
age:<=10
提升
使用boost操作符^使一个词条比另一个词条更相关。
- 例如,如果我们想找到关于狐狸的所有文档,但我们特别对敏捷的狐狸感兴趣。
Quick^2 Fox
- boost默认值是1,可以是任何正的浮点数。boost如果是0到1之间的值表示降低了相关性:
Quick^0.1 Fox
- boost也可用于短语或分组:
(Quick Fox)^4
布尔操作符
默认情况下,只要有一个词条匹配,整个文档匹配。不过可以通过布尔操作符来更细粒度的控制。
首选操作符是+(该词条必须存在)和-(该词条必须不存在),其他词条可选的,例如,查询Fox必须存在、White必须不存在,示例如下:
Quick +Fox -White
组合
多个词条或子句可以用括号组合在一起,形成子查询:
message:(Brown OR Fox) content:(White Fox)^2
保留字符
如果需要在查询中使用作为操作符的字符(而不是作为操作符),那么应该使用前导反斜杠“\”对它们进行转义。例如,要搜索(1+1)=2
,需要将查询编写为\(1\+1\)\=2
,当为请求体使用JSON时,需要两个前面的反斜杠(\\
)。
搜索多个字段
可以使用fields参数在多个字段之间执行query_string搜索(用法参考多值匹配查询)。
8. 简单查询字符串查询
简单查询字符串(simple_query_string)查询使用具有有限但容错语法的解析器,根据提供的查询字符串返回匹配文档。
它的语法比query_string查询简单,但是simple_query_string查询不会返回无效语法的错误。相反,它忽略查询字符串中任何无效的部分。
示例如下:
GET my_index_03/_search
{
"query": {
"simple_query_string" : {
"query": "\"Quick \" +(White | Brown) -Gray",
"fields": ["message^5", "content"],
"default_operator": "and"
}
}
}
简单查询字符串语法
simple_query_string支持下列操作符:
- +表示AND操作
- |表示OR操作
- -不包含单个词条
- "封装了许多分词来表示要搜索的短语
- *在一个词的末尾表示一个前缀查询
- (左括号和)右括号表示优先级
- 一个字后面的~N表示编辑距离(模糊度)
- 一个短语后面的~N表示slop数量
- 保留字符原义,在字符前面使用反斜杠()对其进行转义
9. 间隔查询
根据匹配词条的顺序和接近度返回文档。间隔(intervals)查询使用一系列定义组成的匹配规则,将这些规则应用于来自指定字段的词条。
简单示例如下:
POST my_index_03/_search
{
"query": {
"intervals" : {
"content" : {
"all_of" : {
"ordered" : true,
"intervals" : [
{
"match" : {
"query" : "Quick Brown Fox",
"max_gaps" : 0,
"ordered" : true
}
}
]
}
}
}
}
}
intervals顶级参数
- <field>
(必需的,规则object类型)所需查询字段,该参数的值是一个规则对象,基于匹配词条、顺序和邻近度来匹配文档。有效规则包括:
(1)match
(2)prefix
(3)wildcard
(4)fuzzy
(5)all_of
(6)any_of
match规则参数
匹配(match)规则匹配分析的文本。
- query:(必需的,string)表示在提供的<field>字段中需要查找的文本。
- max_gaps:(可选的,integer)匹配项之间的最大位置数。距离大于此值的词条表示不匹配。默认为1,如果未指定或设置为-1,则对匹配没有宽度限制,如果设置为0,则两个词条必须相邻出现。
- ordered:(可选的,boolean)如果为true,则匹配的词条必须按照指定的顺序出现。默认值为false。
- analyzer:(可选的,string)分析器,用于分析查询中的词条。默认为顶级<field>字段的分析器。
- filter:(可选的,间隔过滤器规则对象)一个可选的间隔过滤器。
- use_field:(可选的,string)如果指定该参数值,则匹配此字段的间隔,而不是顶级<field>,使用来自该字段的搜索分析器分析词条。
prefix规则参数
前缀(prefix)规则用来匹配以指定的一组字符开头的词条,这个前缀可以扩展到最多匹配128个词条,如果前缀匹配超过128词条,Elasticsearch将返回一个错误,可以在字段映射中使用index-prefixes选项来修改此限制。
- prefix:(必需的,string)在顶级<field>中找到的术语的开始字符。
- analyzer:(可选的,string)分析器用于规范化前缀。默认为顶级<field>的分析器。
- use_field:(可选的,string)如果指定该参数值,则匹配此字段的间隔,而不是顶级<field>。
wildcard规则参数
通配符(wildcard)规则使用通配符模式匹配词条。此模式可以扩展到最多匹配128项,如果模式匹配超过128项,Elasticsearch将返回一个错误。
- pattern:(必需的,string)通配符模式用于查找匹配的词条,该参数支持两个通配符操作符:
(1)?
匹配任何单个字符。
(2)*
匹配零个或多个字符,包括一个空字符。
避免以*或?开头的模式,因为可能增加查找匹配项所需的迭代,并降低搜索性能。 - analyzer:(可选的,string)分析器用于规范化模式。默认为顶级<field>的分析器。
- use_field:(可选的,string)如果指定该参数值,则匹配此字段的间隔,而不是顶级<field>。
fuzzy规则参数
模糊(fuzzy)规则在由模糊性定义的编辑距离内匹配与所提供的词条相似的词条。如果模糊展开匹配的项超过128项,Elasticsearch将返回一个错误。
- term:(必需的,string)要匹配的术语。
- prefix_length:(可选的,string)在创建扩展时保持不变的开始字符数。默认值为0。
- transpositions:(可选的,boolean)表示编辑是否包含两个相邻字符的换位(ab→ba),默认值为true。
- fuzziness:(可选的,string)允许匹配的最大编辑距离。默认为AUTO。
- analyzer:(可选的,string)分析器用于规范化词条。默认为顶级<field>的分析器。
- use_field:(可选的,string)如果指定该参数值,则匹配此字段的间隔,而不是顶级<field>。
all_of规则参数
all_of规则返回跨其他规则组合的匹配项。
- intervals:(必需的,规则object的数组)需要组合的规则数组。所有规则必须在文档中匹配。
- max_gaps:(可选的,integer)匹配项之间的最大位置数。距离大于此值的词条表示不匹配。默认为1,如果未指定或设置为-1,则对匹配没有宽度限制,如果设置为0,则两个词条必须相邻出现。
- ordered:(可选的,boolean)如果为true,则匹配的词条必须按照指定的顺序出现。默认值为false。
- filter:(可选的,filter规则object)用于过滤返回间隔(intervals)的规则。
any_of规则参数
any_of规则返回其任一个子规则生成的intervals。
- intervals:(必需的,规则object数组)需要匹配的规则数组。
- filter:(可选的,filter规则object)用于过滤返回间隔(intervals)的规则。
filter规则参数
过滤(filter)规则基于查询返回间隔(intervals)。
- after:(可选的,查询对象)查询用于返回过滤器规则中间隔之后的间隔。
- before:(可选的,查询对象)查询用于返回过滤器规则中间隔之前发生的间隔。
- contained_by:(可选的,查询对象)查询用于返回过滤器规则中间隔所包含的间隔。
- containing:(可选的,查询对象)查询用于返回包含过滤器规则中的间隔的间隔。
- not_contained_by:(可选的,查询对象)查询用于返回过滤器规则中间隔不包含的间隔。
- not_containing:(可选的,查询对象)查询用于返回不包含过滤器规则间隔的间隔。
- not_overlapping:(可选的,查询对象)查询用于返回与过滤器规则中的间隔不重叠的间隔。
- overlapping:(可选的,查询对象)查询用于返回与过滤器规则中的间隔重叠的间隔。
- script:(可选的,脚本对象)用于返回匹配文档的脚本。这个脚本必须返回一个布尔值(true或false)。
使用示例
示例1
下面的intervals查询中包含一个match规则,规则定义了查询文本为“Quick Fox”, 单词Quick
和Fox
之间的位置最大不超过10,match规则里包含一个filter规则,用来排除字段含有单词“Brown”的文档,具体如下:
POST my_index_03/_search
{
"query": {
"intervals" : {
"content" : {
"match" : {
"query" : "Quick Fox",
"max_gaps" : 10,
"filter" : {
"not_containing" : {
"match" : {
"query" : "Brown"
}
}
}
}
}
}
}
}
返回结果片段如下:
"hits" : [
{
"_index" : "my_index_03",
"_type" : "_doc",
"_id" : "2",
"_score" : 0.3333333,
"_source" : {
"message" : "White",
"content" : "Quick White Fox"
}
}
]
示例2
下面的intervals查询中包含一个match规则,match规则里包含一个filter规则,filter规则使用脚本来定义规则(根据间隔的开始位置、结束位置和内部间隔计数来筛选间隔),具体如下:
POST my_index_03/_search
{
"query": {
"intervals" : {
"content" : {
"match" : {
"query" : "Brown Fox",
"filter" : {
"script" : {
"source" : "interval.start > 0 && interval.end < 100 && interval.gaps == 0"
}
}
}
}
}
}
}
示例3
下面的intervals查询中包含一个match规则,规则定义了查询文本为“Fox”,match规则里包含一个filter规则,filter规则使用contained_by参数定义了只查询“Brown Fox”的短语匹配,用其来过滤间隔,具体如下:
POST my_index_03/_search
{
"query": {
"intervals": {
"content": {
"match": {
"query": "Fox",
"filter": {
"contained_by": {
"match": {
"query": "Brown Fox"
}
}
}
}
}
}
}
}
示例4
下面的intervals查询中包含子intervals,子intervals中包含两个match规则,具体如下:
POST my_index_03/_search
{
"query": {
"intervals" : {
"content" : {
"any_of" : {
"intervals" : [
{ "match" : {
"query" : "Brown Fox",
"ordered" : true,
"max_gaps" : 0 } },
{ "match" : {
"query" : "White Fox",
"ordered" : true,
"max_gaps" : 0 } }
]
}
}
}
}
}