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.
Required authorization
- Index privileges:
read
Query parameters
-
A setting that does two separate checks on the index expression. If
false, the request returns an error (1) if any wildcard expression (including_alland*) resolves to zero matching indices or (2) if the complete set of resolved indices, aliases or data streams is empty after all expressions are evaluated. Iftrue, index expressions that resolve to no indices are allowed and the request returns an empty result. -
If true, network roundtrips between the coordinating node and remote clusters are minimized for cross-cluster search requests.
-
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.
Values are
all,open,closed,hidden, ornone. -
If true, concrete, expanded or aliased indices are ignored when frozen.
-
If
false, the request returns an error if it targets a concrete (non-wildcarded) index, alias, or data stream that is missing, closed, or otherwise unavailable. Iftrue, unavailable concrete targets are silently ignored. -
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.
-
Comma-separated list of data streams, indices, and index aliases to use as default
-
Maximum number of concurrent searches the multi search API can execute. Defaults to
max(1, (# of data nodes * min(search thread pool size, 10))). -
Maximum number of concurrent shard requests that each sub-search request executes per node.
-
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.
-
If true, hits.total are returned as an integer in the response. Defaults to false, which returns an object.
-
Custom routing value used to route search operations to a specific shard.
-
Indicates whether global term and document frequencies should be used when scoring returned documents.
Values are
query_then_fetchordfs_query_then_fetch. -
Specifies whether aggregation and suggester names should be prefixed by their respective types in the response.
Body
object
Required
Contains parameters used to limit or change the subsequent search body request.
-
A setting that does two separate checks on the index expression. If
false, the request returns an error (1) if any wildcard expression (including_alland*) resolves to zero matching indices or (2) if the complete set of resolved indices, aliases or data streams is empty after all expressions are evaluated. Iftrue, index expressions that resolve to no indices are allowed and the request returns an empty result. -
If
false, the request returns an error if it targets a concrete (non-wildcarded) index, alias, or data stream that is missing, closed, or otherwise unavailable. Iftrue, unavailable concrete targets are silently ignored. -
Only to be used in query and path parameters, as the array form is actually a csv
-
Values are
query_then_fetchordfs_query_then_fetch.
-
Defines the aggregations that are run as part of the search request.
External documentation -
Collapses search results the values of the specified field.
Hide collapse attributes Show collapse attributes object
-
If
true, the request returns detailed information about score computation as part of a hit.Default value is
false. -
Configuration of search extensions defined by Elasticsearch plugins.
-
The starting document offset, which must be non-negative. By default, you cannot page through more than 10,000 hits using the
fromandsizeparameters. To page through more hits, use thesearch_afterparameter.Default value is
0.0. -
Specifies the highlighter to use for retrieving highlighted snippets from one or more fields in your search results.
External documentation Hide highlight attributes Show highlight attributes object
-
A string that contains each boundary character.
Default value is
.,!? \t\n. -
How far to scan for boundary characters.
Default value is
20.0. -
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.Values are
chars,sentence, orword. -
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".Default value is
Locale.ROOT. -
Specifies how text should be broken up in highlight snippets:
simpleorspan. Only valid for theplainhighlighter.Values are
simpleorspan. -
The size of the highlighted fragment in characters.
Default value is
100.0. -
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.
-
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. -
The amount of text you want to return from the beginning of the field if there are no matching fragments to highlight.
Default value is
0.0. -
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.Default value is
5.0. -
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.Value is
score. -
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.Default value is
256.0. -
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. -
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. -
By default, only fields that contains a query match are highlighted. Set to
falseto highlight all fields.Default value is
true. -
Set to
styledto use the built-in tag schema.Value is
styled. -
Values are
defaultorhtml.
-
Number of hits matching the query to count accurately. If
true, the exact number of hits is returned at the cost of some performance. Iffalse, the response does not include the total number of hits matching the query. -
Boost the
_scoreof documents from specified indices. The boost value is the factor by which scores are multiplied. A boost value greater than1.0increases the score. A boost value between0and1.0decreases the score.External documentation -
An array of wildcard (
*) field patterns. The request returns doc values for field names matching these patterns in thehits.fieldsproperty of the response.External documentation Hide docvalue_fields attributes Show docvalue_fields attributes object
knn
object | array[object] Generally available; Added in 8.4.0 The approximate kNN search to run.
External documentation One of: Hide attributes Show attributes
-
The name of the vector field to search against
-
The query vector
-
The query vector builder. You must provide a query_vector_builder or query_vector, but not both.
-
The final number of nearest neighbors to return as top hits
-
The number of nearest neighbor candidates to consider per shard
-
The percentage of vectors to explore per shard while doing knn search with bbq_disk
-
Boost value to apply to kNN scores
filter
object | array[object] Filters for the kNN search query
One of: An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
External documentation Hide attributes Show attributes
-
Returns documents that contain terms similar to the search term, as measured by a Levenshtein edit distance.
-
Matches
geo_pointandgeo_shapevalues that intersect a grid cell from a GeoGrid aggregation. -
Returns documents based on the order and proximity of matching terms.
-
Returns documents that match a provided text, number, date or boolean value. The provided text is analyzed before matching.
-
Analyzes its input and constructs a
boolquery from the terms. Each term except the last is used in atermquery. The last term is used in a prefix query. -
Analyzes the text and creates a phrase query out of the analyzed text.
-
Returns documents that contain the words of a provided text, in the same order as provided. The last term of the provided text is treated as a prefix, matching any words that begin with that term.
-
Returns documents that contain a specific prefix in a provided field.
-
Returns documents that contain terms within a provided range.
-
Returns documents that contain terms matching a regular expression.
-
Matches spans containing a term.
-
Returns documents that contain an exact term in a provided field. To return a document, the query term must exactly match the queried field's value, including whitespace and capitalization.
-
Returns documents that contain a minimum number of exact terms in a provided field. To return a document, a required number of terms must exactly match the field values, including whitespace and capitalization.
-
Uses a natural language processing model to convert the query text into a list of token-weight pairs which are then used in a query against a sparse vector or rank features field.
-
Supports returning text_expansion query results by sending in precomputed tokens with the query.
-
Returns documents that contain terms matching a wildcard pattern.
An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
-
The minimum similarity for a vector to be considered a match
-
If defined, each search hit will contain inner hits.
External documentation Hide inner_hits attributes Show inner_hits attributes object
-
The maximum number of hits to return per
inner_hits.Default value is
3.0. -
Inner hit starting document offset.
Default value is
0.0. -
Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
-
Default value is
false.
-
-
Apply oversampling and rescoring to quantized vectors
Hide attributes Show attributes object
-
The name of the vector field to search against
-
The query vector
-
The query vector builder. You must provide a query_vector_builder or query_vector, but not both.
-
The final number of nearest neighbors to return as top hits
-
The number of nearest neighbor candidates to consider per shard
-
The percentage of vectors to explore per shard while doing knn search with bbq_disk
-
Boost value to apply to kNN scores
-
The minimum similarity for a vector to be considered a match
-
If defined, each search hit will contain inner hits.
-
Apply oversampling and rescoring to quantized vectors
-
-
The Reciprocal Rank Fusion (RRF) to use.
-
The minimum
_scorefor matching documents. Documents with a lower_scoreare not included in search results or results collected by aggregations. -
Use the
post_filterparameter to filter search results. The search hits are filtered after the aggregations are calculated. A post filter has no impact on the aggregation results.External documentation Hide post_filter attributes Show post_filter attributes object
-
Returns documents that contain terms similar to the search term, as measured by a Levenshtein edit distance.
External documentation -
Matches
geo_pointandgeo_shapevalues that intersect a grid cell from a GeoGrid aggregation. -
Returns documents based on the order and proximity of matching terms.
External documentation -
Returns documents that match a provided text, number, date or boolean value. The provided text is analyzed before matching.
External documentation -
Analyzes its input and constructs a
boolquery from the terms. Each term except the last is used in atermquery. The last term is used in a prefix query.External documentation -
Analyzes the text and creates a phrase query out of the analyzed text.
External documentation -
Returns documents that contain the words of a provided text, in the same order as provided. The last term of the provided text is treated as a prefix, matching any words that begin with that term.
External documentation -
Returns documents that contain a specific prefix in a provided field.
External documentation -
Returns documents that contain terms within a provided range.
External documentation -
Returns documents that contain terms matching a regular expression.
External documentation -
Matches spans containing a term.
External documentation -
Returns documents that contain an exact term in a provided field. To return a document, the query term must exactly match the queried field's value, including whitespace and capitalization.
External documentation -
Returns documents that contain a minimum number of exact terms in a provided field. To return a document, a required number of terms must exactly match the field values, including whitespace and capitalization.
External documentation -
Uses a natural language processing model to convert the query text into a list of token-weight pairs which are then used in a query against a sparse vector or rank features field.
External documentation -
Supports returning text_expansion query results by sending in precomputed tokens with the query.
External documentation -
Returns documents that contain terms matching a wildcard pattern.
External documentation
-
Set to
trueto 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 -
The search definition using the Query DSL.
External documentation Hide query attributes Show query attributes object
-
Returns documents that contain terms similar to the search term, as measured by a Levenshtein edit distance.
External documentation -
Matches
geo_pointandgeo_shapevalues that intersect a grid cell from a GeoGrid aggregation. -
Returns documents based on the order and proximity of matching terms.
External documentation -
Returns documents that match a provided text, number, date or boolean value. The provided text is analyzed before matching.
External documentation -
Analyzes its input and constructs a
boolquery from the terms. Each term except the last is used in atermquery. The last term is used in a prefix query.External documentation -
Analyzes the text and creates a phrase query out of the analyzed text.
External documentation -
Returns documents that contain the words of a provided text, in the same order as provided. The last term of the provided text is treated as a prefix, matching any words that begin with that term.
External documentation -
Returns documents that contain a specific prefix in a provided field.
External documentation -
Returns documents that contain terms within a provided range.
External documentation -
Returns documents that contain terms matching a regular expression.
External documentation -
Matches spans containing a term.
External documentation -
Returns documents that contain an exact term in a provided field. To return a document, the query term must exactly match the queried field's value, including whitespace and capitalization.
External documentation -
Returns documents that contain a minimum number of exact terms in a provided field. To return a document, a required number of terms must exactly match the field values, including whitespace and capitalization.
External documentation -
Uses a natural language processing model to convert the query text into a list of token-weight pairs which are then used in a query against a sparse vector or rank features field.
External documentation -
Supports returning text_expansion query results by sending in precomputed tokens with the query.
External documentation -
Returns documents that contain terms matching a wildcard pattern.
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
queryandpost_filterphases.External documentation -
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
queryandknn.External documentation -
Retrieve a script evaluation (based on different fields) for each hit.
Hide script_fields attribute Show script_fields attribute object
-
Hide * attributes Show * attributes object
-
-
Used to retrieve the next page of hits using a set of sort values from the previous page.
-
The number of hits to return, which must not be negative. By default, you cannot page through more than 10,000 hits using the
fromandsizeparameters. To page through more hits, use thesearch_afterproperty.Default value is
10.0. -
Split a scrolled search into multiple slices that can be consumed independently.
External documentation sort
string | object | array[string | object] A comma-separated list of : pairs.
External documentation One of: Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
External documentation _source
boolean | object The source fields that are returned for matching documents. These fields are returned in the
hits._sourceproperty of the search response. If thestored_fieldsproperty is specified, the_sourceproperty defaults tofalse. Otherwise, it defaults totrue.External documentation One of: External documentation Hide attributes Show attributes
-
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 anincludesrule. -
A list of fields to exclude from the returned source.
-
A list of fields to include in the returned source.
-
-
An array of wildcard (
*) field patterns. The request returns values for field names matching these patterns in thehits.fieldsproperty of the response.Hide fields attributes Show fields attributes object
-
Defines a suggester that provides similar looking terms based on a provided text.
External documentation -
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. -
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.
-
If
true, calculate and return document scores, even if the scores are not used for sorting.Default value is
false. -
If
true, the request returns the document version as part of a hit.Default value is
false. -
If
true, the request returns sequence number and primary term of the last modification of each hit.External documentation -
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
_sourceproperty defaults tofalse. You can pass_source: trueto return both source fields and stored fields in the search response. -
Limit the search to a point in time (PIT). If you provide a PIT, you cannot specify an
<index>in the request path.Hide pit attributes Show pit attributes object
-
A duration. Units can be
nanos,micros,ms(milliseconds),s(seconds),m(minutes),h(hours) andd(days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.External documentation
-
One or more runtime fields in the search request. These fields take precedence over mapped fields with the same name.
External documentation Hide runtime_mappings attribute Show runtime_mappings attribute object
-
Hide * attributes Show * attributes object
-
For type
composite -
For type
lookup -
A custom format for
datetype runtime fields. -
For type
lookup -
For type
lookup -
For type
lookup -
Painless script executed at query time.
-
Field type, which can be:
boolean,composite,date,double,geo_point,ip,keyword,long, orlookup.Values are
boolean,composite,date,double,geo_point,geo_shape,ip,keyword,long, orlookup.
-
-
-
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
-
Hide response attributes Show response attributes object
-
One of: Hide attributes Show attributes
-
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
-
If
true, the request timed out before completion; returned results may be partial or empty. -
A count of shards used for the request.
-
The returned documents and metadata.
-
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.
The response returned by Elasticsearch when request execution did not succeed.
Hide attributes Show attributes
-
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.
-
curl \
--request GET 'http://api.example.com/_msearch' \
--header "Content-Type: application/json" \
--data '"{ }\n{\"query\" : {\"match\" : { \"message\": \"this is a test\"}}}\n{\"index\": \"my-index-000002\"}\n{\"query\" : {\"match_all\" : {}}}"'{ }
{"query" : {"match" : { "message": "this is a test"}}}
{"index": "my-index-000002"}
{"query" : {"match_all" : {}}}