ElasticSearch的REST APIs - 搜索API - 搜索

ElasticSearch的REST APIs - 搜索API - 搜索

基于 ES 7.7 官方文档

搜索 (Search API)

返回与请求中定义的查询匹配的搜索结果(hits)。可以使用查询字符串参数q或 request body 提供搜索查询。

GET|POST //_search

GET|POST /_search

路径参数 (Path parameters)

  (可选, string)   支持英文逗号分割的索引名称的列表或通配符表达式.

请求参数 (Query parameters)

此api中有几个选项可以通过 请求参数 或 request body 参数指定， 前者优先级最高（如果二者中同时指定了该选项，则只使用请求参数）。

allow_no_indices

  (可选, bool)   默认true。如果设置为true, 则当全部使用通配符*、_all只检索不存在(missing)或者已关闭(closed)的索引(或索引别名)时，不会抛出错误；否则，只要有一个匹配的索引不存在时就会抛出错误。

allow_partial_search_results

  (可选, bool)   如果为true, 则当请求超时或分片失效时会返回部分已获取的数据, 否则只返回错误(而不会包含任何已获取的数据)。默认true。

  要覆盖该字段的默认值，可以把集群配置search.default_allow_partial_results设置为false。

analyzer

  (可选, string)   用于查询的分析器。 该参数仅与查询参数q一起使用。

analyze_wildcard

  (可选, bool)   如果为true，则通配符和前缀查询(prefix query) 会被分析(analyzed)。默认false。 该参数仅与查询参数q一起使用。

batched_reduce_size

  (可选, integer) 此参数用来限制协调节点（coordinating node，也就是接受请求的节点）一次（批）处理的分片数量，如果命中的分片数量大于此参数值，则会分批执行，默认值为512。如果请求中潜在的分片数量很大，则应将此值用作保护机制，以减少每个搜索请求的内存开销。

ccs_minimize_roundtrips

  (可选, bool)   如果为true，在执行跨集群搜索(CCS)请求时，协调节点与远程集群之间的网络往返最小。默认true。

这是ES 7.0为跨集群搜索添加的一种新的执行模式: 在不必要的情况下减少往返的耗时。

*default_operator

  (可选, string)   查询字符串(query string)的默认 *** 作符: AND 或 OR。 默认 OR。该参数仅与查询参数q一起使用。

df

  (可选, string)   default field的缩写。 查询字符串(query string)中没有指定字段前缀时的默认字段。该参数仅与查询参数q一起使用。

docvalue_fields

  (可选, string)   逗号分割的字段列表，作为每个命中(hit)的字段的docvalue的呈现。(原文: A comma-separated list of fields to return as the docvalue representation of a field for each hit.)

docvalue fields 的意思是从建好的索引处直接返回这个值, 而source是一大片物理磁盘区。理论上从docvalue处拿着值会比从source中要快，但是ES7之后这个差距已经很小了。 关于docvalue参考: https://www.elastic.co/guide/en/elasticsearch/reference/7.7/run-a-search.html#docvalue-fields

expand_wildcards

  (可选, string)   通配符查询时的范围限制。支持多个条件以逗号分割。默认open。

• all: 匹配open和closed的索引, 包括隐藏的.
• open: 默认, 表示只查询开放中的索引
• closed: 只匹配closed的索引
• hidden: 隐藏的(hidden)索引, 必须和open/closed联合使用.
• none: 不接受通配符.

explain

  (可选, bool)   如果为true，则返回所有hit的得分计算的详细信息。默认false。

from

  (可选, integer)   开始文档的偏移量（offset）。默认值0。

  默认情况下，您不能使用参数from和size对超过10000的文档进行分页。 这个限制是通过索引的配置参数index.max_result_window来设置的。

  深度分页或一次性请求多个结果会导致搜索速度变慢。 结果在返回之前要进行排序。 因为搜索请求通常会跨越多个分片，而每个分片必须生成自己的排序结果。 然后必须将这些分片独自排序的结果组合起来并再次排序，以确保总体的排序是正确的。

  建议使用scroll 或 参数search_after 作为深度分页的替代方法。

scroll, 类似传统数据库的游标(cursor)。需要指定一个时间来保存所有排序的数据，然后每次传递一个scroll_id来获取数据，避免每次的分页请求都要重新排序所有的数据。

ignore_throttled

  (可选, bool)   如果为true，具体的(concrete)、扩展的(expanded)或带别名(aliased)索引将在冻结时被忽略。 默认值为false。

ignore_unavailable

  (可选, bool)   如果为true，不存在的或者关闭的索引不会包含的返回结果中。默认false。

