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

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