Run a search
Get search hits that match the query defined in the request.
You can provide search queries using the q
query string parameter or the request body.
If both are specified, only the query parameter is used.
Path parameters
-
Comma-separated list of data streams, indices, and aliases to search. Supports wildcards (
*
). To search all data streams and indices, omit this parameter or use*
or_all
.
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 targetingfoo*,bar*
returns an error if an index starts withfoo
but no index starts withbar
. -
allow_partial_search_results boolean
If true, returns partial results if there are shard request timeouts or shard failures. If false, returns an error with no partial results.
-
analyzer string
Analyzer to use for the query string. This parameter can only be used when the q query string parameter is specified.
-
analyze_wildcard boolean
If true, wildcard and prefix queries are analyzed. This parameter can only be used when the q query string parameter is specified.
-
batched_reduce_size number
The number of shard results that should be reduced at once on the coordinating node. This value should be used as a protection mechanism to reduce the memory overhead per search request if the potential number of shards in the request can be large.
-
ccs_minimize_roundtrips boolean
If true, network round-trips between the coordinating node and the remote clusters are minimized when executing cross-cluster search (CCS) requests.
-
default_operator string
The default operator for query string query: AND or OR. This parameter can only be used when the
q
query string parameter is specified.Values are
and
,AND
,or
, orOR
. -
df string
Field to use as default where no field prefix is given in the query string. This parameter can only be used when the q query string parameter is specified.
-
docvalue_fields string | array[string]
A comma-separated list of fields to return as the docvalue representation for each hit.
-
expand_wildcards string | array[string]
Type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. Supports comma-separated values, such as
open,hidden
. -
explain boolean
If
true
, returns detailed information about score computation as part of a hit. -
ignore_throttled boolean
If
true
, concrete, expanded or aliased indices will be ignored when frozen. -
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.
-
lenient boolean
If
true
, format-based query failures (such as providing text to a numeric field) in the query string will be ignored. This parameter can only be used when theq
query string parameter is specified. -
Defines the number of concurrent shard requests per node this search executes concurrently. This value should be used to limit the impact of the search on the cluster in order to limit the number of concurrent shard requests.
-
preference string
Nodes and shards used for the search. By default, Elasticsearch selects from eligible nodes and shards using adaptive replica selection, accounting for allocation awareness. Valid values are:
_only_local
to run the search only on shards on the local node;_local
to, if possible, run the search on shards on the local node, or if not, select shards using the default method;_only_nodes:<node-id>,<node-id>
to run the search on only the specified nodes IDs, where, if suitable shards exist on more than one selected node, use shards on those nodes using the default method, or if none of the specified nodes are available, select shards from any available node using the default method;_prefer_nodes:<node-id>,<node-id>
to if possible, run the search on the specified nodes IDs, or if not, select shards using the default method;_shards:<shard>,<shard>
to run the search only on the specified shards;<custom-string>
(any string that does not start with_
) to route searches with the same<custom-string>
to the same shards in the same order. -
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 (if date filters are mandatory to match but the shard bounds and the query are disjoint). When unspecified, the pre-filter phase is executed if any of these conditions is met: the request targets more than 128 shards; the request targets one or more read-only index; the primary sort of the query targets an indexed field.
-
request_cache boolean
If
true
, the caching of search results is enabled for requests wheresize
is0
. Defaults to index level settings. -
routing string
Custom value used to route operations to a specific shard.
-
scroll string
Period to retain the search context for scrolling. See Scroll search results. By default, this value cannot exceed
1d
(24 hours). You can change this limit using thesearch.max_keep_alive
cluster-level setting. -
search_type string
How distributed term frequencies are calculated for relevance scoring.
Values are
query_then_fetch
ordfs_query_then_fetch
. -
stats array[string]
Specific
tag
of the request for logging and statistical purposes. -
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
parameter defaults tofalse
. You can pass_source: true
to return both source fields and stored fields in the search response. -
suggest_field string
Specifies which field to use for suggestions.
-
suggest_mode string
Specifies the suggest mode. This parameter can only be used when the
suggest_field
andsuggest_text
query string parameters are specified.Values are
missing
,popular
, oralways
. -
suggest_size number
Number of suggestions to return. This parameter can only be used when the
suggest_field
andsuggest_text
query string parameters are specified. -
suggest_text string
The source text for which the suggestions should be returned. This parameter can only be used when the
suggest_field
andsuggest_text
query string parameters are specified. -
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. Use with caution. Elasticsearch applies this parameter to each shard handling the request. When possible, let Elasticsearch perform early termination automatically. Avoid specifying this parameter 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
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.
-
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. Iffalse
, the response does not include the total number of hits matching the query. -
track_scores boolean
If
true
, calculate and return document scores, even if the scores are not used for sorting. -
typed_keys boolean
If
true
, aggregation and suggester names are be prefixed by their respective types in the response. -
rest_total_hits_as_int boolean
Indicates whether
hits.total
should be rendered as an integer or an object in the rest search response. -
version boolean
If
true
, returns document version as part of a hit. -
_source boolean | string | array[string]
Indicates which source fields are returned for matching documents. These fields are returned in the
hits._source
property of the search response. Valid values are:true
to return the entire document source;false
to not return the document source;<string>
to return the source fields that are specified as a comma-separated list (supports wildcard (*
) patterns). -
_source_excludes string | array[string]
A comma-separated list of source fields to exclude from the response. You can also use this parameter to exclude fields from the subset specified in
_source_includes
query parameter. If the_source
parameter isfalse
, this parameter is ignored. -
_source_includes string | array[string]
A comma-separated list of source fields to include in the response. If this parameter is specified, only these source fields are returned. You can exclude fields from this subset using the
_source_excludes
query parameter. If the_source
parameter isfalse
, this parameter is ignored. -
seq_no_primary_term boolean
If
true
, returns sequence number and primary term of the last modification of each hit. -
q string
Query in the Lucene query string syntax using query parameter search. Query parameter searches do not support the full Elasticsearch Query DSL but are handy for testing.
-
size number
Defines the number of hits to return. By default, you cannot page through more than 10,000 hits using the
from
andsize
parameters. To page through more hits, use thesearch_after
parameter. -
from number
Starting document offset. Needs to be non-negative. By default, you cannot page through more than 10,000 hits using the
from
andsize
parameters. To page through more hits, use thesearch_after
parameter. -
sort string | array[string]
A comma-separated list of
: pairs. -
force_synthetic_source boolean
Should this request force synthetic _source? Use this to test if the mapping supports synthetic _source and to get a sense of the worst case performance. Fetches with this enabled will be slower the enabling synthetic source natively in the index.
Body
-
aggregations object
Defines the aggregations that are run as part of the search request.
-
collapse object
Additional properties are allowed.
-
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.
-
from number
Starting document offset. Needs to be non-negative. By default, you cannot page through more than 10,000 hits using the
from
andsize
parameters. To page through more hits, use thesearch_after
parameter. -
highlight object
Additional properties are allowed.
-
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]
Boosts the _score of documents from specified indices.
-
docvalue_fields array[object]
Array of wildcard (
*
) patterns. The request returns doc values for field names matching these patterns in thehits.fields
property of the response. knn object | array[object]
Defines the approximate kNN search to run.
-
rank object
Additional properties are allowed.
-
min_score number
Minimum
_score
for matching documents. Documents with a lower_score
are not included in the search results. -
post_filter object
Additional properties are allowed.
-
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
Additional properties are allowed.
rescore object | array[object]
Can be used to improve precision by reordering just the top (for example 100 - 500) documents returned by the
query
andpost_filter
phases.-
retriever object
Additional properties are allowed.
-
script_fields object
Retrieve a script evaluation (based on different fields) for each hit.
-
search_after array[number | string | boolean | null | object]
A field value.
One of: Additional properties are allowed.
-
size number
The number of hits to return. By default, you cannot page through more than 10,000 hits using the
from
andsize
parameters. To page through more hits, use thesearch_after
parameter. -
slice object
Additional properties are allowed.
_source boolean | object
Defines how to fetch a source. Fetching can be disabled entirely, or the source can be filtered.
-
fields array[object]
Array of wildcard (
*
) patterns. The request returns values for field names matching these patterns in thehits.fields
property of the response. -
suggest object
Additional properties are allowed.
-
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. Use with caution. Elasticsearch applies this parameter to each shard handling the request. When possible, let Elasticsearch perform early termination automatically. Avoid specifying this parameter 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
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.
-
version boolean
If true, returns document version as part of a hit.
-
seq_no_primary_term boolean
If
true
, returns sequence number and primary term of the last modification of each hit. -
stored_fields string | array[string]
-
pit object
Additional properties are allowed.
-
runtime_mappings object
-
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.
curl \
-X POST http://api.example.com/{index}/_search \
-H "Content-Type: application/json" \
-d '{"aggregations":{},"collapse":{},"explain":true,"ext":{"additionalProperty1":{},"additionalProperty2":{}},"from":42.0,"":true,"track_total_hits":true,"indices_boost":[{"additionalProperty1":42.0,"additionalProperty2":42.0}],"docvalue_fields":[{"field":"string","format":"string","include_unmapped":true}],"knn":{"field":"string","query_vector":[42.0],"query_vector_builder":{"text_embedding":{"model_id":"string","model_text":"string"}},"k":42.0,"num_candidates":42.0,"boost":42.0,"filter":{},"similarity":42.0,"inner_hits":{"name":"string","size":42.0,"from":42.0,"collapse":{},"docvalue_fields":[{"field":"string","format":"string","include_unmapped":true}],"explain":true,"":true,"ignore_unmapped":true,"script_fields":{"additionalProperty1":{"script":{"source":"string","id":"string","params":{},"options":{}},"ignore_failure":true},"additionalProperty2":{"script":{"source":"string","id":"string","params":{},"options":{}},"ignore_failure":true}},"seq_no_primary_term":true,"fields":"string","stored_fields":"string","track_scores":true,"version":true}},"rank":{"":{"rank_constant":42.0,"rank_window_size":42.0}},"min_score":42.0,"post_filter":{},"profile":true,"query":{},"retriever":{"":{"filter":{},"min_score":42.0,"ruleset_ids":["string"],"match_criteria":{},"retriever":{},"rank_window_size":42.0}},"script_fields":{"additionalProperty1":{"script":{"source":"string","id":"string","params":{"additionalProperty1":{},"additionalProperty2":{}},"":"painless","options":{"additionalProperty1":"string","additionalProperty2":"string"}},"ignore_failure":true},"additionalProperty2":{"script":{"source":"string","id":"string","params":{"additionalProperty1":{},"additionalProperty2":{}},"":"painless","options":{"additionalProperty1":"string","additionalProperty2":"string"}},"ignore_failure":true}},"search_after":[42.0],"size":42.0,"slice":{"field":"string","id":"string","max":42.0},"fields":[{"field":"string","format":"string","include_unmapped":true}],"suggest":{"text":"string"},"terminate_after":42.0,"timeout":"string","track_scores":true,"version":true,"seq_no_primary_term":true,"stored_fields":"string","pit":{"id":"string","keep_alive":"string"},"runtime_mappings":{"additionalProperty1":{"fields":{"additionalProperty1":{"type":"boolean"},"additionalProperty2":{"type":"boolean"}},"fetch_fields":[{"field":"string","format":"string"}],"format":"string","input_field":"string","target_field":"string","target_index":"string","script":{"source":"string","id":"string","params":{"additionalProperty1":{},"additionalProperty2":{}},"":"painless","options":{"additionalProperty1":"string","additionalProperty2":"string"}},"type":"boolean"},"additionalProperty2":{"fields":{"additionalProperty1":{"type":"boolean"},"additionalProperty2":{"type":"boolean"}},"fetch_fields":[{"field":"string","format":"string"}],"format":"string","input_field":"string","target_field":"string","target_index":"string","script":{"source":"string","id":"string","params":{"additionalProperty1":{},"additionalProperty2":{}},"":"painless","options":{"additionalProperty1":"string","additionalProperty2":"string"}},"type":"boolean"}},"stats":["string"]}'
{
"aggregations": {},
"collapse": {},
"explain": true,
"ext": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"from": 42.0,
"": true,
"track_total_hits": true,
"indices_boost": [
{
"additionalProperty1": 42.0,
"additionalProperty2": 42.0
}
],
"docvalue_fields": [
{
"field": "string",
"format": "string",
"include_unmapped": true
}
],
"knn": {
"field": "string",
"query_vector": [
42.0
],
"query_vector_builder": {
"text_embedding": {
"model_id": "string",
"model_text": "string"
}
},
"k": 42.0,
"num_candidates": 42.0,
"boost": 42.0,
"filter": {},
"similarity": 42.0,
"inner_hits": {
"name": "string",
"size": 42.0,
"from": 42.0,
"collapse": {},
"docvalue_fields": [
{
"field": "string",
"format": "string",
"include_unmapped": true
}
],
"explain": true,
"": true,
"ignore_unmapped": true,
"script_fields": {
"additionalProperty1": {
"script": {
"source": "string",
"id": "string",
"params": {},
"options": {}
},
"ignore_failure": true
},
"additionalProperty2": {
"script": {
"source": "string",
"id": "string",
"params": {},
"options": {}
},
"ignore_failure": true
}
},
"seq_no_primary_term": true,
"fields": "string",
"stored_fields": "string",
"track_scores": true,
"version": true
}
},
"rank": {
"": {
"rank_constant": 42.0,
"rank_window_size": 42.0
}
},
"min_score": 42.0,
"post_filter": {},
"profile": true,
"query": {},
"retriever": {
"": {
"filter": {},
"min_score": 42.0,
"ruleset_ids": [
"string"
],
"match_criteria": {},
"retriever": {},
"rank_window_size": 42.0
}
},
"script_fields": {
"additionalProperty1": {
"script": {
"source": "string",
"id": "string",
"params": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"": "painless",
"options": {
"additionalProperty1": "string",
"additionalProperty2": "string"
}
},
"ignore_failure": true
},
"additionalProperty2": {
"script": {
"source": "string",
"id": "string",
"params": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"": "painless",
"options": {
"additionalProperty1": "string",
"additionalProperty2": "string"
}
},
"ignore_failure": true
}
},
"search_after": [
42.0
],
"size": 42.0,
"slice": {
"field": "string",
"id": "string",
"max": 42.0
},
"fields": [
{
"field": "string",
"format": "string",
"include_unmapped": true
}
],
"suggest": {
"text": "string"
},
"terminate_after": 42.0,
"timeout": "string",
"track_scores": true,
"version": true,
"seq_no_primary_term": true,
"stored_fields": "string",
"pit": {
"id": "string",
"keep_alive": "string"
},
"runtime_mappings": {
"additionalProperty1": {
"fields": {
"additionalProperty1": {
"type": "boolean"
},
"additionalProperty2": {
"type": "boolean"
}
},
"fetch_fields": [
{
"field": "string",
"format": "string"
}
],
"format": "string",
"input_field": "string",
"target_field": "string",
"target_index": "string",
"script": {
"source": "string",
"id": "string",
"params": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"": "painless",
"options": {
"additionalProperty1": "string",
"additionalProperty2": "string"
}
},
"type": "boolean"
},
"additionalProperty2": {
"fields": {
"additionalProperty1": {
"type": "boolean"
},
"additionalProperty2": {
"type": "boolean"
}
},
"fetch_fields": [
{
"field": "string",
"format": "string"
}
],
"format": "string",
"input_field": "string",
"target_field": "string",
"target_index": "string",
"script": {
"source": "string",
"id": "string",
"params": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"": "painless",
"options": {
"additionalProperty1": "string",
"additionalProperty2": "string"
}
},
"type": "boolean"
}
},
"stats": [
"string"
]
}
{
"took": 42.0,
"timed_out": true,
"_shards": {
"failed": 42.0,
"successful": 42.0,
"total": 42.0,
"failures": [
{
"index": "string",
"node": "string",
"reason": {
"type": "string",
"reason": "string",
"stack_trace": "string",
"caused_by": {},
"root_cause": [
{}
],
"suppressed": [
{}
]
},
"shard": 42.0,
"status": "string"
}
],
"skipped": 42.0
},
"hits": {
"total": {
"relation": "eq",
"value": 42.0
},
"hits": [
{
"_index": "string",
"_id": "string",
"_score": 42.0,
"_explanation": {
"description": "string",
"details": [
{}
],
"value": 42.0
},
"fields": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"highlight": {
"additionalProperty1": [
"string"
],
"additionalProperty2": [
"string"
]
},
"inner_hits": {
"additionalProperty1": {
"hits": {}
},
"additionalProperty2": {
"hits": {}
}
},
"matched_queries": [
"string"
],
"_nested": {
"field": "string",
"offset": 42.0,
"_nested": {}
},
"_ignored": [
"string"
],
"ignored_field_values": {
"additionalProperty1": [
{}
],
"additionalProperty2": [
{}
]
},
"_shard": "string",
"_node": "string",
"_routing": "string",
"_source": {},
"_rank": 42.0,
"_seq_no": 42.0,
"_primary_term": 42.0,
"_version": 42.0,
"sort": [
42.0
]
}
],
"max_score": 42.0
},
"aggregations": {},
"_clusters": {
"skipped": 42.0,
"successful": 42.0,
"total": 42.0,
"running": 42.0,
"partial": 42.0,
"failed": 42.0,
"details": {
"additionalProperty1": {
"status": "running",
"indices": "string",
"": 42.0,
"timed_out": true,
"_shards": {
"failed": 42.0,
"successful": 42.0,
"total": 42.0,
"failures": [
{}
],
"skipped": 42.0
},
"failures": [
{
"index": "string",
"node": "string",
"reason": {},
"shard": 42.0,
"status": "string"
}
]
},
"additionalProperty2": {
"status": "running",
"indices": "string",
"": 42.0,
"timed_out": true,
"_shards": {
"failed": 42.0,
"successful": 42.0,
"total": 42.0,
"failures": [
{}
],
"skipped": 42.0
},
"failures": [
{
"index": "string",
"node": "string",
"reason": {},
"shard": 42.0,
"status": "string"
}
]
}
}
},
"fields": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"max_score": 42.0,
"num_reduce_phases": 42.0,
"profile": {
"shards": [
{
"aggregations": [
{
"breakdown": {},
"description": "string",
"type": "string",
"debug": {},
"children": [
{}
]
}
],
"cluster": "string",
"dfs": {
"statistics": {
"type": "string",
"description": "string",
"time": "string",
"breakdown": {},
"debug": {},
"children": [
{}
]
},
"knn": [
{}
]
},
"fetch": {
"type": "string",
"description": "string",
"": 42.0,
"breakdown": {
"load_source": 42.0,
"load_source_count": 42.0,
"load_stored_fields": 42.0,
"load_stored_fields_count": 42.0,
"next_reader": 42.0,
"next_reader_count": 42.0,
"process_count": 42.0,
"process": 42.0
},
"debug": {
"stored_fields": [
"string"
],
"fast_path": 42.0
},
"children": [
{}
]
},
"id": "string",
"index": "string",
"node_id": "string",
"searches": [
{
"collector": [
{}
],
"query": [
{}
],
"rewrite_time": 42.0
}
],
"shard_id": 42.0
}
]
},
"pit_id": "string",
"_scroll_id": "string",
"suggest": {
"additionalProperty1": [
{
"length": 42.0,
"offset": 42.0,
"text": "string"
}
],
"additionalProperty2": [
{
"length": 42.0,
"offset": 42.0,
"text": "string"
}
]
},
"terminated_early": true
}