[[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? * How many of my products have a price greater than $20? * 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 data stored in {es} data streams or indices. The API can run two types of searches, depending on how you provide queries: <>:: Queries are provided through a query parameter. URI searches tend to be simpler and best suited for testing. <>:: Queries are provided through the JSON body of the API request. These queries are written in <>. We recommend using request body searches in most production use cases. [WARNING] ==== If you specify a query in both the URI and request body, the search API request runs only the URI query. ==== [discrete] [[run-uri-search]] === Run a URI search You can use the search API's <> to run a search in the request's URI. The `q` parameter only accepts queries written in Lucene's <>. To get started, ingest or add some data to an {es} data stream or index. The following <> request adds some example server access log data to the `my-index-000001` index. [source,console] ---- PUT /my-index-000001/_bulk?refresh { "index":{ } } { "@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" } } { "index":{ } } { "@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": "10.42.42.42" }, "user": { "id": "elkbee" } } { "index":{ } } { "@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": "10.42.42.42" }, "user": { "id": "elkbee" } } ---- // TESTSETUP You can now use the search API to run a URI search on this index. The following URI search matches documents with a `user.id` value of `kimchy`. Note the query is specified using the `q` query string parameter. [source,console] ---- GET /my-index-000001/_search?q=user.id:kimchy ---- The API returns the following response. Note the `hits.hits` property contains the document that matched the query. [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": 0.9808291, "hits": [ { "_index": "my-index-000001", "_type": "_doc", "_id": "kxWFcnMByiguvud1Z8vC", "_score": 0.9808291, "_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] [[run-request-body-search]] === Run a request body search You can use the search API's <> to provide a query as a JSON object, written in <>. The following request body search uses the <> query to match documents with a `user.id` value of `kimchy`. Note the `match` query is specified as a JSON object in the `query` parameter. [source,console] ---- GET /my-index-000001/_search { "query": { "match": { "user.id": "kimchy" } } } ---- The API returns the following response. The `hits.hits` property contains matching documents. By default, the response sorts these matching documents by `_score`, a <> that measures how well each document matches the query. [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": 0.9808291, "hits": [ { "_index": "my-index-000001", "_type": "_doc", "_id": "kxWFcnMByiguvud1Z8vC", "_score": 0.9808291, "_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] [[search-multiple-indices]] === Search multiple data streams and indices To search multiple data streams and indices, add them as comma-separated values in the search API request path. The following request searches the `my-index-000001` and `my-index-000002` indices. [source,console] ---- GET /my-index-000001,my-index-000002/_search { "query": { "match": { "user.id": "kimchy" } } } ---- // TEST[s/^/PUT my-index-000002\n/] You can also search multiple data streams and indices using a wildcard (`*`) pattern. The following request targets the wildcard pattern `user_logs*`. The request searches any data streams or indices in the cluster that start with `user_logs`. [source,console] ---- GET /user_logs*/_search { "query": { "match": { "user.id": "kimchy" } } } ---- To search all data streams and indices in a cluster, omit the target from the request path. Alternatively, you can use `_all` or `*`. The following requests are equivalent and search all data streams and indices in the cluster. [source,console] ---- GET /_search { "query": { "match": { "user.id": "kimchy" } } } GET /_all/_search { "query": { "match": { "user.id": "kimchy" } } } GET /*/_search { "query": { "match": { "user.id": "kimchy" } } } ---- include::request/from-size.asciidoc[] include::search-fields.asciidoc[] include::request/collapse.asciidoc[] include::request/highlighting.asciidoc[] include::request/sort.asciidoc[] include::{es-repo-dir}/async-search.asciidoc[] include::{es-repo-dir}/modules/cross-cluster-search.asciidoc[] include::{es-repo-dir}/search/near-real-time.asciidoc[]