Run multiple searches | Elasticsearch Serverless API documentation

Run multiple searches Added in 1.3.0

POST /{index}/_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.

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

index string | array[string] Required

Comma-separated list of data streams, indices, and index aliases to search.

Query parameters

allow_no_indices boolean

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_roundtrips boolean

If true, network roundtrips between the coordinating node and remote clusters are minimized for cross-cluster search requests.
expand_wildcards string | array[string]

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.
ignore_throttled boolean

If true, concrete, expanded or aliased indices are ignored when frozen.
ignore_unavailable boolean

If true, missing or closed indices are not included in the response.
include_named_queries_score boolean

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.
max_concurrent_searches number

Maximum number of concurrent searches the multi search API can execute.
max_concurrent_shard_requests number

Maximum number of concurrent shard requests that each sub-search request executes per node.
pre_filter_shard_size number

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_int boolean

If true, hits.total are returned as an integer in the response. Defaults to false, which returns an object.
routing string

Custom routing value used to route search operations to a specific shard.
search_type string

Indicates whether global term and document frequencies should be used when scoring returned documents.

Values are query_then_fetch or dfs_query_then_fetch.
typed_keys boolean

Specifies whether aggregation and suggester names should be prefixed by their respective types in the response.

application/json

Body object Required

allow_no_indices boolean
expand_wildcards string | array[string]
ignore_unavailable boolean
index string | array[string]
preference string
request_cache boolean
routing string
search_type string

Values are query_then_fetch or dfs_query_then_fetch.
ccs_minimize_roundtrips boolean
allow_partial_search_results boolean
ignore_throttled boolean

aggregations object

External documentation
collapse object

External documentation
query object

An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.

External documentation
explain boolean

If true, returns detailed information about score computation as part of a hit.
ext object

Configuration of search extensions defined by Elasticsearch plugins.
Hide ext attribute Show ext attribute object
- * object Additional properties
stored_fields string | array[string]
docvalue_fields array[object]

Array of wildcard (*) patterns. The request returns doc values for field names matching these patterns in the hits.fields property of the response.
Hide docvalue_fields attributes Show docvalue_fields attributes object
- field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
- format string
  
  The format in which the values are returned.
- include_unmapped boolean
knn object | array[object]

Defines the approximate kNN search to run.
One of:
_types:KnnSearch object array-2 array[object]
Hide attributes Show attributes

field string Required

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

query_vector array[number]

query_vector_builder object

Hide query_vector_builder attribute Show query_vector_builder attribute object

text_embedding object

Hide text_embedding attributes Show text_embedding attributes object

model_id string Required

model_text string Required

k number

The final number of nearest neighbors to return as top hits

num_candidates number

The number of nearest neighbor candidates to consider per shard

boost number

Boost value to apply to kNN scores

filter object | array[object]

Filters for the kNN search query

One of:
query_dsl:QueryContainer object array-2 array[object]

An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.

External documentation

similarity number

The minimum similarity for a vector to be considered a match

inner_hits object

Hide inner_hits attributes Show inner_hits attributes object

name string

size number

The maximum number of hits to return per inner_hits.

from number

Inner hit starting document offset.

collapse object

External documentation

docvalue_fields array[object]

explain boolean

highlight object

ignore_unmapped boolean

script_fields object

Hide script_fields attribute Show script_fields attribute object

* object Additional properties

seq_no_primary_term boolean

fields string | array[string]

sort array[string | object]

_source boolean | object

Defines how to fetch a source. Fetching can be disabled entirely, or the source can be filtered.

One of:
_types:SourceConfig boolean _types:SourceFilter object

stored_fields string | array[string]

track_scores boolean

version boolean

rescore_vector object

Hide rescore_vector attribute Show rescore_vector attribute object

oversample number Required

Applies the specified oversample factor to k on the approximate kNN search
Hide attributes Show attributes object

field string Required

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

query_vector array[number]

query_vector_builder object

Hide query_vector_builder attribute Show query_vector_builder attribute object

text_embedding object

k number

The final number of nearest neighbors to return as top hits

num_candidates number

The number of nearest neighbor candidates to consider per shard

boost number

Boost value to apply to kNN scores

filter object | array[object]

Filters for the kNN search query

One of:
query_dsl:QueryContainer object array-2 array[object]

An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.

similarity number

The minimum similarity for a vector to be considered a match

inner_hits object

Hide inner_hits attributes Show inner_hits attributes object

name string

size number

The maximum number of hits to return per inner_hits.

from number

