[[search-your-data]] = Search your data [[search-query]] A _search query_, or _query_, is a request for information about data in {es} data streams or indices. You can think of a query as a question, written in a way {es} 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 {es}. 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. [discrete] [[run-an-es-search]] == Run a search You can use the <> to search and <> data stored in {es} data streams or indices. The API's `query` request body parameter accepts queries written in <>. The following request searches `my-index-000001` using a <> query. This query matches documents with a `user.id` value of `kimchy`. [source,console] ---- GET /my-index-000001/_search { "query": { "match": { "user.id": "kimchy" } } } ---- // TEST[setup:my_index] The API response returns the top 10 documents matching the query in the `hits.hits` property. [source,console-result] ---- { "took": 5, "timed_out": false, "_shards": { "total": 1, "successful": 1, "skipped": 0, "failed": 0 }, "hits": { "total": { "value": 1, "relation": "eq" }, "max_score": 1.3862942, "hits": [ { "_index": "my-index-000001", "_type": "_doc", "_id": "kxWFcnMByiguvud1Z8vC", "_score": 1.3862942, "_source": { "@timestamp": "2099-11-15T14:12:12", "http": { "request": { "method": "get" }, "response": { "bytes": 1070000, "status_code": 200 }, "version": "1.1" }, "message": "GET /search HTTP/1.1 200 1070000", "source": { "ip": "127.0.0.1" }, "user": { "id": "kimchy" } } } ] } } ---- // TESTRESPONSE[s/"took": 5/"took": "$body.took"/] // TESTRESPONSE[s/"_id": "kxWFcnMByiguvud1Z8vC"/"_id": "$body.hits.hits.0._id"/] [discrete] [[common-search-options]] === Common search options You can use the following options to customize your searches. *Query DSL* + <> supports a variety of query types you can mix and match to get the results you want. Query types include: * <> and other <>, which let you combine queries and match results based on multiple criteria * <> for filtering and finding exact matches * <>, which are commonly used in search engines * <> and <> *Aggregations* + You can use <> 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 <>. *Paginate search results* + By default, searches return only the top 10 matching hits. To retrieve more or fewer documents, see <>. *Retrieve selected fields* + The search response's `hit.hits` property includes the full document <> for each hit. To retrieve only a subset of the `_source` or other fields, see <>. *Sort search results* + By default, search hits are sorted by `_score`, a <> that measures how well each document matches the query. To customize the calculation of these scores, use the <> query. To sort search hits by other field values, see <>. *Run an async search* + {es} 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 <> or <>. To avoid long waits, you can use run an _asynchronous_, or _async_, search instead. An <> lets you retrieve partial results for a long-running search now and get complete results later. [discrete] [[search-timeout]] === Search timeout By default, search requests don't time out. The request waits for complete results before returning a response. While <> 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. [source,console] ---- GET /my-index-000001/_search { "timeout": "2s", "query": { "match": { "user.id": "kimchy" } } } ---- // TEST[setup:my_index] To set a cluster-wide default timeout for all search requests, configure `search.default_search_timeout` using the <>. 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 <>. The `search.default_search_timeout` setting defaults to `-1` (no timeout). [discrete] [[global-search-cancellation]] === Search cancellation You can cancel a search request using the <>. {es} 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. include::request/track-total-hits.asciidoc[] include::quickly-check-for-matching-docs.asciidoc[] include::request/collapse.asciidoc[] include::filter-search-results.asciidoc[] include::request/highlighting.asciidoc[] include::{es-repo-dir}/async-search.asciidoc[] include::{es-repo-dir}/search/near-real-time.asciidoc[] include::paginate-search-results.asciidoc[] include::request/inner-hits.asciidoc[] include::search-fields.asciidoc[] include::{es-repo-dir}/modules/cross-cluster-search.asciidoc[] include::search-multiple-indices.asciidoc[] include::search-shard-routing.asciidoc[] include::request/sort.asciidoc[]