Run multiple templated searches | Elasticsearch API documentation

Run multiple templated searchesAdded in 5.0.0

GET /_msearch/template

Run multiple templated searches with a single request. If you are providing a text file or text input to curl, use the --data-binary flag instead of -d to preserve newlines. For example:

$ cat requests
{ "index": "my-index" }
{ "id": "my-search-template", "params": { "query_string": "hello world", "from": 0, "size": 10 }}
{ "index": "my-other-index" }
{ "id": "my-other-search-template", "params": { "query_type": "match_all" }}

$ curl -H "Content-Type: application/x-ndjson" -XGET localhost:9200/_msearch/template --data-binary "@requests"; echo

External documentation

Query parameters

ccs_minimize_roundtripsboolean
If true, network round-trips are minimized for cross-cluster search requests.
max_concurrent_searchesnumber
The maximum number of concurrent searches the API can run.
search_typestring
The type of the search operation.
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 are query_then_fetch or dfs_query_then_fetch.
rest_total_hits_as_intboolean
If true, the response returns hits.total as an integer. If false, it returns hits.total as an object.
typed_keysboolean
If true, the response prefixes aggregation and suggester names with their respective types.

application/json

Bodyobject Required

explainboolean
If true, returns detailed information about score calculation as part of each hit.
idstring
paramsobject
Key-value pairs used to replace Mustache variables in the template. The key is the variable name. The value is the variable value.
Hide params attribute Show params attribute object
- *object Additional properties
profileboolean
If true, the query execution is profiled.
sourcestring | object
One of:
ScriptSourcestring SearchRequestBodyobject
Hide attributes Show attributes
aggregationsobject
Defines the aggregations that are run as part of the search request.
External documentation
collapseobject
External documentation
explainboolean
If true, the request returns detailed information about score computation as part of a hit.
extobject
Configuration of search extensions defined by Elasticsearch plugins.
Hide ext attribute Show ext attribute object
*object Additional properties
fromnumber
The starting document offset, which must be non-negative. 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
Hide highlight attributes Show highlight attributes object
type
boundary_charsstring
A string that contains each boundary character.
boundary_max_scannumber
How far to scan for boundary characters.
boundary_scannerstring
Values are chars, sentence, or word.
boundary_scanner_localestring
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_sourceboolean Deprecated
fragmenterstring
Values are simple or span.
fragment_sizenumber
The size of the highlighted fragment in characters.
highlight_filterboolean
highlight_queryobject
An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
max_fragment_lengthnumber
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_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_sizenumber
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
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.
optionsobject
orderstring
Value is score.
phrase_limitnumber
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_tagsarray[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_tagsarray[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_matchboolean
By default, only fields that contains a query match are highlighted. Set to false to highlight all fields.
tags_schemastring
Value is styled.
encoderstring
Values are default or html.
fieldsobject Required
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.
indices_boostarray[object]
Boost the _score of documents from specified indices. The boost value is the factor by which scores are multiplied. A boost value greater than 1.0 increases the score. A boost value between 0 and 1.0 decreases the score.
External documentation
Hide indices_boost attribute Show indices_boost attribute object
*number Additional properties
docvalue_fieldsarray[object]
An array of wildcard (*) field patterns. The request returns doc values for field names matching these patterns in the hits.fields property of the response.
External documentation
Hide docvalue_fields attributes Show docvalue_fields attributes object
fieldstring Required
Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
formatstring
The format in which the values are returned.
include_unmappedboolean
knnobject | array[object]
The approximate kNN search to run.
One of:
KnnSearchobject array-2array[object]
Hide attributes Show attributes
fieldstring Required
Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
query_vectorarray[number]
query_vector_builderobject
knumber
The final number of nearest neigrs to return as top hits
num_candidatesnumber
The number of nearest neigr candidates to consider per shard
boostnumber
Boost value to apply to kNN scores
filter
similaritynumber
The minimum similarity for a vector to be considered a match
inner_hitsobject
rescore_vectorobject
External documentation
rankobject
Hide rank attribute Show rank attribute object
rrfobject
min_scorenumber
The minimum _score for matching documents. Documents with a lower _score are not included in search results or results collected by aggregations.
post_filterobject
An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
External documentation
profileboolean
Set to true to return detailed timing information about the execution of individual components in a search request. NOTE: This is a debugging tool and adds significant overhead to search execution.
queryobject
An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
External documentation
rescoreobject | array[object]
Can be used to improve precision by reordering just the top (for example 100 - 500) documents returned by the query and post_filter phases.
One of:
Rescoreobject array-2array[object]
retrieverobject
Hide retriever attributes Show retriever attributes object
standardobject
knnobject
rrfobject
text_similarity_rerankerobject
ruleobject
script_fieldsobject
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
scriptobject Required
ignore_failureboolean
search_afterarray[number | string | boolean | null]
A field value.
sizenumber
The number of hits to return, which must not be negative. 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 property.
sliceobject
Hide slice attributes Show slice attributes object
fieldstring
Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
idstring Required
maxnumber Required
sortstring | object | array[string | object]
One of:
Fieldstring SortOptionsobject Sortarray[string | object]
Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
_sourceboolean | object
Defines how to fetch a source. Fetching can be disabled entirely, or the source can be filtered.
One of:
SourceConfigboolean SourceFilterobject
fieldsarray[object]
An array of wildcard (*) field 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
fieldstring Required
Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
formatstring
The format in which the values are returned.
include_unmappedboolean
suggestobject
Hide suggest attribute Show suggest attribute object
textstring
Global suggest text, to avoid repetition when the same text is used in several suggesters
terminate_afternumber
The 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.
IMPORTANT: Use with caution. Elasticsearch applies this property to each shard handling the request. When possible, let Elasticsearch perform early termination automatically. Avoid specifying this property for requests that target data streams with backing indices across multiple data tiers.
If set to 0 (default), the query does not terminate early.
timeoutstring
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
If true, calculate and return document scores, even if the scores are not used for sorting.
versionboolean
If true, the request returns the document version as part of a hit.
seq_no_primary_termboolean
If true, the request returns sequence number and primary term of the last modification of each hit.
External documentation
stored_fieldsstring | array[string]
pitobject
Hide pit attributes Show pit attributes object
idstring Required
keep_alivestring
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.
runtime_mappingsobject
Hide runtime_mappings attribute Show runtime_mappings attribute object
*object Additional properties
Hide * attributes Show * attributes object
fieldsobject
For type composite
fetch_fieldsarray[object]
For type lookup
formatstring
A custom format for date type runtime fields.
input_fieldstring
Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
target_fieldstring
Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
target_indexstring
scriptobject
typestring Required
Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
statsarray[string]
The 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.

Responses

200 application/json
Hide response attributes Show response attributes object
- tooknumber Required
- responsesarray[object] Required
  One of:
  MultiSearchItemobject ErrorResponseBaseobject
  Hide attributes Show attributes
  tooknumber 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_outboolean Required
  If true, the request timed out before completion; returned results may be partial or empty.
  _shardsobject Required
  Hide _shards attributes Show _shards attributes object
  failednumber Required
  successfulnumber Required
  totalnumber Required
  failuresarray[object]
  skippednumber
  hitsobject Required
  Hide hits attributes Show hits attributes object
  total
  hitsarray[object] Required
  max_score
  aggregationsobject
  _clustersobject
  Hide _clusters attributes Show _clusters attributes object
  skippednumber Required
  successfulnumber Required
  totalnumber Required
  runningnumber Required
  partialnumber Required
  failednumber Required
  detailsobject
  fieldsobject
  Hide fields attribute Show fields attribute object
  *object Additional properties
  max_scorenumber
  num_reduce_phasesnumber
  profileobject
  Hide profile attribute Show profile attribute object
  shardsarray[object] Required
  pit_idstring
  _scroll_idstring
  suggestobject
  Hide suggest attribute Show suggest attribute object
  *array[object] Additional properties
  terminated_earlyboolean
  statusnumber

GET /_msearch/template

curl \
 --request GET 'http://api.example.com/_msearch/template' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{ }\n{ \"id\": \"my-search-template\", \"params\": { \"query_string\": \"hello world\", \"from\": 0, \"size\": 10 }}\n{ }\n{ \"id\": \"my-other-search-template\", \"params\": { \"query_type\": \"match_all\" }}"'

Request example

Run `GET my-index/_msearch/template` to run multiple templated searches.

{ }
{ "id": "my-search-template", "params": { "query_string": "hello world", "from": 0, "size": 10 }}
{ }
{ "id": "my-other-search-template", "params": { "query_type": "match_all" }}