ElasticSearch的REST APIs - 搜索API - 搜索

最新推荐文章于 2024-07-26 14:43:34 发布

aben_sky

最新推荐文章于 2024-07-26 14:43:34 发布

阅读量923

点赞数

文章标签： python elasticsearch java 大数据数据库

本文链接：https://blog.csdn.net/aben_sky/article/details/121514577

版权

基于 ES 7.7 官方文档

搜索 (Search API)

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

GET|POST /<index>/_search

GET|POST /_search

路径参数 (Path parameters)

<index>

(可选, 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一起使用。

(可选, 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) 指定应该在哪个节点或分片上执行查询。默认随机选择。

(可选, 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) 逗号分隔的 <field>:<direction>值对列表。

_source

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

_source可用的值有：

true: (bool) 返回整个文档的source
false: (bool) 不返回文档的source
<string> 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。

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

<object> (object) 包含或排除的source字段列表的对象。属性包括：

excludes (字符串或字符串数组) 要排除的source字段的通配符表达式或一组表达式。它的优先级比includes高，所以可以用来排除includes属性指定的子集中的字段。

excludes (字符串或字符串数组) 要返回的source字段的通配符表达式或一组表达式。如果指定了该属性，则只有这些字段会被返回。也可以使用excludes属性从这个子集中排除字段。

terminate_after

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

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

timeout

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

version

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

响应消息体 ( Response body )

_scroll_id

(sring) 搜索及其搜索上下文(search context)的标识符。

你可以使用scroll API加上这个参数来获取搜索结果的下一批数据。参考Scroll。

该属性只有当请求中指定了参数scroll时才会返回。

took

(integer) es执行请求耗费的时间(毫秒)。

这个值是通过计算协调节点(coordinating node)从收到请求，到该节点已准备好可以发送响应数据的时间差得来的。

这个时间包括：

协调节点和数据节点之间通信的时间
请求在搜索线程池中排队，等待执行的时间
数据节点实际的执行时间

但是不包括：

客户端发送请求到ES的web服务的时间
以json格式将响应数据序列化的时间
ES服务端发送响应数据到客户端的时间

timed_out

(bool) 如果为true，在请求执行完成前已经超时；返回的数据可能只是其中的一部分，或者没有数据。

_shards

(object) 包含了请求使用到的分片的计数。其属性包括：

total (integer) 需要查询的分片总数，包括未分配的分片。

successful (integer) 成功执行请求的分片数。

skipped (integer) 得益于轻量级检查(lightweight check)，系统会跳过它认为可能没有相匹配的文档的分片的数量。这通常发生在搜索请求包含范围过滤器，而分片的值只落在该范围之外的时候。

failed (integer) 执行请求失败的分片数。注意，未分配的分片既不计入成功的分片数，也不计入失败的分片数。如果failed + successful小于total，则意味着有一些分片没有分配。

hits

(object) 包含返回的文档及元数据。其属性包括：

total

(object) 返回文档数量的元数据。其属性包括：

value (integer) 命中的文档的总数量。

relation (string) 指示属性value中的文档数量是精确值的还是其下限。它有2个取值: eq, equal, 等于的意思, 表明这个数量是精确的; gte, greater than or equal, 表明这个value是文档数量的下限值, 总的匹配的文档数量大于等于这个value的值。

max_score

(float) 文档相关性评分_score的最高值。如果请求时指定的排序字段不包含_score，则该值及所有文档的相关性评分都会是0。

hits

(对象数组) 返回的文档对象的数组。其属性包括：

_index (string) 该文档所在的索引的名称。

_type (string) 文档mapping的类型。该属性自6.0版本废弃, 并将在8.0版本移除

_index (string) 该文档所在的索引的名称。

_id (string) 文档的唯一标识符。注意：该id仅在其所在的索引中是唯一的。

_score (float) 文档的相关性评分, 一个32位的正浮点数。

_source (object) 索引时使用的原始的JSON信息体。可以使用_source参数使得结果中不返回这个属性(比如, "_source":false), 或者指定要返回的字段(比如, "_source":[字段列表])。

fields (object) 包含文档的字段值。这些字段必须在请求中使用以下的一个或多个参数指定：docvalue_fields, 'script_fields', stored_fields。其属性包含：

<field> (array) 数组, 以字段名为键, 值是对应字段的值。

几个例子

使用查询参数`q`搜索指定的一个索引

搜索索引twitter中字段user的值为kimchy的文档:

GET /twitter/_search?q=user:kimchy

使用查询参数`q`同时在多个索引中搜索

同时在索引twitter和orders中搜索字段user的值为kimchy的文档:

GET /twitter,orders/_search?q=user:kimchy

使用查询参数`q`同时在所有索引中搜索

在所有索引中搜索字段user的值为kimchy的文档:

GET /_search?q=user:kimchy

# 以下两种不常用
GET /_all/_search?q=user:kimchy
GET /*/_search?q=user:kimchy

在request body中使用`query`

GET /twitter/_search
{
  "query": {
    "term": {
      "user": "kimchy"
    }
  },
  "sort": [
    {
      "post_date": {
        "order": "desc"
      }
    },
    {
      "_score":{
        "order": "desc"
      }
    }
  ]
}

last update at 2021/11/18 21:16