Search your data

A search query, or query, is a request for information about data in Elasticsearch data streams or indices.

You can think of a query as a question, written in a way Elasticsearch understands. Depending on your data, you can use a query to get answers to questions like:

  • What processes on my server take longer than 500 milliseconds to respond?
  • What users on my network ran regsvr32.exe within the last week?
  • What pages on my website contain a specific word or phrase?

A search consists of one or more queries that are combined and sent to Elasticsearch. Documents that match a search’s queries are returned in the hits, or search results, of the response.

A search may also contain additional information used to better process its queries. For example, a search may be limited to a specific index or only return a specific number of results.

Run a search

You can use the search API to search and aggregate data stored in Elasticsearch data streams or indices. The API’s query request body parameter accepts queries written in Query DSL.

The following request searches my-index-000001 using a match query. This query matches documents with a user.id value of kimchy.

  1. GET /my-index-000001/_search
  2. {
  3.   "query": {
  4.     "match": {
  5.       "user.id": "kimchy"
  6.     }
  7.   }
  8. }

The API response returns the top 10 documents matching the query in the hits.hits property.

  1. {
  2.   "took": 5,
  3.   "timed_out": false,
  4.   "_shards": {
  5.     "total": 1,
  6.     "successful": 1,
  7.     "skipped": 0,
  8.     "failed": 0
  9.   },
  10.   "hits": {
  11.     "total": {
  12.       "value": 1,
  13.       "relation": "eq"
  14.     },
  15.     "max_score": 1.3862942,
  16.     "hits": [
  17.       {
  18.         "_index": "my-index-000001",
  19.         "_type": "_doc",
  20.         "_id": "kxWFcnMByiguvud1Z8vC",
  21.         "_score": 1.3862942,
  22.         "_source": {
  23.           "@timestamp": "2099-11-15T14:12:12",
  24.           "http": {
  25.             "request": {
  26.               "method": "get"
  27.             },
  28.             "response": {
  29.               "bytes": 1070000,
  30.               "status_code": 200
  31.             },
  32.             "version": "1.1"
  33.           },
  34.           "message": "GET /search HTTP/1.1 200 1070000",
  35.           "source": {
  36.             "ip": "127.0.0.1"
  37.           },
  38.           "user": {
  39.             "id": "kimchy"
  40.           }
  41.         }
  42.       }
  43.     ]
  44.   }
  45. }

Common search options

You can use the following options to customize your searches.

Query DSL
Query DSL supports a variety of query types you can mix and match to get the results you want. Query types include:

Aggregations
You can use search aggregations to get statistics and other analytics for your search results. Aggregations help you answer questions like:

  • What’s the average response time for my servers?
  • What are the top IP addresses hit by users on my network?
  • What is the total transaction revenue by customer?

Search multiple data streams and indices
You can use comma-separated values and grep-like index patterns to search several data streams and indices in the same request. You can even boost search results from specific indices. See Search multiple data streams and indices.

Paginate search results
By default, searches return only the top 10 matching hits. To retrieve more or fewer documents, see Paginate search results.

Retrieve selected fields
The search response’s hit.hits property includes the full document _source for each hit. To retrieve only a subset of the _source or other fields, see Retrieve selected fields.

Sort search results
By default, search hits are sorted by _score, a relevance score that measures how well each document matches the query. To customize the calculation of these scores, use the script_score query. To sort search hits by other field values, see Sort search results.

Run an async search
Elasticsearch searches are designed to run on large volumes of data quickly, often returning results in milliseconds. For this reason, searches are synchronous by default. The search request waits for complete results before returning a response.

However, complete results can take longer for searches across frozen indices or multiple clusters.

To avoid long waits, you can run an asynchronous, or async, search instead. An async search lets you retrieve partial results for a long-running search now and get complete results later.

Search timeout

By default, search requests don’t time out. The request waits for complete results before returning a response.

While async search is designed for long-running searches, you can also use the timeout parameter to specify a duration you’d like to wait for a search to complete. If no response is received before this period ends, the request fails and returns an error.

  1. GET /my-index-000001/_search
  2. {
  3.   "timeout": "2s",
  4.   "query": {
  5.     "match": {
  6.       "user.id": "kimchy"
  7.     }
  8.   }
  9. }

To set a cluster-wide default timeout for all search requests, configure search.default_search_timeout using the cluster settings API. This global timeout duration is used if no timeout argument is passed in the request. If the global search timeout expires before the search request finishes, the request is cancelled using task cancellation. The search.default_search_timeout setting defaults to -1 (no timeout).

Search cancellation

You can cancel a search request using the task management API. Elasticsearch also automatically cancels a search request when your client’s HTTP connection closes. We recommend you set up your client to close HTTP connections when a search request is aborted or times out.

Track total hits

