Run multiple templated searches | Elasticsearch API documentation

Run multiple templated searches Generally available; Added in 5.0.0

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

External documentation

Path parameters

index string | array[string] Required

A comma-separated list of data streams, indices, and aliases to search. It supports wildcards (*). To search all data streams and indices, omit this parameter or use *.

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

explain boolean

If true, returns detailed information about score calculation as part of each hit.
id string
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.
source string | object
One of:
ScriptSource 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
External documentation

explain boolean

If true, the request 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

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.

highlight object

Hide highlight attributes Show highlight attributes object

type

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.

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

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

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.

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

Hide indices_boost attribute Show indices_boost attribute object

* number Additional properties

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.

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

External documentation

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]

The approximate kNN search to run.

One of:
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

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

similarity number

The minimum similarity for a vector to be considered a match

inner_hits object

rescore_vector object

External documentation

rank object

Hide rank attribute Show rank attribute object

rrf object

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

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

External documentation

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.

query object

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

External documentation

rescore object | 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:
Rescore object array-2 array[object]

retriever object

Hide retriever attributes Show retriever attributes object

standard object

knn object

rrf object

text_similarity_reranker object

rule object

rescorer object

linear object

pinned 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

ignore_failure boolean

search_after array[number | string | boolean | null]

A field value.

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.

slice object

Hide slice attributes Show slice attributes object

field string

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

id string Required

max number Required

sort string | object | array[string | object]

One of:
Field string SortOptions object Sort array[string | 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:
SourceConfig boolean SourceFilter object

Hide attributes Show attributes

exclude_vectors boolean

If true, vector fields are excluded from the returned source.

This option takes precedence over includes: any vector field will remain excluded even if it matches an includes rule.

excludes string | array[string]

includes string | array[string]

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

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

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

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.

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.

version boolean

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

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]

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.

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

fetch_fields array[object]

For type lookup

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

type string Required

Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.

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:
  MultiSearchItem 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
  
  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
  
  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 string | null
  
  A human-readable explanation of the error, in English.
  
  One of:
  string-1 string string-2 string | null
  
  stack_trace string
  
  The server stack trace. Present only if the error_trace=true parameter was sent with the request.
  
  caused_by object
  
  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.
  
  root_cause array[object]
  
  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.
  
  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.
  
  suppressed array[object]
  
  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.
  
  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.
  
  status number Required

POST /{index}/_msearch/template

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

resp = client.msearch_template(
    index="my-index",
    search_templates=[
        {},
        {
            "id": "my-search-template",
            "params": {
                "query_string": "hello world",
                "from": 0,
                "size": 10
            }
        },
        {},
        {
            "id": "my-other-search-template",
            "params": {
                "query_type": "match_all"
            }
        }
    ],
)

const response = await client.msearchTemplate({
  index: "my-index",
  search_templates: [
    {},
    {
      id: "my-search-template",
      params: {
        query_string: "hello world",
        from: 0,
        size: 10,
      },
    },
    {},
    {
      id: "my-other-search-template",
      params: {
        query_type: "match_all",
      },
    },
  ],
});

response = client.msearch_template(
  index: "my-index",
  body: [
    {},
    {
      "id": "my-search-template",
      "params": {
        "query_string": "hello world",
        "from": 0,
        "size": 10
      }
    },
    {},
    {
      "id": "my-other-search-template",
      "params": {
        "query_type": "match_all"
      }
    }
  ]
)

$resp = $client->msearchTemplate([
    "index" => "my-index",
    "body" => array(
        new ArrayObject([]),
        [
            "id" => "my-search-template",
            "params" => [
                "query_string" => "hello world",
                "from" => 0,
                "size" => 10,
            ],
        ],
        new ArrayObject([]),
        [
            "id" => "my-other-search-template",
            "params" => [
                "query_type" => "match_all",
            ],
        ],
    ),
]);

curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '[{},{"id":"my-search-template","params":{"query_string":"hello world","from":0,"size":10}},{},{"id":"my-other-search-template","params":{"query_type":"match_all"}}]' "$ELASTICSEARCH_URL/my-index/_msearch/template"

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