Inner hit starting document offset.

collapse object

docvalue_fields array[object]

explain boolean

highlight

ignore_unmapped boolean

script_fields object

seq_no_primary_term boolean

fields string | array[string]

sort

_source

stored_fields string | array[string]

track_scores boolean

version boolean

rescore_vector object

Hide rescore_vector attribute Show rescore_vector attribute object

oversample number Required

Applies the specified oversample factor to k on the approximate kNN search
from number

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.
highlight object
Hide highlight attributes Show highlight attributes object
- Values are plain, fvh, or unified.
- boundary_chars string
  
  A string that contains each boundary character.
- boundary_max_scan number
  
  How far to scan for boundary characters.
- boundary_scanner string
  
  Values are chars, sentence, or word.
- boundary_scanner_locale string
  
  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".
- force_source boolean Deprecated
- fragmenter string
  
  Values are simple or span.
- fragment_size number
  
  The size of the highlighted fragment in characters.
- highlight_filter boolean
- highlight_query object
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  External documentation
- max_fragment_length number
- max_analyzed_offset number
  
  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_offset query setting does not override the index.highlight.max_analyzed_offset setting, which prevails when it’s set to lower value than the query setting.
- no_match_size number
  
  The amount of text you want to return from the beginning of the field if there are no matching fragments to highlight.
- number_of_fragments number
  
  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. If number_of_fragments is 0, fragment_size is ignored.
- options object
  Hide options attribute Show options attribute object
  
  * object Additional properties
- order string
  
  Value is score.
- phrase_limit number
  
  Controls the number of matching phrases in a document that are considered. Prevents the fvh highlighter from analyzing too many phrases and consuming too much memory. When using matched_fields, phrase_limit phrases per matched field are considered. Raising the limit increases query time and consumes more memory. Only supported by the fvh highlighter.
- post_tags array[string]
  
  Use in conjunction with pre_tags to define the HTML tags to use for the highlighted text. By default, highlighted text is wrapped in <em> and </em> tags.
- pre_tags array[string]
  
  Use in conjunction with post_tags to define the HTML tags to use for the highlighted text. By default, highlighted text is wrapped in <em> and </em> tags.
- require_field_match boolean
  
  By default, only fields that contains a query match are highlighted. Set to false to highlight all fields.
- tags_schema string
  
  Value is styled.
- encoder string
  
  Values are default or html.
- fields object Required
indices_boost array[object]

Boosts the _score of documents from specified indices.
Hide indices_boost attribute Show indices_boost attribute object
- * number Additional properties
min_score number

Minimum _score for matching documents. Documents with a lower _score are not included in the search results.
post_filter object

An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.

External documentation
profile boolean
rescore object | array[object]
One of:
_types:Rescore object array-2 array[object]
Hide attributes Show attributes

window_size number

query object

Hide query attributes Show query attributes object

rescore_query object Required

An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.

query_weight number

Relative importance of the original query versus the rescore query.

rescore_query_weight number

Relative importance of the rescore query versus the original query.

score_mode string

Values are avg, max, min, multiply, or total.

learning_to_rank object

Hide learning_to_rank attributes Show learning_to_rank attributes object

model_id string Required

The unique identifier of the trained model uploaded to Elasticsearch

params object

Named parameters to be passed to the query templates used for feature
Hide attributes Show attributes object

window_size number

query object

learning_to_rank object
script_fields object

Retrieve a script evaluation (based on different fields) for each hit.
Hide script_fields attribute Show script_fields attribute object
- * object Additional properties
  Hide * attributes Show * attributes object
  
  script object Required
  
  Hide script attributes Show script attributes object
  
  source string
  
  The script source.
  
  id string
  
  params object
  
  Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.
  
  Hide params attribute Show params attribute object
  
  * object Additional properties
  
  lang string
  
  Any of:
  _types:ScriptLanguage string _types:ScriptLanguage string
  
  Values are painless, expression, mustache, or java.
  
  options object
  
  Hide options attribute Show options attribute object
  
  * string Additional properties
  
  ignore_failure boolean
search_after array[number | string | boolean | null]

A field value.
size number

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.
sort string | object | array[string | object]
One of:
_types:Field string _types:SortOptions object _types:Sort array[string | object]

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
Hide attributes Show attributes

_score object

Hide _score attribute Show _score attribute object

order string

Values are asc or desc.

_doc object

Hide _doc attribute Show _doc attribute object

order string

Values are asc or desc.

_geo_distance object

Hide _geo_distance attributes Show _geo_distance attributes object

