IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.

« Suggesters Count API »

› › ›

Multi Search API

edit

Multi Search API

edit

Executes several searches with a single API request.

Request

edit

GET /<index>/_msearch

Description

edit

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):

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

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.

Path parameters

edit

<index>: (Optional, string) Comma-separated list or wildcard expression of index names used to limit the request.

Request body

edit

aggregations

(Optional, object) Specifies aggregations.

from

(Optional, integer) Starting document offset. Defaults to 0.

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.

preference

(Optional, string) Specifies the node or shard the operation should be performed on. Random by default.

query

(Optional, query object) Defines the search definition using the Query DSL.

routing

(Optional, string) Target the specified primary shard.

search_type

(Optional, string) The type of the search operation. Available options:

query_then_fetch
dfs_query_then_fetch

size

(Optional, integer) The number of hits to return. Defaults to 10.

Response body

edit

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.

Examples

edit

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

$ 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

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:

GET twitter/_msearch
{}
{"query" : {"match_all" : {}}, "from" : 0, "size" : 10}
{}
{"query" : {"match_all" : {}}}
{"index" : "twitter2"}
{"query" : {"match_all" : {}}}

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.

Security

edit

See URL-based access control

Template support

edit

Much like described in Search Template for the _search resource, _msearch also provides support for templates. Submit them like follows for inline templates:

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" } }

You can also create search templates:

POST /_scripts/my_template_1
{
    "script": {
        "lang": "mustache",
        "source": {
            "query": {
                "match": {
                    "message": "{{query_string}}"
                }
            }
        }
    }
}

POST /_scripts/my_template_2
{
    "script": {
        "lang": "mustache",
        "source": {
            "query": {
                "term": {
                    "{{field}}": "{{value}}"
                }
            }
        }
    }
}

You can use search templates in a _msearch:

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" } }

Partial responses

edit

To ensure fast responses, the multi search API will respond with partial results if one or more shards fail. See Shard failures for more information.

« Suggesters Count API »