Run multiple searches
- POST also GET /{index}/_msearch
- POST also GET /_msearch
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:
header\n
body\n
header\n
body\n
This structure is specifically optimized to reduce parsing if a specific search ends up redirected to another node.
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.
Required authorization
- Index privileges read
Authentication
Authorization: <value>Elasticsearch APIs support key-based authentication. You must create an API key and use the encoded value in the request header. For example:
curl -X GET "${ES_URL}/_cat/indices?v=true" \
-H "Authorization: ApiKey ${API_KEY}"
To get API keys, use the /_security/api_key APIs.
Authorization: Basic <credentials>Authorization: Bearer <token>Elasticsearch APIs support the use of bearer tokens in the Authorization HTTP header to authenticate with the API.
For examples, refer to Token-based authentication services
Query parameters
-
allow_no_indicesboolean -
If false, the request returns an error if any wildcard expression, index alias, or _all value targets only missing or closed indices. This behavior applies even if the request targets other open indices. For example, a request targeting foo*,bar* returns an error if an index starts with foo but no index starts with bar.
-
ccs_minimize_roundtripsboolean · default: true -
If true, network roundtrips between the coordinating node and remote clusters are minimized for cross-cluster search requests.
-
expand_wildcardsstring · default: open -
Type of index that wildcard expressions can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams.
Supported values include:
all: Match any data stream or index, including hidden ones.open: Match open, non-hidden indices. Also matches any non-hidden data stream.closed: Match closed, non-hidden indices. Also matches any non-hidden data stream. Data streams cannot be closed.hidden: Match hidden data streams and hidden indices. Must be combined withopen,closed, orboth.none: Wildcard expressions are not accepted.
-
Values:
allopenclosedhiddennone -
ignore_throttledboolean · default: falsedeprecated -
If true, concrete, expanded or aliased indices are ignored when frozen.
-
ignore_unavailableboolean · default: false -
If true, missing or closed indices are not included in the response.
-
include_named_queries_scoreboolean · default: false -
Indicates whether hit.matched_queries should be rendered as a map that includes the name of the matched query associated with its score (true) or as an array containing the name of the matched queries (false) This functionality reruns each named query on every hit in a search response. Typically, this adds a small overhead to a request. However, using computationally expensive named queries on a large number of hits may add significant overhead.
-
indexunion oneOf -
Comma-separated list of data streams, indices, and index aliases to use as default
-
One of:
string[]orstring -
max_concurrent_searchesnumber -
Maximum number of concurrent searches the multi search API can execute.
-
max_concurrent_shard_requestsnumber · default: 5 -
Maximum number of concurrent shard requests that each sub-search request executes per node.
-
pre_filter_shard_sizenumber -
Defines a threshold that enforces a pre-filter roundtrip to prefilter search shards based on query rewriting if the number of shards the search request expands to exceeds the threshold. This filter roundtrip can limit the number of shards significantly if for instance a shard can not match any documents based on its rewrite method i.e., if date filters are mandatory to match but the shard bounds and the query are disjoint.
-
rest_total_hits_as_intboolean · default: false -
If true, hits.total are returned as an integer in the response. Defaults to false, which returns an object.
-
search_typeenum -
Indicates whether global term and document frequencies should be used when scoring returned documents.
Supported values include:
query_then_fetch: Documents are scored using local term and document frequencies for the shard. This is usually faster but less accurate.dfs_query_then_fetch: Documents are scored using global term and document frequencies across all shards. This is usually slower but more accurate.
-
Values:
query_then_fetchdfs_query_then_fetch
Request body
Contains parameters used to limit or change the subsequent search body request.
-
expand_wildcardsstring -
Supported values include:
all: Match any data stream or index, including hidden ones.open: Match open, non-hidden indices. Also matches any non-hidden data stream.closed: Match closed, non-hidden indices. Also matches any non-hidden data stream. Data streams cannot be closed.hidden: Match hidden data streams and hidden indices. Must be combined withopen,closed, orboth.none: Wildcard expressions are not accepted.
-
Values:
allopenclosedhiddennone -
search_typeenum -
Supported values include:
query_then_fetch: Documents are scored using local term and document frequencies for the shard. This is usually faster but less accurate.dfs_query_then_fetch: Documents are scored using global term and document frequencies across all shards. This is usually slower but more accurate.
-
Values:
query_then_fetchdfs_query_then_fetch
-
aggregationsmap string to {} Aggregation -
collapseobject -
inner_hitsunion oneOf -
The number of inner hits and their sort order
-
objectorobject[] -
namestring -
The name for the particular inner hit definition in the response. Useful when a search request contains multiple inner hits.
-
collapseobject -
Same fields as
collapsein{ aggregations, collapse, query, … } -
highlightobject -
typeunion -
Supported values include:
plain: Theplainhighlighter uses the standard Lucene highlighterfvh: The fvh highlighter uses the Lucene Fast Vector highlighter.unified: The unified highlighter uses the Lucene Unified Highlighter.
-
Values:
plainfvhunified -
boundary_scannerenum -
Specifies how to break the highlighted fragments: chars, sentence, or word. Only valid for the unified and fvh highlighters. Defaults to
sentencefor theunifiedhighlighter. Defaults tocharsfor thefvhhighlighter.Supported values include:
chars: Use the characters specified byboundary_charsas highlighting boundaries. Theboundary_max_scansetting controls how far to scan for boundary characters. Only valid for thefvhhighlighter.sentence: Break highlighted fragments at the next sentence boundary, as determined by Java’sBreakIterator. You can specify the locale to use withboundary_scanner_locale. When used with theunifiedhighlighter, thesentencescanner splits sentences bigger thanfragment_sizeat the first word boundary next to fragment_size. You can setfragment_sizeto0to never split any sentence.word: Break highlighted fragments at the next word boundary, as determined by Java’sBreakIterator. You can specify the locale to use withboundary_scanner_locale.
-
Values:
charssentenceword -
boundary_scanner_localestring · default: Locale.ROOT -
Controls which locale is used to search for sentence and word boundaries. This parameter takes a form of a language tag, for example:
"en-US","fr-FR","ja-JP". -
fragmenterenum · default: span -
Specifies how text should be broken up in highlight snippets:
simpleorspan. Only valid for theplainhighlighter. -
Values:
simplespan -
highlight_query{} Query -
Highlight matches for a query other than the search query. This is especially useful if you use a rescore query because those are not taken into account by highlighting by default.
-
max_analyzed_offsetnumber -
If set to a non-negative value, highlighting stops at this defined maximum limit. The rest of the text is not processed, thus not highlighted and no error is returned The
max_analyzed_offsetquery setting does not override theindex.highlight.max_analyzed_offsetsetting, which prevails when it’s set to lower value than the query setting. -
no_match_sizenumber · default: 0 -
The amount of text you want to return from the beginning of the field if there are no matching fragments to highlight.
-
number_of_fragmentsnumber · default: 5 -
The maximum number of fragments to return. If the number of fragments is set to
0, no fragments are returned. Instead, the entire field contents are highlighted and returned. This can be handy when you need to highlight short texts such as a title or address, but fragmentation is not required. Ifnumber_of_fragmentsis0,fragment_sizeis ignored. -
orderenum · default: none -
Sorts highlighted fragments by score when set to
score. By default, fragments will be output in the order they appear in the field (order:none). Setting this option toscorewill output the most relevant fragments first. Each highlighter applies its own logic to compute relevancy scores. -
Values:
score -
phrase_limitnumber · default: 256 -
Controls the number of matching phrases in a document that are considered. Prevents the
fvhhighlighter from analyzing too many phrases and consuming too much memory. When usingmatched_fields,phrase_limitphrases per matched field are considered. Raising the limit increases query time and consumes more memory. Only supported by thefvhhighlighter. -
post_tagsstring[] -
Use in conjunction with
pre_tagsto define the HTML tags to use for the highlighted text. By default, highlighted text is wrapped in<em>and</em>tags. -
pre_tagsstring[] -
Use in conjunction with
post_tagsto define the HTML tags to use for the highlighted text. By default, highlighted text is wrapped in<em>and</em>tags. -
require_field_matchboolean · default: true -
By default, only fields that contains a query match are highlighted. Set to
falseto highlight all fields. -
fieldsmap string to objectrequired -
<string>object -
typeunion -
Supported values include:
plain: Theplainhighlighter uses the standard Lucene highlighterfvh: The fvh highlighter uses the Lucene Fast Vector highlighter.unified: The unified highlighter uses the Lucene Unified Highlighter.
-
Values:
plainfvhunified -
boundary_scannerenum -
Specifies how to break the highlighted fragments: chars, sentence, or word. Only valid for the unified and fvh highlighters. Defaults to
sentencefor theunifiedhighlighter. Defaults tocharsfor thefvhhighlighter.Supported values include:
chars: Use the characters specified byboundary_charsas highlighting boundaries. Theboundary_max_scansetting controls how far to scan for boundary characters. Only valid for thefvhhighlighter.sentence: Break highlighted fragments at the next sentence boundary, as determined by Java’sBreakIterator. You can specify the locale to use withboundary_scanner_locale. When used with theunifiedhighlighter, thesentencescanner splits sentences bigger thanfragment_sizeat the first word boundary next to fragment_size. You can setfragment_sizeto0to never split any sentence.word: Break highlighted fragments at the next word boundary, as determined by Java’sBreakIterator. You can specify the locale to use withboundary_scanner_locale.
-
Values:
charssentenceword -
boundary_scanner_localestring · default: Locale.ROOT -
Controls which locale is used to search for sentence and word boundaries. This parameter takes a form of a language tag, for example:
"en-US","fr-FR","ja-JP". -
fragmenterenum · default: span -
Specifies how text should be broken up in highlight snippets:
simpleorspan. Only valid for theplainhighlighter. -
Values:
simplespan -
highlight_query{} Query -
Highlight matches for a query other than the search query. This is especially useful if you use a rescore query because those are not taken into account by highlighting by default.
-
max_analyzed_offsetnumber -
If set to a non-negative value, highlighting stops at this defined maximum limit. The rest of the text is not processed, thus not highlighted and no error is returned The
max_analyzed_offsetquery setting does not override theindex.highlight.max_analyzed_offsetsetting, which prevails when it’s set to lower value than the query setting. -
no_match_sizenumber · default: 0 -
The amount of text you want to return from the beginning of the field if there are no matching fragments to highlight.
-
number_of_fragmentsnumber · default: 5 -
The maximum number of fragments to return. If the number of fragments is set to
0, no fragments are returned. Instead, the entire field contents are highlighted and returned. This can be handy when you need to highlight short texts such as a title or address, but fragmentation is not required. Ifnumber_of_fragmentsis0,fragment_sizeis ignored. -
orderenum · default: none -
Sorts highlighted fragments by score when set to
score. By default, fragments will be output in the order they appear in the field (order:none). Setting this option toscorewill output the most relevant fragments first. Each highlighter applies its own logic to compute relevancy scores. -
Values:
score -
phrase_limitnumber · default: 256 -
Controls the number of matching phrases in a document that are considered. Prevents the
fvhhighlighter from analyzing too many phrases and consuming too much memory. When usingmatched_fields,phrase_limitphrases per matched field are considered. Raising the limit increases query time and consumes more memory. Only supported by thefvhhighlighter. -
post_tagsstring[] -
Use in conjunction with
pre_tagsto define the HTML tags to use for the highlighted text. By default, highlighted text is wrapped in<em>and</em>tags. -
pre_tagsstring[] -
Use in conjunction with
post_tagsto define the HTML tags to use for the highlighted text. By default, highlighted text is wrapped in<em>and</em>tags. -
max_concurrent_group_searchesnumber -
The number of concurrent requests allowed to retrieve the inner_hits per group
-
collapseobject -
Same fields as
collapsein{ aggregations, collapse, query, … } -
query{} Query -
Defines the search definition using the Query DSL.
-
explainboolean · default: false -
If true, returns detailed information about score computation as part of a hit.
-
stored_fieldsstring -
List of stored fields to return as part of a hit. If no fields are specified, no stored fields are included in the response. If this field is specified, the _source parameter defaults to false. You can pass _source: true to return both source fields and stored fields in the search response.
-
docvalue_fieldsobject[] -
Array of wildcard (*) patterns. The request returns doc values for field names matching these patterns in the hits.fields property of the response.
-
knnunion oneOf -
Defines the approximate kNN search to run.
-
objectorobject[] -
query_vector_builderobject -
The query vector builder. You must provide a query_vector_builder or query_vector, but not both.
-
inner_hitsobject -
If defined, each search hit will contain inner hits.
-
namestring -
The name for the particular inner hit definition in the response. Useful when a search request contains multiple inner hits.
-
collapseobject -
max_concurrent_group_searchesnumber -
The number of concurrent requests allowed to retrieve the inner_hits per group
-
collapseobject -
Same fields as
collapseininner_hits -
highlightobject -
Same fields as
highlightininner_hits -
fromnumber · default: 0 -
Starting document offset. By default, you cannot page through more than 10,000 hits using the from and size parameters. To page through more hits, use the search_after parameter.
-
highlightobject -
Same fields as
highlightininner_hits -
min_scorenumber -
The minimum
_scorefor matching documents. Documents with a lower_scoreare not included in search results and results collected by aggregations. -
post_filter{} Query -
rescoreunion oneOf -
objectorobject[] -
queryobject -
rescore_query{} Queryrequired -
The query to use for rescoring. This query is only run on the Top-K results returned by the
queryandpost_filterphases. -
query_weightnumber · default: 1 -
Relative importance of the original query versus the rescore query.
-
rescore_query_weightnumber · default: 1 -
Relative importance of the rescore query versus the original query.
-
score_modeenum · default: total -
Determines how scores are combined.
Supported values include:
avg: Average the original score and the rescore query score.max: Take the max of original score and the rescore query score.min: Take the min of the original score and the rescore query score.multiply: Multiply the original score by the rescore query score. Useful forfunctionquery rescores.total: Add the original score and the rescore query score.
-
Values:
avgmaxminmultiplytotal -
script_fieldsmap string to object -
Retrieve a script evaluation (based on different fields) for each hit.
-
sizenumber · default: 10 -
The number of hits to return. By default, you cannot page through more than 10,000 hits using the from and size parameters. To page through more hits, use the search_after parameter.
-
_sourceunion -
Indicates which source fields are returned for matching documents. These fields are returned in the hits._source property of the search response.
-
fieldsobject[] -
Array of wildcard (*) patterns. The request returns values for field names matching these patterns in the hits.fields property of the response.
-
terminate_afternumber · default: 0 -
Maximum number of documents to collect for each shard. If a query reaches this limit, Elasticsearch terminates the query early. Elasticsearch collects documents before sorting. Defaults to 0, which does not terminate query execution early.
-
statsstring[] -
Stats groups to associate with the search. Each group maintains a statistics aggregation for its associated searches. You can retrieve these stats using the indices stats API.
-
timeoutstring -
Specifies the period of time to wait for a response from each shard. If no response is received before the timeout expires, the request fails and returns an error. Defaults to no timeout.
-
track_scoresboolean · default: false -
If true, calculate and return document scores, even if the scores are not used for sorting.
-
track_total_hitsboolean | number -
Number of hits matching the query to count accurately. If true, the exact number of hits is returned at the cost of some performance. If false, the response does not include the total number of hits matching the query. Defaults to 10,000 hits.
-
runtime_mappingsobject -
Defines one or more runtime fields in the search request. These fields take precedence over mapped fields with the same name.
-
seq_no_primary_termboolean -
If true, returns sequence number and primary term of the last modification of each hit. See Optimistic concurrency control.
Response
-
responsesunion oneOf[]required - One of:
-
tooknumberrequired -
The number of milliseconds it took Elasticsearch to run the request. This value is calculated by measuring the time elapsed between receipt of a request on the coordinating node and the time at which the coordinating node is ready to send the response. It includes:
- Communication time between the coordinating node and data nodes
- Time the request spends in the search thread pool, queued for execution
- Actual run time
It does not include:
- Time needed to send the request to Elasticsearch
- Time needed to serialize the JSON response
- Time needed to send the response to a client
-
timed_outbooleanrequired -
If
true, the request timed out before completion; returned results may be partial or empty. -
hitsobjectrequired -
The returned documents and metadata.
-
aggregationsmap string to {} Aggregation result -
profileobject -
shardsobject[]required -
aggregationsobject[]required -
childrenobject[] -
Same fields as
aggregationsinshards -
dfsobject -
_scroll_idstring -
The identifier for the search and its search context. You can use this scroll ID with the scroll API to retrieve the next batch of search results for the request. This property is returned only if the
scrollquery parameter is specified in the request. - Reference
The response returned by Elasticsearch when request execution did not succeed.