mode string

Values are min, max, sum, avg, or median.

distance_type string

Values are arc or plane.

ignore_unmapped boolean

order string

Values are asc or desc.

unit string

Values are in, ft, yd, mi, nmi, km, m, cm, or mm.

nested object

_script object

Hide _script attributes Show _script attributes object

order string

Values are asc or desc.

script object Required

type string

Values are string, number, or version.

mode string

Values are min, max, sum, avg, or median.

nested object
One of:
_types:Field string _types:SortOptions object

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
_source boolean | object

Defines how to fetch a source. Fetching can be disabled entirely, or the source can be filtered.
One of:
_types:SourceConfig boolean _types:SourceFilter object
Hide attributes Show attributes

excludes string | array[string]

includes string | array[string]
fields array[object]

Array of wildcard (*) patterns. The request returns values for field names matching these patterns in the hits.fields property of the response.
Hide fields attributes Show fields attributes object
- field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
- format string
  
  The format in which the values are returned.
- include_unmapped boolean
terminate_after number

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.
stats array[string]

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.
timeout string

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_scores boolean

If true, calculate and return document scores, even if the scores are not used for sorting.
track_total_hits boolean | 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.
version boolean

If true, returns document version as part of a hit.
runtime_mappings object
Hide runtime_mappings attribute Show runtime_mappings attribute object
- * object Additional properties
  Hide * attributes Show * attributes object
  
  fields object
  
  For type composite
  
  Hide fields attribute Show fields attribute object
  
  * object Additional properties
  
  Hide * attribute Show * attribute object
  
  type string Required
  
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
  
  fetch_fields array[object]
  
  For type lookup
  
  Hide fetch_fields attributes Show fetch_fields attributes object
  
  field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  format string
  
  format string
  
  A custom format for date type runtime fields.
  
  input_field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  target_field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  target_index string
  
  script object
  
  Hide script attributes Show script attributes object
  
  source string
  
  The script source.
  
  id string
  
  params object
  
  Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.
  
  Hide params attribute Show params attribute object
  
  * object Additional properties
  
  lang string
  
  Any of:
  _types:ScriptLanguage string _types:ScriptLanguage string
  
  Values are painless, expression, mustache, or java.
  
  options object
  
  Hide options attribute Show options attribute object
  
  * string Additional properties
  
  type string Required
  
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
seq_no_primary_term boolean

If true, returns sequence number and primary term of the last modification of each hit. See Optimistic concurrency control.
pit object
Hide pit attributes Show pit attributes object
- id string Required
- keep_alive string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
suggest object
Hide suggest attribute Show suggest attribute object
- text string
  
  Global suggest text, to avoid repetition when the same text is used in several suggesters

Responses

200 application/json
Hide response attributes Show response attributes object
- took number Required
- responses array[object] Required
  
  One of:
  msearch:MultiSearchItem object _types:ErrorResponseBase object
  
  Hide attributes Show attributes
  
  took number Required
  
  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_out boolean Required
  
  If true, the request timed out before completion; returned results may be partial or empty.
  
  _shards object Required
  
  Hide _shards attributes Show _shards attributes object
  
  failed number Required
  
  successful number Required
  
  total number Required
  
  failures array[object]
  
  skipped number
  
  hits object Required
  
  Hide hits attributes Show hits attributes object
  
  total
  
  hits array[object] Required
  
  max_score
  
  aggregations object
  
  _clusters object
  
  Hide _clusters attributes Show _clusters attributes object
  
  skipped number Required
  
  successful number Required
  
  total number Required
  
  running number Required
  
  partial number Required
  
  failed number Required
  
  details object
  
  fields object
  
  Hide fields attribute Show fields attribute object
  
  * object Additional properties
  
  max_score number
  
  num_reduce_phases number
  
  profile object
  
  Hide profile attribute Show profile attribute object
  
  shards array[object] Required
  
  pit_id string
  
  _scroll_id string
  
  suggest object
  
  Hide suggest attribute Show suggest attribute object
  
  * array[object] Additional properties
  
  terminated_early boolean
  
  status number
  
  Hide attributes Show attributes
  
  error object Required
  
  Hide error attributes Show error attributes object
  
  type string Required
  
  The type of error
  
  reason string
  
  A human-readable explanation of the error, in English.
  
  stack_trace string
  
  The server stack trace. Present only if the error_trace=true parameter was sent with the request.
  
  caused_by object
  
  root_cause array[object]
  
  suppressed array[object]
  
  status number Required