Run multiple templated searches | Elasticsearch API documentation (v9)

Run multiple templated searches Generally available; Added 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

Required authorization

Index privileges: read

More about searching templates

Query parameters

ccs_minimize_roundtrips boolean

If true, network round-trips are minimized for cross-cluster search requests.
max_concurrent_searches number

The maximum number of concurrent searches the API can run.
search_type string

The type of the search operation.

Values are query_then_fetch or dfs_query_then_fetch.
rest_total_hits_as_int boolean

If true, the response returns hits.total as an integer. If false, it returns hits.total as an object.
typed_keys boolean

If true, the response prefixes aggregation and suggester names with their respective types.

application/json

Body object Required

Contains parameters used to limit or change the subsequent search body request.

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

Only to be used in query and path parameters, as the array form is actually a csv
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

explain boolean

If true, returns detailed information about score calculation as part of each hit.

Default value is false.
id string

The ID of the search template to use. If no source is specified, this parameter is required.
params object

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

If true, the query execution is profiled.

Default value is false.
source string | object

An inline search template. Supports the same parameters as the search API's request body. It also supports Mustache variables. If no id is specified, this parameter is required.
One of:
string-1 string SearchRequestBody object
Hide attributes Show attributes

aggregations object

Defines the aggregations that are run as part of the search request.

External documentation

collapse object

Collapses search results the values of the specified field.

explain boolean

If true, the request returns detailed information about score computation as part of a hit.

Default value is false.

ext object

Configuration of search extensions defined by Elasticsearch plugins.

Hide ext attribute Show ext attribute object

* object Additional properties

from number

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.

Default value is 0.0.

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.

indices_boost array[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

docvalue_fields array[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

A reference to a field with formatting instructions on how to return the value

A reference to a field with formatting instructions on how to return the value

knn object | array[object] Generally available; Added in 8.4.0

The approximate kNN search to run.

External documentation

One of:
KnnSearch object array-2 array[object]

rank object

The Reciprocal Rank Fusion (RRF) to use.

min_score number

The minimum _score for matching documents. Documents with a lower _score are not included in search results or results collected by aggregations.

post_filter object

Use the post_filter parameter to filter search results. The search hits are filtered after the aggregations are calculated. A post filter has no impact on the aggregation results.

profile boolean

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.

Default value is false.

External documentation

query object

The search definition using the Query DSL.

rescore array[object]

retriever object

A retriever is a specification to describe top documents returned from a search. A retriever replaces other elements of the search API that also return top documents such as query and knn.

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

search_after array[number | string | boolean | null]

Used to retrieve the next page of hits using a set of sort values from the previous page.

size number

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.

Default value is 10.0.

slice object

Split a scrolled search into multiple slices that can be consumed independently.

sort

_source

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

A reference to a field with formatting instructions on how to return the value

A reference to a field with formatting instructions on how to return the value

suggest object

Defines a suggester that provides similar looking terms based on a provided text.

terminate_after number

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.

Default value is 0.0.

timeout string

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.

Default value is false.

version boolean

If true, the request returns the document version as part of a hit.

Default value is false.

seq_no_primary_term boolean

If true, the request returns sequence number and primary term of the last modification of each hit.

External documentation

stored_fields string | array[string]

A comma-separated 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 property defaults to false. You can pass _source: true to return both source fields and stored fields in the search response.

pit object

Limit the search to a point in time (PIT). If you provide a PIT, you cannot specify an <index> in the request path.

runtime_mappings object

One or more runtime fields in the search request. These fields take precedence over mapped fields with the same name.

stats array[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
- took number Required
- responses array[object] Required
  
  One of:
  object-2 object 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
  
  A count of shards used for the request.
  
  hits object Required
  
  The returned documents and metadata.
  
  aggregations object
  
  _clusters object
  
  fields object
  
  Hide fields attribute Show fields attribute object
  
  * object Additional properties
  
  max_score number
  
  num_reduce_phases number
  
  profile object
  
  pit_id string
  
  _scroll_id string
  
  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 scroll query parameter is specified in the request.
  
  suggest object
  
  Hide suggest attribute Show suggest attribute object
  
  * array[object] Additional properties
  
  terminated_early boolean
  
  status number
  
  The response returned by Elasticsearch when request execution did not succeed.
  
  Hide attributes Show attributes
  
  error object Required
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  Hide error attributes Show error attributes object
  
  type string Required
  
  The type of error
  
  reason
  
  stack_trace string
  
  The server stack trace. Present only if the error_trace=true parameter was sent with the request.
  
  root_cause array[object]
  
  suppressed array[object]
  
  status number Required

GET /_msearch/template

curl \
 --request GET 'http://api.example.com/_msearch/template' \
 --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" }}