[DOCS] Reformats multi search API (#46256)
* [DOCS] Reformats multi search API. Co-Authored-By: James Rodewig <james.rodewig@elastic.co>
This commit is contained in:
István Zoltán Szabó
parent
8fca5b5204
commit
f2bdd392e7
|
|
@ -1,13 +1,22 @@
|
|||
[[search-multi-search]]
|
||||
=== Multi Search API
|
||||
|
||||
The multi search API allows to execute several search requests within
|
||||
the same API. The endpoint for it is `_msearch`.
|
||||
Executes several searches with 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):
|
||||
[[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]
|
||||
--------------------------------------------------
|
||||
|
|
@ -22,9 +31,67 @@ body\n
|
|||
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`.
|
||||
|
||||
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). Here is an example:
|
||||
[[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]
|
||||
--------------------------------------------------
|
||||
|
|
@ -51,11 +118,6 @@ $ curl -H "Content-Type: application/x-ndjson" -XGET localhost:9200/_msearch --d
|
|||
Note, the above includes an example of an empty header (can also be just
|
||||
without any content) which is supported as well.
|
||||
|
||||
The response returns a `responses` array, which 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 that
|
||||
specific search request, an object with `error` message and corresponding
|
||||
status code will be returned in place of the actual search response.
|
||||
|
||||
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
|
||||
|
|
@ -81,33 +143,19 @@ against the `twitter2` index.
|
|||
The `search_type` can be set in a similar manner to globally apply to
|
||||
all search requests.
|
||||
|
||||
The msearch's `max_concurrent_searches` request parameter can be used to control
|
||||
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.
|
||||
|
||||
The request parameter `max_concurrent_shard_requests` can be used to control
|
||||
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 (e.g., 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). This default value is `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.
|
||||
|
||||
[float]
|
||||
[[msearch-security]]
|
||||
==== Security
|
||||
|
||||
See <<url-access-control>>
|
||||
|
||||
[float]
|
||||
|
||||
[[template-msearch]]
|
||||
==== Template support
|
||||
|
||||
Much like described in <<search-template>> for the _search resource, _msearch
|
||||
also provides support for templates. Submit them like follows:
|
||||
also provides support for templates. Submit them like follows for inline
|
||||
templates:
|
||||
|
||||
[source,js]
|
||||
-----------------------------------------------
|
||||
|
|
@ -120,7 +168,6 @@ GET _msearch/template
|
|||
// CONSOLE
|
||||
// TEST[setup:twitter]
|
||||
|
||||
for inline templates.
|
||||
|
||||
You can also create search templates:
|
||||
|
||||
|
|
@ -143,6 +190,7 @@ POST /_scripts/my_template_1
|
|||
// CONSOLE
|
||||
// TEST[setup:twitter]
|
||||
|
||||
|
||||
[source,js]
|
||||
------------------------------------------
|
||||
POST /_scripts/my_template_2
|
||||
|
|
@ -162,7 +210,7 @@ POST /_scripts/my_template_2
|
|||
// CONSOLE
|
||||
// TEST[continued]
|
||||
|
||||
and later use them in a _msearch:
|
||||
You can use search templates in a _msearch:
|
||||
|
||||
[source,js]
|
||||
-----------------------------------------------
|
||||
|
|
@ -175,7 +223,10 @@ GET _msearch/template
|
|||
// CONSOLE
|
||||
// TEST[continued]
|
||||
|
||||
[float]
|
||||
|
||||
[[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.
|
||||
|
||||
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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue