« 建议器 计数 API »
Elastic 文档 ›Elasticsearch 指南 [8.17] ›REST API ›搜索 API

多重搜索 API

编辑

多重搜索 API

编辑

使用单个 API 请求执行多个搜索。

resp = client.msearch(
    index="my-index-000001",
    searches=[
        {},
        {
            "query": {
                "match": {
                    "message": "this is a test"
                }
            }
        },
        {
            "index": "my-index-000002"
        },
        {
            "query": {
                "match_all": {}
            }
        }
    ],
)
print(resp)
response = client.msearch(
  index: 'my-index-000001',
  body: [
    {},
    {
      query: {
        match: {
          message: 'this is a test'
        }
      }
    },
    {
      index: 'my-index-000002'
    },
    {
      query: {
        match_all: {}
      }
    }
  ]
)
puts response
const response = await client.msearch({
  index: "my-index-000001",
  searches: [
    {},
    {
      query: {
        match: {
          message: "this is a test",
        },
      },
    },
    {
      index: "my-index-000002",
    },
    {
      query: {
        match_all: {},
      },
    },
  ],
});
console.log(response);
GET my-index-000001/_msearch
{ }
{"query" : {"match" : { "message": "this is a test"}}}
{"index": "my-index-000002"}
{"query" : {"match_all" : {}}}

请求

编辑

GET /<目标>/_msearch

先决条件

编辑
  • 如果启用了 Elasticsearch 安全功能，您必须具有目标数据流、索引或别名的 read 索引权限。对于跨集群搜索，请参阅 远程集群。

描述

编辑

多重搜索 API 从单个 API 请求执行多个搜索。请求的格式类似于批量 API 格式，并使用换行符分隔的 JSON (NDJSON) 格式。

结构如下：

header\n
body\n
header\n
body\n

此结构经过专门优化，以减少特定搜索最终被重定向到另一个节点时的解析。

最后一行数据必须以换行符 \n 结尾。每个换行符前面可以跟一个回车符 \r。向此端点发送请求时，Content-Type 标头应设置为 application/x-ndjson。

路径参数

编辑
<目标>

（可选，字符串）要搜索的数据流、索引和别名的逗号分隔列表。

如果请求正文中的搜索未指定 index 目标，则此列表充当回退。

支持通配符 (*) 表达式。要搜索集群中的所有数据流和索引，请省略此参数或使用 _all 或 *。

查询参数

编辑
allow_no_indices
（可选，布尔值）如果为 false，则当任何通配符表达式、索引别名或 _all 值仅以缺失或关闭的索引为目标时，请求将返回错误。即使请求以其他打开的索引为目标，此行为也适用。例如，如果某个索引以 foo 开头，但没有索引以 bar 开头，则以 foo*,bar* 为目标的请求将返回错误。
ccs_minimize_roundtrips
（可选，布尔值）如果为 true，则会为跨集群搜索请求最大程度减少协调节点和远程集群之间的网络往返。默认为 true。请参阅 跨集群搜索如何处理网络延迟。
expand_wildcards

（可选，字符串）通配符模式可以匹配的索引类型。如果请求可以以数据流为目标，则此参数确定通配符表达式是否匹配隐藏的数据流。支持逗号分隔的值，例如 open,hidden。有效值为：

all
匹配任何数据流或索引，包括隐藏的那些。
open
匹配打开的、非隐藏的索引。也匹配任何非隐藏的数据流。
closed
匹配关闭的、非隐藏的索引。也匹配任何非隐藏的数据流。数据流无法关闭。
hidden
匹配隐藏的数据流和隐藏的索引。必须与 open、closed 或两者结合使用。
none
不接受通配符模式。

默认为 open。

ignore_throttled

（可选，布尔值）如果为 true，则在冻结时会忽略具体的、展开的或别名的索引。默认为 true。

[7.16.0] 在 7.16.0 中已弃用。

ignore_unavailable
（可选，布尔值）如果为 false，则当请求以缺失或关闭的索引为目标时，请求将返回错误。默认为 false。
max_concurrent_searches
（可选，整数）多重搜索 API 可以执行的最大并发搜索数。默认为 max(1, ( 数据节点的数量 * min(搜索线程池大小, 10) ))。
max_concurrent_shard_requests

（可选，整数）每个子搜索请求在每个节点上执行的最大并发分片请求数。默认为 5。

您可以使用此参数来防止请求使集群过载。例如，默认请求会命中集群中的所有数据流和索引。如果每个节点的分片数很高，这可能会导致分片请求被拒绝。

在某些情况下，并行性并非通过并发请求来实现。在这些情况下，此参数中的低值可能会导致性能不佳。例如，在预期并发搜索请求数量非常低的环境中，此参数中的较高值可能会提高性能。

pre_filter_shard_size

（可选，整数）定义一个阈值，如果搜索请求展开到的分片数量超过该阈值，则强制执行预筛选往返来基于查询重写预筛选搜索分片。如果分片基于其重写方法无法匹配任何文档，例如，如果日期过滤器是强制匹配的，但分片边界和查询是不相交的，则此筛选往返可以显著限制分片数量。未指定时，如果满足以下任何条件，则执行预筛选阶段：

  • 请求的目标是超过 128 个分片。
  • 请求的目标是一个或多个只读索引。
  • 查询的主排序的目标是索引字段。
rest_total_hits_as_int
（可选，布尔值）如果为 true，则 hits.total 在响应中以整数形式返回。默认为 false，返回对象。
routing
（可选，字符串）用于将搜索操作路由到特定分片的自定义 路由值。
search_type

（可选，字符串）指示在对返回的文档进行评分时，是否应使用全局术语和文档频率。

选项为：

query_then_fetch
（默认）文档使用该分片的本地术语和文档频率进行评分。这通常更快，但准确性较低。
dfs_query_then_fetch
文档使用所有分片中的全局术语和文档频率进行评分。这通常较慢，但准确性较高。
typed_keys
（可选，布尔值）指定是否应在响应中为聚合和建议器名称添加各自类型的前缀。

请求正文

编辑

请求正文包含换行符分隔的搜索 <header> 和搜索 <body> 对象列表。

<header>

（必需，对象）用于限制或更改搜索的参数。

每个搜索正文都必须使用此对象，但可以为空 ({}) 或空行。

<header> 对象的属性：
allow_no_indices

（可选，布尔值）如果为 true，则当通配符表达式或 _all 值仅检索到缺失或关闭的索引时，请求不会返回错误。

此参数也适用于指向缺失或索引的别名。

expand_wildcards

（可选，字符串）通配符模式可以匹配的索引类型。如果请求可以以数据流为目标，则此参数确定通配符表达式是否匹配隐藏的数据流。支持逗号分隔的值，例如 open,hidden。有效值为：

all
匹配任何数据流或索引，包括隐藏的那些。
open
匹配打开的、非隐藏的索引。也匹配任何非隐藏的数据流。
closed
匹配关闭的、非隐藏的索引。也匹配任何非隐藏的数据流。数据流无法关闭。
hidden
匹配隐藏的数据流和隐藏的索引。必须与 open、closed 或两者结合使用。
none
不接受通配符模式。

默认为 open。

ignore_unavailable
（可选，布尔值）如果为 true，则响应中不包含来自缺失或关闭索引的文档。默认为 false。
index

（可选，字符串或字符串数组）要搜索的数据流、索引和别名。支持通配符 (*)。将多个目标指定为数组。

如果未指定此参数，则使用 <目标> 请求路径参数作为回退。

preference
（可选，字符串）用于执行搜索的节点或分片。默认为随机。
request_cache
（可选，布尔值）如果为 true，则可以将请求缓存用于此搜索。默认为索引级设置。请参阅 分片请求缓存设置。
routing
（可选，字符串）用于将搜索操作路由到特定分片的自定义 路由值。
search_type

（可选，字符串）指示在对返回的文档进行评分时，是否应使用全局术语和文档频率。

选项为：

