Elasticsearch REST APIs-Search APIs

 

核心search

Search 

GET /<target>/_search

GET /_search

POST /<target>/_search

POST /_search

 

path参数:  

<target>(Optional, string) 逗号分割的 data streams, indices, 和aliases. 支持wildcards (*). 也可以search所有data streams 和 indices,使用 * 或 _all.

 

query参数（如果同时存在query参数和body参数，则使用body参数）：

allow_no_indices(Optional, Boolean) 是否允许匹配不到index，如果false则匹配不到时失败，例如target是foo*,bar*，实际存在foo开头的index但没有bar开头的就会失败，默认true.

allow_partial_search_results(Optional, Boolean) 如果为true，则在存在shard请求超时或shard失败时返回部分结果。如果为false，则返回没有部分结果的错误。默认为true。如果要覆盖默认值，可以对cluster setting设置search.default_allow_partial_results为false。

analyzer(Optional, string) query string的分词器.只在 q 参数指定时起作用。

analyze_wildcard(Optional, Boolean) If true, wildcard and prefix queries are analyzed. Defaults to false.只能在 q 参数指定时使用.

batched_reduce_size(Optional, integer) 在coordinating节点上应该reduced shard结果数量. 可以用于在shard数量很多的情况下防止内存开销过大. 默认512.

ccs_minimize_roundtrips(Optional, Boolean)如果为true，则在执行跨集群搜索（CCS）请求时，协调节点和远程集群之间的网络往返将最小化。默认为true.

default_operator(Optional, string) 默认的 query string: AND 或 OR. 默认 OR.只能在 q 参数指定时使用.

df(Optional, string) Field to use as default where no field prefix is given in the query string.只能在 q 参数指定时使用.

docvalue_fields(Optional, string) 逗号分割的需要返回的字段集.

expand_wildcards(Optional, string) 可以被通配符匹配的索引，逗号分割，默认open，可选值:

all

Match any data stream or index, including hidden ones.

open

Match open, non-hidden indices. Also matches any non-hidden data stream.

closed

Match closed, non-hidden indices. Also matches any non-hidden data stream. Data streams cannot be closed.

hidden

Match hidden data streams and hidden indices. Must be combined with open, closed, or both.

none

Wildcard patterns are not accepted.

explain(Optional, Boolean) 如果为true，则返回有关分数计算的详细信息。默认为false.

from(Optional, integer) 文档的offset. 默认 0.默认情况下，分页获取不能超过10000条，如果需要可以使用参数 search_after 。

ignore_throttled(Optional, Boolean) 如果 true, 将忽略 frozen 的索引. 默认 true.

ignore_unavailable(Optional, Boolean) 如果 true, missing 或 closed 索引将不会在返回中. 默认 false.

lenient(Optional, Boolean) 错误容忍，如果true,忽略query的格式错误（比如给数字类型使用text） .默认false.只能在 q 参数指定时使用.

max_concurrent_shard_requests(Optional, integer) 在每个node上可并发请求的shard数量，默认5.

pre_filter_shard_size(Optional, integer) 定义一个阈值，如果搜索请求扩展到的碎片数超过阈值，则该阈值将基于查询重写强制预筛选搜索碎片的预筛选往返。例如，如果一个分片无法根据其重写方法匹配任何文档，即如果日期筛选器必须匹配，但分片边界和查询不相交，则此筛选器往返可以显著限制分片的数量。未指定时，如果满足以下任何条件，则执行预过滤阶段:

• The request targets more than 128 shards.
• The request targets one or more read-only index.
• The primary sort of the query targets an indexed field.

preference(Optional, string) 用于搜索的node和shard，支持以下参数：

　　_only_local　　只在本node节点上的shards中执行search.

　　_local　　优先使用_only_local，不行再使用默认方法.

　　_only_nodes:<node-id>,<node-id>　　只在指定的node节点IDs上的shards中执行search.

　　_prefer_nodes:<node-id>,<node-id>　　优先使用指定的nodes IDs. 不行再使用默认方法.

　　_shards:<shard>,<shard>　　只在指定的shards中执行search，可以和其他preference参数组合使用。例如: _shards:2,3|_local.

　　<custom-string>　　Any string that does not start with _. If the cluster state and selected shards do not change, searches using the same <custom-string> value are routed to the same shards in the same order.

q(Optional, string) Query in the Lucene query string syntax.

request_cache(Optional, Boolean) If true, the caching of search results is enabled for requests where size is 0. See Shard request cache settings. Defaults to index level settings.

rest_total_hits_as_int(Optional, Boolean) 将hits.total呈现为integer 还是 object 。默认为false。

routing(Optional, string) shard路由参数.

scroll(Optional, time value) scrolling在 search context 的保留时间，见 Scroll search results.默认该值不能超过1d（24h），可以在集群级别修改 search.max_keep_alive 。

search_type(Optional, string) ：

　　query_then_fetch(Default) Distributed term frequencies are calculated locally for each shard running the search. We recommend this option for faster searches with potentially less accurate scoring.

　　dfs_query_then_fetch

Distributed term frequencies are calculated globally, using information gathered from all shards running the search. While this option increases the accuracy of scoring, it adds a round-trip to each shard, which can result in slower searches.

seq_no_primary_term(Optional, Boolean) 如果true, 在每个hit中返回最后的primary term.

size(Optional, integer)分页大小，默认10.默认情况下，分页获取不能超过10000条，如果需要可以使用参数 search_after 。

sort(Optional, string) 逗号分割的 <field>:<direction> pairs.

