228 lines
6.9 KiB
Plaintext
228 lines
6.9 KiB
Plaintext
[[search-multi-search]]
|
|
=== Multi Search API
|
|
|
|
Executes several searches with a single API request.
|
|
|
|
[[search-multi-search-api-request]]
|
|
==== {api-request-title}
|
|
|
|
`GET /<index>/_msearch`
|
|
|
|
|
|
[[search-multi-search-api-desc]]
|
|
==== {api-description-title}
|
|
|
|
The multi search AP executes several searches from a single API request.
|
|
The format of the request is similar to the bulk API format and makes use
|
|
of the newline delimited JSON (NDJSON) format. The structure is as follows (the
|
|
structure is specifically optimized to reduce parsing if a specific search ends
|
|
up redirected to another node):
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
header\n
|
|
body\n
|
|
header\n
|
|
body\n
|
|
--------------------------------------------------
|
|
// NOTCONSOLE
|
|
|
|
*NOTE*: the final line of data must end with a newline character `\n`. Each newline character
|
|
may be preceded by a carriage return `\r`. When sending requests to this endpoint the
|
|
`Content-Type` header should be set to `application/x-ndjson`.
|
|
|
|
[[search-multi-search-api-path-params]]
|
|
==== {api-path-parms-title}
|
|
|
|
include::{docdir}/rest-api/common-parms.asciidoc[tag=index]
|
|
|
|
|
|
[[search-multi-search-api-request-body]]
|
|
==== {api-request-body-title}
|
|
|
|
`aggregations`::
|
|
(Optional, object) Specifies aggregations.
|
|
|
|
include::{docdir}/rest-api/common-parms.asciidoc[tag=from]
|
|
|
|
`max_concurrent_searches`::
|
|
(Optional, integer) Specifies the maximum number of concurrent searches the
|
|
multi search API will execute. This default is based on the number of data
|
|
nodes and the default search thread pool size.
|
|
|
|
`max_concurrent_shard_requests`::
|
|
(Optional, integer) Specifies the maximum number of concurrent shard requests
|
|
that each sub search request will execute per node. This parameter should be
|
|
used to protect a single request from overloading a cluster (for example a
|
|
default request will hit all indices in a cluster which could cause shard
|
|
request rejections if the number of shards per node is high). Defaults to `5`.
|
|
In certain scenarios parallelism isn't achieved through concurrent request
|
|
such that this protection will result in poor performance. For instance in an
|
|
environment where only a very low number of concurrent search requests are
|
|
expected it might help to increase this value to a higher number.
|
|
|
|
include::{docdir}/rest-api/common-parms.asciidoc[tag=preference]
|
|
|
|
`query`::
|
|
(Optional, <<query-dsl,query object>>) Defines the search definition using the
|
|
<<query-dsl,Query DSL>>.
|
|
|
|
include::{docdir}/rest-api/common-parms.asciidoc[tag=routing]
|
|
|
|
include::{docdir}/rest-api/common-parms.asciidoc[tag=search_type]
|
|
|
|
`size`::
|
|
(Optional, integer) The number of hits to return. Defaults to `10`.
|
|
|
|
|
|
[[search-multi-search-api-response-body]]
|
|
==== {api-response-body-title}
|
|
|
|
`responses`::
|
|
(array) Includes the search response and status code for each search request
|
|
matching its order in the original multi search request. If there was a
|
|
complete failure for a specific search request, an object with `error` message
|
|
and corresponding status code will be returned in place of the actual search
|
|
response.
|
|
|
|
|
|
[[search-multi-search-api-example]]
|
|
==== {api-examples-title}
|
|
|
|
The header part includes which index / indices to search on, the `search_type`,
|
|
`preference`, and `routing`. The body includes the typical search body request
|
|
(including the `query`, `aggregations`, `from`, `size`, and so on).
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
$ 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" : {}}}
|
|
--------------------------------------------------
|
|
// NOTCONSOLE
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
$ curl -H "Content-Type: application/x-ndjson" -XGET localhost:9200/_msearch --data-binary "@requests"; echo
|
|
--------------------------------------------------
|
|
// NOTCONSOLE
|
|
|
|
Note, the above includes an example of an empty header (can also be just
|
|
without any content) which is supported as well.
|
|
|
|
|
|
The endpoint allows to also search against an index/indices in the URI itself,
|
|
in which case it will be used as the default unless explicitly defined otherwise
|
|
in the header. For example:
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
GET twitter/_msearch
|
|
{}
|
|
{"query" : {"match_all" : {}}, "from" : 0, "size" : 10}
|
|
{}
|
|
{"query" : {"match_all" : {}}}
|
|
{"index" : "twitter2"}
|
|
{"query" : {"match_all" : {}}}
|
|
--------------------------------------------------
|
|
// TEST[setup:twitter]
|
|
|
|
The above will execute the search against the `twitter` index for all the
|
|
requests that don't define an index, and the last one will be executed
|
|
against the `twitter2` index.
|
|
|
|
The `search_type` can be set in a similar manner to globally apply to
|
|
all search requests.
|
|
|
|
|
|
[[msearch-security]]
|
|
==== Security
|
|
|
|
See <<url-access-control>>
|
|
|
|
|
|
[[template-msearch]]
|
|
==== Template support
|
|
|
|
Much like described in <<search-template>> for the _search resource, _msearch
|
|
also provides support for templates. Submit them like follows for inline
|
|
templates:
|
|
|
|
[source,console]
|
|
-----------------------------------------------
|
|
GET _msearch/template
|
|
{"index" : "twitter"}
|
|
{ "source" : "{ \"query\": { \"match\": { \"message\" : \"{{keywords}}\" } } } }", "params": { "query_type": "match", "keywords": "some message" } }
|
|
{"index" : "twitter"}
|
|
{ "source" : "{ \"query\": { \"match_{{template}}\": {} } }", "params": { "template": "all" } }
|
|
-----------------------------------------------
|
|
// TEST[setup:twitter]
|
|
|
|
|
|
You can also create search templates:
|
|
|
|
[source,console]
|
|
------------------------------------------
|
|
POST /_scripts/my_template_1
|
|
{
|
|
"script": {
|
|
"lang": "mustache",
|
|
"source": {
|
|
"query": {
|
|
"match": {
|
|
"message": "{{query_string}}"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
------------------------------------------
|
|
// TEST[setup:twitter]
|
|
|
|
|
|
[source,console]
|
|
------------------------------------------
|
|
POST /_scripts/my_template_2
|
|
{
|
|
"script": {
|
|
"lang": "mustache",
|
|
"source": {
|
|
"query": {
|
|
"term": {
|
|
"{{field}}": "{{value}}"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
------------------------------------------
|
|
// TEST[continued]
|
|
|
|
You can use search templates in a _msearch:
|
|
|
|
[source,console]
|
|
-----------------------------------------------
|
|
GET _msearch/template
|
|
{"index" : "main"}
|
|
{ "id": "my_template_1", "params": { "query_string": "some message" } }
|
|
{"index" : "main"}
|
|
{ "id": "my_template_2", "params": { "field": "user", "value": "test" } }
|
|
-----------------------------------------------
|
|
// TEST[continued]
|
|
|
|
|
|
[[multi-search-partial-responses]]
|
|
==== Partial responses
|
|
|
|
To ensure fast responses, the multi search API will respond with partial results
|
|
if one or more shards fail. See <<shard-failures, Shard failures>> for more
|
|
information.
|