query_then_fetch
（默认）文档使用该分片的本地术语和文档频率进行评分。这通常更快，但准确性较低。
dfs_query_then_fetch
文档使用所有分片中的全局术语和文档频率进行评分。这通常较慢，但准确性较高。
<body>

（可选，对象）包含搜索请求的参数

<body> 对象的属性：
aggregations
（可选，聚合对象）您希望在搜索期间运行的聚合。请参阅聚合。
query
（可选，查询 DSL 对象）您希望在搜索期间运行的查询。响应中将返回与此查询匹配的命中。
from
（可选，整数）返回命中的起始偏移量。默认为 0。
size
（可选，整数）要返回的命中数。默认为 10。

响应正文

编辑
responses
（数组）包括每个搜索请求的搜索响应和状态代码，与原始多重搜索请求中的顺序匹配。如果某个特定搜索请求完全失败，则将返回包含 error 消息和相应状态代码的对象，以替代实际的搜索响应。

示例

编辑

标头包含要搜索的数据流、索引和别名。标头还指示 search_type、preference 和 routing。正文包含典型的搜索正文请求（包括 query、aggregations、from、size 等）。

$ cat requests
{"index" : "test"}
{"query" : {"match_all" : {}}, "from" : 0, "size" : 10}
{"index" : "test", "search_type" : "dfs_query_then_fetch"}
{"query" : {"match_all" : {}}}
{}
{"query" : {"match_all" : {}}}

{"query" : {"match_all" : {}}}
{"search_type" : "dfs_query_then_fetch"}
{"query" : {"match_all" : {}}}
$ curl -H "Content-Type: application/x-ndjson" -XGET localhost:9200/_msearch --data-binary "@requests"; echo

请注意，以上包含了一个空头的示例（也可以没有任何内容），这也是支持的。

该端点还允许您在请求路径中搜索数据流、索引和别名。在这种情况下，它将用作默认目标，除非在标头的 index 参数中明确指定。例如

resp = client.msearch(
    index="my-index-000001",
    searches=[
        {},
        {
            "query": {
                "match_all": {}
            },
            "from": 0,
            "size": 10
        },
        {},
        {
            "query": {
                "match_all": {}
            }
        },
        {
            "index": "my-index-000002"
        },
        {
            "query": {
                "match_all": {}
            }
        }
    ],
)
print(resp)
response = client.msearch(
  index: 'my-index-000001',
  body: [
    {},
    {
      query: {
        match_all: {}
      },
      from: 0,
      size: 10
    },
    {},
    {
      query: {
        match_all: {}
      }
    },
    {
      index: 'my-index-000002'
    },
    {
      query: {
        match_all: {}
      }
    }
  ]
)
puts response
const response = await client.msearch({
  index: "my-index-000001",
  searches: [
    {},
    {
      query: {
        match_all: {},
      },
      from: 0,
      size: 10,
    },
    {},
    {
      query: {
        match_all: {},
      },
    },
    {
      index: "my-index-000002",
    },
    {
      query: {
        match_all: {},
      },
    },
  ],
});
console.log(response);
GET my-index-000001/_msearch
{}
{"query" : {"match_all" : {}}, "from" : 0, "size" : 10}
{}
{"query" : {"match_all" : {}}}
{"index" : "my-index-000002"}
{"query" : {"match_all" : {}}}

上述示例将对所有请求体中未定义 index 目标的请求，针对 my-index-000001 索引执行搜索。最后一次搜索将针对 my-index-000002 索引执行。

可以采用类似的方式设置 search_type，以全局应用于所有搜索请求。

安全性

编辑

请参阅 基于 URL 的访问控制

部分响应

编辑

为确保快速响应，如果一个或多个分片失败，多搜索 API 将返回部分结果。有关更多信息，请参阅 分片失败。

搜索取消

编辑

可以使用标准的 任务取消 机制取消多搜索，并且当客户端关闭用于执行请求的 http 连接时，也会自动取消多搜索。至关重要的是，发送请求的 http 客户端应在请求超时或中止时关闭连接。取消 msearch 请求也会取消所有相应的子搜索请求。

« 建议器 计数 API »