OpenSearch/docs/reference/search/multi-search.asciidoc

[[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`.

The format of the request is similar to the bulk API format, and 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
--------------------------------------------------

The header part includes which index / indices to search on, optional
(mapping) types to search on, the `search_type`, `preference`, and
`routing`. The body includes the typical search body request (including
the `query`, `facets`, `from`, `size`, and so on). Here is an example:

[source,js]
--------------------------------------------------
$ cat requests
{"index" : "test"}
{"query" : {"match_all" : {}}, "from" : 0, "size" : 10}
{"index" : "test", "search_type" : "count"}
{"query" : {"match_all" : {}}}
{}
{"query" : {"match_all" : {}}}

{"query" : {"match_all" : {}}}
{"search_type" : "count"}
{"query" : {"match_all" : {}}}

$ curl -XGET localhost:9200/_msearch --data-binary @requests; echo
--------------------------------------------------

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 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 will be returned in place
of the actual search response.

The endpoint allows to also search against an index/indices and
type/types in the URI itself, in which case it will be used as the
default unless explicitly defined otherwise in the header. For example:

[source,js]
--------------------------------------------------
$ cat requests
{}
{"query" : {"match_all" : {}}, "from" : 0, "size" : 10}
{}
{"query" : {"match_all" : {}}}
{"index" : "test2"}
{"query" : {"match_all" : {}}}

$ curl -XGET localhost:9200/test/_msearch --data-binary @requests; echo
--------------------------------------------------

The above will execute the search against the `test` index for all the
requests that don't define an index, and the last one will be executed
against the `test2` index.

The `search_type` can be set in a similar manner to globally apply to
all search requests.

[float]
[[msearch-security]]
=== Security

See <<url-access-control>>