Generally the total hit count can’t be computed accurately without visiting all matches, which is costly for queries that match lots of documents. The track_total_hits parameter allows you to control how the total number of hits should be tracked. Given that it is often enough to have a lower bound of the number of hits, such as “there are at least 10000 hits”, the default is set to 10,000. This means that requests will count the total hit accurately up to 10,000 hits. It’s is a good trade off to speed up searches if you don’t need the accurate number of hits after a certain threshold.

When set to true the search response will always track the number of hits that match the query accurately (e.g. total.relation will always be equal to "eq" when track_total_hits is set to true). Otherwise the "total.relation" returned in the "total" object in the search response determines how the "total.value" should be interpreted. A value of "gte" means that the "total.value" is a lower bound of the total hits that match the query and a value of "eq" indicates that "total.value" is the accurate count.

  1. GET my-index-000001/_search
  2. {
  3.   "track_total_hits": true,
  4.     "query": {
  5.       "match" : {
  6.         "user.id" : "elkbee"
  7.       }
  8.     }
  9. }

… returns:

  1. {
  2.   "_shards": ...
  3.   "timed_out": false,
  4.   "took": 100,
  5.   "hits": {
  6.     "max_score": 1.0,
  7.     "total" : {
  8.       "value": 2048,    
  9.       "relation": "eq"  
  10.     },
  11.     "hits": ...
  12.   }
  13. }

The total number of hits that match the query.

The count is accurate (e.g. “eq” means equals).

It is also possible to set track_total_hits to an integer. For instance the following query will accurately track the total hit count that match the query up to 100 documents:

  1. GET my-index-000001/_search
  2. {
  3.   "track_total_hits": 100,
  4.   "query": {
  5.     "match": {
  6.       "user.id": "elkbee"
  7.     }
  8.   }
  9. }

The hits.total.relation in the response will indicate if the value returned in hits.total.value is accurate ("eq") or a lower bound of the total ("gte").

For instance the following response:

  1. {
  2.   "_shards": ...
  3.   "timed_out": false,
  4.   "took": 30,
  5.   "hits": {
  6.     "max_score": 1.0,
  7.     "total": {
  8.       "value": 42,         
  9.       "relation": "eq"     
  10.     },
  11.     "hits": ...
  12.   }
  13. }

42 documents match the query

and the count is accurate (“eq”)

… indicates that the number of hits returned in the total is accurate.

If the total number of hits that match the query is greater than the value set in track_total_hits, the total hits in the response will indicate that the returned value is a lower bound:

  1. {
  2.   "_shards": ...
  3.   "hits": {
  4.     "max_score": 1.0,
  5.     "total": {
  6.       "value": 100,         
  7.       "relation": "gte"     
  8.     },
  9.     "hits": ...
  10.   }
  11. }

There are at least 100 documents that match the query

This is a lower bound (“gte”).

If you don’t need to track the total number of hits at all you can improve query times by setting this option to false:

  1. GET my-index-000001/_search
  2. {
  3.   "track_total_hits": false,
  4.   "query": {
  5.     "match": {
  6.       "user.id": "elkbee"
  7.     }
  8.   }
  9. }

… returns:

  1. {
  2.   "_shards": ...
  3.   "timed_out": false,
  4.   "took": 10,
  5.   "hits": {             
  6.     "max_score": 1.0,
  7.     "hits": ...
  8.   }
  9. }

The total number of hits is unknown.

Finally you can force an accurate count by setting "track_total_hits" to true in the request.

Quickly check for matching docs

If you only want to know if there are any documents matching a specific query, you can set the size to 0 to indicate that we are not interested in the search results. You can also set terminate_after to 1 to indicate that the query execution can be terminated whenever the first matching document was found (per shard).

  1. GET /_search?q=user.id:elkbee&size=0&terminate_after=1

terminate_after is always applied after the post_filter and stops the query as well as the aggregation executions when enough hits have been collected on the shard. Though the doc count on aggregations may not reflect the hits.total in the response since aggregations are applied before the post filtering.

The response will not contain any hits as the size was set to 0. The hits.total will be either equal to 0, indicating that there were no matching documents, or greater than 0 meaning that there were at least as many documents matching the query when it was early terminated. Also if the query was terminated early, the terminated_early flag will be set to true in the response.

  1. {
  2.   "took": 3,
  3.   "timed_out": false,
  4.   "terminated_early": true,
  5.   "_shards": {
  6.     "total": 1,
  7.     "successful": 1,
  8.     "skipped" : 0,
  9.     "failed": 0
  10.   },
  11.   "hits": {
  12.     "total" : {
  13.         "value": 1,
  14.         "relation": "eq"
  15.     },
  16.     "max_score": null,
  17.     "hits": []
  18.   }
  19. }

The took time in the response contains the milliseconds that this request took for processing, beginning quickly after the node received the query, up until all search related work is done and before the above JSON is returned to the client. This means it includes the time spent waiting in thread pools, executing a distributed search across the whole cluster and gathering all the results.