max_concurrent_shard_requests

  (可选, ,integer)   定义一个搜索请求可以在每个节点的多少个分片上并发执行。 这个值应该用来限制搜索对集群的影响，以限制并发分片请求的数量。 默认为5。

pre_filter_shard_size

  (可选, integer)   定义一个阈值，当搜索请求的分片数量超过阈值时，强制执行一个基于查询重写的预筛选往返(pre-filter roundtrip)对搜索分片进行预筛选。 如果一个分片不能匹配任何基于其重写方法的文档，比如日期过滤器(date filters )必须匹配，但分片边界和查询是不相交的，则这个过滤器往返(filter roundtrip)可以显著限制分片的数量。如果该参数未指定，只要满足以下任一条件，就会执行预过滤处理过程(pre-filter phase)：

• 请求目标的分片数量超过128
• 请求目标是一个或多个只读索引
• 主要的排序字段是索引的字段 (索引的mapping在定义时, 字段可以指定为不进行索引(及分析), 即: "index":false )

preference

  (可选, string)   指定应该在哪个节点或分片上执行查询。默认随机选择。

q

  (可选, string)   Lucene中的查询语法的查询字符串。可以使用参数q来执行搜索，它不能完全支持ES的Query DSL，但是用于测试会比较简单方便。

参数q会覆盖request body中的"query"参数。如果二者同时指定了相同的参数，即使有文档能匹配request body中的"query"条件， 这些文档也不会被返回。

request_cache

  (可选, bool)   如果为true，当size为0时会缓存搜索结果。参考分片请求缓存设置(shard request cache setting)。默认使用索引级别的设置。

默认情况下，当size=0时（就是不返回命中的文档）， 不会缓存hits.hits, 但是会缓存hits.total, 聚合(aggregations)及建议(suggestions)。如果您执行过 GET /twitter/_search?size=20&from=0这样的查询就能理解了。

