All methods and paths for this operation:
Get search hits that match the query defined in the request.You can provide search queries using theq query string parameter or the request body.If both are specified, only the query parameter is used.
If the Elasticsearch security features are enabled, you must have the read index privilege for the target data stream, index, or alias. For cross-cluster search, refer to the documentation about configuring CCS privileges.To search a point in time (PIT) for an alias, you must have theread index privilege for the alias's data streams or indices.
Search slicing
When paging through a large number of documents, it can be helpful to split the search into multiple slices to consume them independently with theslice andpit properties.By default the splitting is done first on the shards, then locally on each shard.The local splitting partitions the shard into contiguous ranges based on Lucene document IDs.
For instance if the number of shards is equal to 2 and you request 4 slices, the slices 0 and 2 are assigned to the first shard and the slices 1 and 3 are assigned to the second shard.
IMPORTANT: The same point-in-time ID should be used for all slices.If different PIT IDs are used, slices can overlap and miss documents.This situation can occur because the splitting criterion is based on Lucene document IDs, which are not stable across changes to the index.
readA 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* or_all.
Iffalse, 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.
Iftrue and there are shard request timeouts or shard failures, the request returns partial results.Iffalse, it returns an error with no partial results.
To override the default behavior, you can set thesearch.default_allow_partial_results cluster setting tofalse.
The analyzer to use for the query string.This parameter can be used only when theq query string parameter is specified.
Iftrue, wildcard and prefix queries are analyzed.This parameter can be used only when theq query string parameter is specified.
The number of shard results that should be reduced at once on the coordinating node.If the potential number of shards in the request can be large, this value should be used as a protection mechanism to reduce the memory overhead per search request.
Iftrue, network round-trips between the coordinating node and the remote clusters are minimized when running cross-cluster search (CCS) requests.
The default operator for the query string query:and oror.This parameter can be used only when theq query string parameter is specified.
Values areand,AND,or, orOR.
The field to use as a default when no field prefix is given in the query string.This parameter can be used only when theq query string parameter is specified.
A comma-separated list of fields to return as the docvalue representation of a field for each hit.
The 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.It supports comma-separated values such asopen,hidden.
Supported values include:
all: Match any data stream or index, including hidden ones.open: Match open, non-hidden indices. Also matches any non-hidden data stream.closed: Match closed, non-hidden indices. Also matches any non-hidden data stream. Data streams cannot be closed.hidden: Match hidden data streams and hidden indices. Must be combined withopen,closed, orboth.none: Wildcard expressions are not accepted.Values areall,open,closed,hidden, ornone.
Iftrue, the request returns detailed information about score computation as part of a hit.
Iftrue, concrete, expanded or aliased indices will be ignored when frozen.
Iffalse, the request returns an error if it targets a missing or closed index.
Iftrue, the response includes the score contribution from any named queries.
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.
Iftrue, format-based query failures (such as providing text to a numeric field) in the query string will be ignored.This parameter can be used only when theq query string parameter is specified.
The number of concurrent shard requests per node that the search runs 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.
The 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. If suitable shards exist on more than one selected node, use shards on those nodes using the default method. 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. If not, select shards using the default method._shards:<shard>,<shard> to run the search only on the specified shards. You can combine this value with otherpreference values. However, the_shards value must come first. For example:_shards:2,3|_local.<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.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:
Iftrue, the caching of search results is enabled for requests wheresize is0.It defaults to index level settings.
A custom value that is used to route operations to a specific shard.
The period to retain the search context for scrolling.By default, this value cannot exceed1d (24 hours).You can change this limit by using thesearch.max_keep_alive cluster-level setting.
Indicates how distributed term frequencies are calculated for relevance scoring.
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 arequery_then_fetch ordfs_query_then_fetch.
Specifictag of the request for logging and statistical purposes.
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.
The field to use for suggestions.
The suggest mode.This parameter can be used only when thesuggest_field andsuggest_text query string parameters are specified.
Supported values include:
missing: Only generate suggestions for terms that are not in the shard.popular: Only suggest terms that occur in more docs on the shard than the original term.always: Suggest any matching suggestions based on terms in the suggest text.Values aremissing,popular, oralways.
The number of suggestions to return.This parameter can be used only when thesuggest_field andsuggest_text query string parameters are specified.
The source text for which the suggestions should be returned.This parameter can be used only when thesuggest_field andsuggest_text query string parameters are specified.
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 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 to0 (default), the query does not terminate early.
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.It defaults to no timeout.
The number of hits matching the query to count accurately.Iftrue, 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.
Iftrue, the request calculates and returns document scores, even if the scores are not used for sorting.
Iftrue, aggregation and suggester names are be prefixed by their respective types in the response.
Indicates whetherhits.total should be rendered as an integer or an object in the rest search response.
Iftrue, the request returns the document version as part of a hit.
The source fields that are returned for matching documents.These fields are returned in thehits._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 that supports wildcard (*) patterns.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.
Whether vectors should be excluded from _source
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.
Iftrue, the request returns the sequence number and primary term of the last modification of each hit.
A query in the Lucene query string syntax.Query parameter searches do not support the full Elasticsearch Query DSL but are handy for testing.
IMPORTANT: This parameter overrides the query parameter in the request body.If both parameters are specified, documents matching the query request body parameter are not returned.
The number of hits to return.By default, you cannot page through more than 10,000 hits using thefrom andsize parameters.To page through more hits, use thesearch_after parameter.
The starting document offset, which must be non-negative.By default, you cannot page through more than 10,000 hits using thefrom andsize parameters.To page through more hits, use thesearch_after parameter.
A comma-separated list of<field>:<direction> pairs.
Defines the aggregations that are run as part of the search request.
Collapses search results the values of the specified field.
Iftrue, the request returns detailed information about score computation as part of a hit.
Default value isfalse.
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 thefrom andsize parameters.To page through more hits, use thesearch_after parameter.
Default value is0.
Specifies the highlighter to use for retrieving highlighted snippets from one or more fields in your search results.
A string that contains each boundary character.
Default value is.,!? \t\n.
How far to scan for boundary characters.
Default value is20.
Specifies how to break the highlighted fragments: chars, sentence, or word.Only valid for the unified and fvh highlighters.Defaults tosentence for theunified highlighter. Defaults tochars for thefvh highlighter.
Supported values include:
chars: Use the characters specified byboundary_chars as highlighting boundaries.Theboundary_max_scan setting controls how far to scan for boundary characters.Only valid for thefvh highlighter.sentence: Break highlighted fragments at the next sentence boundary, as determined by Java’sBreakIterator.You can specify the locale to use withboundary_scanner_locale.When used with theunified highlighter, thesentence scanner splits sentences bigger thanfragment_size at the first word boundary next to fragment_size.You can setfragment_size to0 to never split any sentence.word: Break highlighted fragments at the next word boundary, as determined by Java’sBreakIterator.You can specify the locale to use withboundary_scanner_locale.Values arechars,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 isLocale.ROOT.
Specifies how text should be broken up in highlight snippets:simple orspan.Only valid for theplain highlighter.
Values aresimple orspan.
The size of the highlighted fragment in characters.
Default value is100.
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 returnedThemax_analyzed_offset query setting does not override theindex.highlight.max_analyzed_offset setting, 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 is0.
The maximum number of fragments to return.If the number of fragments is set to0, 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_fragments is0,fragment_size is ignored.
Default value is5.
Sorts highlighted fragments by score when set toscore.By default, fragments will be output in the order they appear in the field (order:none).Setting this option toscore will output the most relevant fragments first.Each highlighter applies its own logic to compute relevancy scores.
Value isscore.
Controls the number of matching phrases in a document that are considered.Prevents thefvh highlighter from analyzing too many phrases and consuming too much memory.When usingmatched_fields,phrase_limit phrases per matched field are considered. Raising the limit increases query time and consumes more memory.Only supported by thefvh highlighter.
Default value is256.
Use in conjunction withpre_tags to define the HTML tags to use for the highlighted text.By default, highlighted text is wrapped in<em> and</em> tags.
Use in conjunction withpost_tags to 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 tofalse to highlight all fields.
Default value istrue.
Set tostyled to use the built-in tag schema.
Value isstyled.
Values aredefault orhtml.
Number of hits matching the query to count accurately.Iftrue, 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_score of documents from specified indices.The boost value is the factor by which scores are multiplied.A boost value greater than1.0 increases the score.A boost value between0 and1.0 decreases the score.
An array of wildcard (*) field patterns.The request returns doc values for field names matching these patterns in thehits.fields property of the response.
A reference to a field with formatting instructions on how to return the value
The approximate kNN search to run.
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
Filters for the kNN search query
An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
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.
The name for the particular inner hit definition in the response.Useful when a search request contains multiple inner hits.
The maximum number of hits to return perinner_hits.
Default value is3.
Inner hit starting document offset.
Default value is0.
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
Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
Default value isfalse.
Apply oversampling and rescoring to quantized vectors
The Reciprocal Rank Fusion (RRF) to use.
The minimum_score for matching documents.Documents with a lower_score are not included in search results and results collected by aggregations.
Use thepost_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.
Set totrue 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 isfalse.
The search definition using the Query DSL.
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 asquery andknn.
A retriever that replaces the functionality of a traditional query.
Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
Retriever name.
Defines a query to retrieve a set of top documents.
Defines a search after object parameter used for pagination.
Maximum number of documents to collect for each shard.
Collapses the top documents by a specified key into a single top document per key.
A retriever that replaces the functionality of a knn search.
Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
Retriever name.
The name of the vector field to search against.
Query vector. Must have the same number of dimensions as the vector field you are searching against. You must provide a query_vector_builder or query_vector, but not both.
Defines a model to build a query vector.
Number of nearest neighbors to return as top hits.
Number of nearest neighbor candidates to consider per shard.
The percentage of vectors to explore per shard while doing knn search with bbq_disk
The minimum similarity required for a document to be considered a match.
Apply oversampling and rescoring to quantized vectors
A retriever that produces top documents from reciprocal rank fusion (RRF).
Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
Retriever name.
A list of child retrievers to specify which sets of returned top documents will have the RRF formula applied to them. Each retriever can optionally include a weight parameter.
Either a direct RetrieverContainer (backward compatible) or an RRFRetrieverComponent with weight.
This value determines how much influence documents in individual result sets per query have over the final ranked result set.
This value determines the size of the individual result sets per query.
A retriever that reranks the top documents based on a reranking model using the InferenceAPI
Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
Retriever name.
The nested retriever which will produce the first-level results, that will later be used for reranking.
This value determines how many documents we will consider from the nested retriever.
Unique identifier of the inference endpoint created using the inference API.
The text snippet used as the basis for similarity comparison.
The document field to be used for text similarity comparisons. This field should contain the text that will be evaluated against the inference_text.
Whether to rescore on only the best matching chunks.
A retriever that replaces the functionality of a rule query.
Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
Retriever name.
The match criteria that will determine if a rule in the provided rulesets should be applied.
The retriever whose results rules should be applied to.
This value determines the size of the individual result set.
A retriever that re-scores only the results produced by its child retriever.
Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
Retriever name.
Inner retriever.
A retriever that supports the combination of different retrievers through a weighted linear combination.
Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
Retriever name.
Inner retrievers.
Values arenone,minmax, orl2_norm.
A pinned retriever applies pinned documents to the underlying retriever.This retriever will rewrite to a PinnedQueryBuilder.
Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
Retriever name.
Inner retriever.
A retriever that diversifies the results from its child retriever.
Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
Retriever name.
The diversification strategy to apply.
Value ismmr.
The document field on which to diversify results on.
The nested retriever whose results will be diversified.
The number of top documents to return after diversification.
The number of top documents from the nested retriever to consider for diversification.
The query vector used for diversification.
a dense vector query vector builder to use instead of a static query_vector
Controls the trade-off between relevance and diversity for MMR. A value of 0.0 focuses solely on diversity, while a value of 1.0 focuses solely on relevance. Required for MMR
Retrieve a script evaluation (based on different fields) for each hit.
Theid for a stored script.
Specifies any named parameters that are passed into the script as variables.Use parameters instead of hard-coded values to decrease compile time.
Specifies the language the script is written in.
Supported values include:
painless: Painless scripting language, purpose-built for Elasticsearch.expression: Lucene’s expressions language, compiles a JavaScript expression to bytecode.mustache: Mustache templated, used for templates.java: Expert Java APIUsed 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 thefrom andsize parameters.To page through more hits, use thesearch_after property.
Default value is10.
Split a scrolled search into multiple slices that can be consumed independently.
A comma-separated list of : pairs.
Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
The source fields that are returned for matching documents.These fields are returned in thehits._source property of the search response.If thestored_fields property is specified, the_source property defaults tofalse.Otherwise, it defaults totrue.
An array of wildcard (*) field patterns.The request returns values for field names matching these patterns in thehits.fields property of the response.
A reference to a field with formatting instructions on how to return the value
Defines a suggester that provides similar looking terms based on a provided text.
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 to0 (default), the query does not terminate early.
Default value is0.
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.
Iftrue, calculate and return document scores, even if the scores are not used for sorting.
Default value isfalse.
Iftrue, the request returns the document version as part of a hit.
Default value isfalse.
Iftrue, the request returns sequence number and primary term of the last modification of each hit.
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 tofalse.You can pass_source: true to 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.
A duration. Units can benanos,micros,ms (milliseconds),s (seconds),m (minutes),h (hours) andd (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
One or more runtime fields in the search request.These fields take precedence over mapped fields with the same name.
For typecomposite
For typelookup
A custom format fordate type runtime fields.
For typelookup
For typelookup
For typelookup
Painless script executed at query time.
Theid for a stored script.
Specifies any named parameters that are passed into the script as variables.Use parameters instead of hard-coded values to decrease compile time.
Field type, which can be:boolean,composite,date,double,geo_point,ip,keyword,long, orlookup.
Values areboolean,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.
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:
It does not include:
Iftrue, the request timed out before completion; returned results may be partial or empty.
A count of shards used for the request.
The number of shards the operation or search attempted to run on but failed.
The number of shards the operation or search succeeded on.
The number of shards the operation or search will run on overall.
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 thescroll query parameter is specified in the request.
GET /my-index-000001/_search?from=40&size=20{ "query": { "term": { "user.id": "kimchy" } }}resp = client.search( index="my-index-000001", from="40", size="20", query={ "term": { "user.id": "kimchy" } },)const response = await client.search({ index: "my-index-000001", from: 40, size: 20, query: { term: { "user.id": "kimchy", }, },});response = client.search( index: "my-index-000001", from: "40", size: "20", body: { "query": { "term": { "user.id": "kimchy" } } })$resp = $client->search([ "index" => "my-index-000001", "from" => "40", "size" => "20", "body" => [ "query" => [ "term" => [ "user.id" => "kimchy", ], ], ],]);curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"query":{"term":{"user.id":"kimchy"}}}' "$ELASTICSEARCH_URL/my-index-000001/_search?from=40&size=20"client.search(s -> s .from(40) .index("my-index-000001") .query(q -> q .term(t -> t .field("user.id") .value(FieldValue.of("kimchy")) ) ) .size(20),Void.class);{ "query": { "term": { "user.id": "kimchy" } }}{ "size": 100, "query": { "match" : { "title" : "elasticsearch" } }, "pit": { "id": "46ToAwMDaWR5BXV1aWQyKwZub2RlXzMAAAAAAAAAACoBYwADaWR4BXV1aWQxAgZub2RlXzEAAAAAAAAAAAEBYQADaWR5BXV1aWQyKgZub2RlXzIAAAAAAAAAAAwBYgACBXV1aWQyAAAFdXVpZDEAAQltYXRjaF9hbGw_gAAAAA==", "keep_alive": "1m" }}{ "slice": { "id": 0, "max": 2 }, "query": { "match": { "message": "foo" } }, "pit": { "id": "46ToAwMDaWR5BXV1aWQyKwZub2RlXzMAAAAAAAAAACoBYwADaWR4BXV1aWQxAgZub2RlXzEAAAAAAAAAAAEBYQADaWR5BXV1aWQyKgZub2RlXzIAAAAAAAAAAAwBYgACBXV1aWQyAAAFdXVpZDEAAQltYXRjaF9hbGw_gAAAAA==" }}{ "took": 5, "timed_out": false, "_shards": { "total": 1, "successful": 1, "skipped": 0, "failed": 0 }, "hits": { "total": { "value": 20, "relation": "eq" }, "max_score": 1.3862942, "hits": [ { "_index": "my-index-000001", "_id": "0", "_score": 1.3862942, "_source": { "@timestamp": "2099-11-15T14:12:12", "http": { "request": { "method": "get" }, "response": { "status_code": 200, "bytes": 1070000 }, "version": "1.1" }, "source": { "ip": "127.0.0.1" }, "message": "GET /search HTTP/1.1 200 1070000", "user": { "id": "kimchy" } } } ] }}