_source(Optional) 哪些source fields 需要返回. 默认 true.可选值：

　　true(Boolean) 返回整个source.

　　false(Boolean) 不返回source.

　　<string>(string) 逗号分割的字段集，允许使用 Wildcard (*).

_source_excludes(可选, string) 响应中在_source排除哪些字段，逗号分割.当_source 是false时不起作用。

_source_includes(可选, string) 跟_source_excludes相反。

stats(Optional, string) Specific tag of the request for logging and statistical purposes.

stored_fields(Optional, string) 逗号分割的字段集.当指定该参数时， _source 参数默认为false，可以指定 _source: true 两者都返回。

suggest_field(Optional, string) 指定哪个字段用于 suggestions.

suggest_mode(Optional, string)指定suggest mode. 默认 missing.该参数只能在 suggest_field 和suggest_text 指定时使用，可选参数：

• always
• missing
• popular

suggest_size(Optional, integer) Number of suggestions to return..该参数只能在 suggest_field 和suggest_text 指定时使用

suggest_text(Optional, string) The source text for which the suggestions should be returned.该参数只能在 suggest_field  指定时使用

terminate_after(Optional, integer) 每个shard允许搜集的最大文档数量，当到达最大数量时提前结束query.默认0表示不提前终止。

timeout(Optional, time units) 指定没有shard的超时时间，默认不超时。

track_scores(Optional, Boolean) If true, calculate and return document scores, even if the scores are not used for sorting. Defaults to false.

track_total_hits(Optional, integer or Boolean) Number of hits matching the query to count accurately. Defaults to 10000.If true, the exact number of hits is returned at the cost of some performance. If false, the response does not include the total number of hits matching the query.

typed_keys(Optional, Boolean) If true, aggregation and suggester names are be prefixed by their respective types in the response. Defaults to true.version(Optional, Boolean) If true, returns document version as part of a hit. Defaults to false.


version(Optional, Boolean) 如果 true, 返回的文档包含version. 默认 false。

 

request body：

docvalue_fields(Optional, array of strings and objects) 在 hits.fields 返回的字段.

　　field(Required, string) 字段名称通配符. 

　　format(Optional, string) value的格式化，对日期可以指定 date format，数字可以指定 DecimalFormat，其他类型的字段该参数不支持。

fields(Optional, array of strings and objects) 在 hits.fields 返回的字段.

　　field(Required, string) 字段名称通配符. 

　　format(Optional, string) value的格式化，只支持date 和 geospatial。

explain(Optional, Boolean) 同query参数.

from(Optional, integer) 同query参数.

indices_boost(Optional, array of objects) Boosts the _score of documents from specified indices.

　　<index>: <boost-value>(Required, float) <index> is the name of the index or index alias. Wildcard (*) expressions are supported.<boost-value> is the factor by which scores are multiplied.A boost value greater than 1.0 increases the score. A boost value between 0 and 1.0 decreases the score.

min_score(Optional, float) 排除_score 小于该值的文档.

pit(Optional, object) Limits the search to a point in time (PIT). If you provide a pit, you cannot specify a <target> in the request path.

　　id(Required*, string) ID for the PIT to search. If you provide a pit object, this parameter is required.

　　keep_alive(Optional, time value) Period of time used to extend the life of the PIT.

query(Optional, query object) Defines the search definition using the Query DSL.查询语法块。

runtime_mappings(Optional, object of objects) Defines one or more runtime fields in the search request. These fields take precedence over mapped fields with the same name.

seq_no_primary_term(Optional, Boolean) 同query参数。

size(Optional, integer) 同query参数。

_source(Optional) Indicates which source fields are returned for matching documents. These fields are returned in the hits._source property of the search response. Defaults to true.

　　true(Boolean) The entire document source is returned.

　　false(Boolean) The document source is not returned.

　　<wildcard_pattern>(string or array of strings) Wildcard (*) pattern or array of patterns containing source fields to return.

　　<object>(object) Object containing a list of source fields to include or exclude.

stats(Optional, array of strings) 同query参数。

terminate_after(Optional, integer) 同query参数。

timeout(Optional, time units) 同query参数。

version(Optional, Boolean) 同query参数。

 

response body:

_scroll_id(string) 该参数可以使用 scroll API ，该参数只在search时指定了scroll参数有返回。

took(integer)耗时ms。这个时间值是coordinating节点收到请求和准备响应的时间差，耗时包括coordinating和data节点的通讯、线程池执行search的时间（包括queued等待时间）、真实执行时间；不包括请求发送到ES的时间、响应转换JSON的时间、响应到客户端的时间。

timed_out(Boolean) 如果true, 表示超时，响应可能是空的或一部分.

_shards(object) ：

　　total(integer) 总的shards数量.

　　successful(integer) 成功的shards数量.

　　failed(integer) 失败的shards数量.

　　未分配的碎片将被视为既不成功也不失败。因此，失败+成功少于总数表示未分配部分碎片。

hits(object):

　　total(object) :

　　　　value(integer) 返回的文档数量.

　　　　relation(string) Indicates whether the number of returned documents in the value parameter is accurate or a lower bound. eq 、 gte

max_score(float) 返回文档中的最高分.

hits(array of objects) ：

　　_index(string) index名称.

　　_type过时.

　　_id(string) 文档ID.

　　_score(float) 得分.

　　_source(object) 文档source.

　　fields(object) 返回的文档字段，这些字段必须在以下参数中指定:

• 　　docvalue_fields
• script_fields
• stored_fields

　　　　<field>(array) Key is the field name. Value is the value for the field.