rest_total_hits_as_int

  (可选, bool)   指定hits.total应该以整数形式还是一个对象的形式在rest(就是RESTful请求)搜索结果中返回。默认false，就是返回一个json的对象, 比如:

  "hits" : {
    "total" : {
      "value" : 3,
      "relation" : "eq"
    },

routing

&emps; (可选, string)   以指定的主分片为目标。

scroll

  (可选, 时间值)   给scroll设置的搜索上下文(search context)缓存保留的时间。参考scroll。

&emsp；默认情况下，最大值不能超过1d, 就是一天(24小时)。可以通过集群级别的设置search.max_keep_alive来修改。

search_type

  (可选, string)   搜索 *** 作的类型。可能的选项：

• query_then_fetch
• dfs_query_then_fetch: 比query_then_fetch得到的score更准确, 但是消耗更大

seq_no_primary_term

  (可选, bool)   如果为true, 则返回每个命中的最后修改的序号和主要的term。 参考并发控制优化(Optimistic concurrency control)

size

  (可选,, integer)   定义要返回的命中(hits,包括文档)的数量。默认是10。

 默认情况下，不能使用参数from和size对超过10000个文档进行分页。 这个限制来自索引的设置index.max_result_window。

 深度分页(deep paging)或同时请求很多结果会导致搜索速度变慢。 在返回结果之前会对其进行排序。 因为搜索请求通常会跨越多个分片，而每个分片必须先排序，然后再将这些单独的排序后的结果组合起来并再次进行排序，以确保总体顺序是正确的。

  建议使用scroll 或 参数search_after 作为深度分页的替代方法。

sort

  (可选, string)   逗号分隔的 :值对列表。

_source

  (可选)   指定要返回的匹配的文档的源字段(source fields)。这些字段在搜索返回结果中的hits.hits._source属性中。

 _source可用的值有：

• true: (bool) 返回整个文档的source
• false: (bool) 不返回文档的source
• source字段的逗号分割的列表，也可以使用通配符。

_souce_excludes

  (可选, string)   不需要在返回结果中显示的source字段, 用逗号分隔多个字段。

  还可以使用此参数从_source_includes查询参数中指定的子集中排除字段。(就是_souce_excludes的优先级比_source_includes高, 只要指定了排除的字段, 就不会再返回)。

  如果参数_source设置为false, 则不会返回任何字段, 这个参数也会被忽略。

_source_includes

  (可选, string) &nsbp; 希望在返回结果中显示的source字段, 用逗号分隔多个字段。

  如果指定了该参数, 则仅返回source中的这些字段。如果要从这个子集中排除字段，使用参数_source_excludes 。

  如果参数_source设置为false, 则不会返回任何字段, 这个参数也会被忽略。

stats

  (可选, string) &nsbp; 请求的特定标记(tag)，用于日志记录和统计目的。

stored_fields

  (可选,, string)   作为命中的一部分返回的以逗号分隔的存储字段(stored fiedls)列表。如果不指定字段，则返回结果中不会包含任何存储字段(stored fields)。

 如果指定了该参数, 则参数_source默认会被设置为false。可以使用"_source": true来同时返回源字段(source fields)和存储字段(stored fields)。

suggest_field

  (可选,, string)   指定建议(suggestions)使用的字段。

suggest_text

  (可选,, string)   指定建议(suggestions)应该返回的源文本(source text)。

terminate_after

  (可选,, integer)   每个分片收集的最大文档数量，一旦达到该数值，将提前终止查询的执行。

  默认为0, 即不会提前终止查询的执行。

timeout

  (可选,, time units)   指定等待返回的超时时间。如果在指定时间结束前没有收到返回结果，则请求失败并抛出错误。默认没有限制。

track_scores

  (可选,, bool)   如果为true，计算并返回文档得分，即使得分不用于排序。默认false。

track_total_hits

  (可选,, integer或bool)   匹配查询时精确统计的命中数。默认值是10000。

如果结果数量超过这个值, hits.total.relation会显示为gte而不是eq

  如果设置为true, 则使用其默认值。如果我false，则返回结果中不会包含匹配的文档的数量（不会返回hits.total节点）。

typed_keys

  (可选,, bool)   如果为true，则返回数据中的聚合(aggregation)和建议(suggester)的名称会以它们各自的类型作为前缀。默认true。

version

  (可选,, bool)   如果为true，会在返回的数据中包含文档的版本。默认false。

Request body

docvalue_fields

  (可选, 字符串数组或对象)   通配符表达式的数组。请求返回匹配这些命中模式的字段名的doc值。 字段属性的响应。在请求的响应数据的hits.fields属性中返回与这些字段名表达式匹配的doc values。

  可以使用字符串数组或对象来指定项目。参考doc value fields。

  docvalue_fields 对象的属性有:

• field: (必填, string) 通配符表达式。请求会返回与字段名表达式匹配的doc values。
• format (可选, string) doc values 返回的格式。   对于日期型字段(date fileds)，你可以以日期格式(date format)指定一个日期。对于数值型字段(numeric fields)，可以指定一个十进制格式的(DecimalFormat)表达式。暂不支持其他类型的字段。

explain

  (可选, bool)   如果为true，会在返回数据的hit中包含得分计算的详细信息。默认false。

from

  (可选, integer)   开始文档的偏移量（offset）。默认值0。

  默认情况下，您不能使用参数from和size对超过10000的文档进行分页。 这个限制是通过索引的配置参数index.max_result_window来设置的。

  深度分页或一次性请求多个结果会导致搜索速度变慢。 结果在返回之前要进行排序。 因为搜索请求通常会跨越多个分片，而每个分片必须生成自己的排序结果。 然后必须将这些分片独自排序的结果组合起来并再次排序，以确保总体的排序是正确的。

  建议使用scroll 或 参数search_after 作为深度分页的替代方法。

scroll, 类似传统数据库的游标(cursor)。需要指定一个时间来保存所有排序的数据，然后每次传递一个scroll_id来获取数据，避免每次的分页请求都要重新排序所有的数据。

query

  (可选, query对象)   使用Query DSL来指定搜索的定义。

seq_no_primary_term

  (可选,bool )   如果为true，返回每个命中的最后一次修改的序号和主要项目(primary term)。参考 乐观并发控制(Optimistic concurrency control)

size

  (可选, integer)   要返回的命中的数量。默认10。

  默认情况下，您不能使用参数from和size对超过10000的文档进行分页。 这个限制是通过索引的配置参数index.max_result_window来设置的。

  深度分页或一次性请求多个结果会导致搜索速度变慢。 结果在返回之前要进行排序。 因为搜索请求通常会跨越多个分片，而每个分片必须生成自己的排序结果。 然后必须将这些分片独自排序的结果组合起来并再次排序，以确保总体的排序是正确的。

  建议使用scroll 或 参数search_after 作为深度分页的替代方法。

如果指定了参数scroll则该值不能为0。

_source

  (可选)   指定要返回的匹配的文档的源字段(source fields)。这些字段是在搜索响应数据的hits._source属性中。默认true，表示返回所有字段。

  _source有效的值包括：

  true (bool) 返回真个文档的source。

  false (bool) 不返回文档的source。

   (字符串或字符串数组) 要返回的source字段的通配符表达式或一组表达式。