diff --git a/docs/reference/index.asciidoc b/docs/reference/index.asciidoc index 21a42a7f634cc..18ae2e22399b4 100644 --- a/docs/reference/index.asciidoc +++ b/docs/reference/index.asciidoc @@ -18,13 +18,17 @@ include::setup.asciidoc[] include::upgrade.asciidoc[] -include::aggregations.asciidoc[] +include::search/index.asciidoc[] include::query-dsl.asciidoc[] -include::modules/cross-cluster-search.asciidoc[] +ifdef::permanently-unreleased-branch[] +include::eql/index.asciidoc[] +endif::[] -include::async-search.asciidoc[] +include::sql/index.asciidoc[] + +include::aggregations.asciidoc[] include::scripting.asciidoc[] @@ -42,12 +46,8 @@ ifdef::permanently-unreleased-branch[] include::autoscaling/index.asciidoc[] -include::eql/index.asciidoc[] - endif::[] -include::sql/index.asciidoc[] - include::monitoring/index.asciidoc[] include::frozen-indices.asciidoc[] diff --git a/docs/reference/modules/cross-cluster-search.asciidoc b/docs/reference/modules/cross-cluster-search.asciidoc index 46b7df26167d9..d9fdf0ceca2a0 100644 --- a/docs/reference/modules/cross-cluster-search.asciidoc +++ b/docs/reference/modules/cross-cluster-search.asciidoc @@ -1,6 +1,5 @@ -[chapter] [[modules-cross-cluster-search]] -= Search across clusters +== Search across clusters *{ccs-cap}* lets you run a single search request against one or more <>. For example, you can use a {ccs} to @@ -10,7 +9,7 @@ IMPORTANT: {ccs-cap} requires <>. [float] [[ccs-supported-apis]] -== Supported APIs +=== Supported APIs The following APIs support {ccs}: @@ -21,11 +20,11 @@ The following APIs support {ccs}: [float] [[ccs-example]] -== {ccs-cap} examples +=== {ccs-cap} examples [float] [[ccs-remote-cluster-setup]] -=== Remote cluster setup +==== Remote cluster setup To perform a {ccs}, you must have at least one remote cluster configured. @@ -64,7 +63,7 @@ PUT _cluster/settings [float] [[ccs-search-remote-cluster]] -=== Search a single remote cluster +==== Search a single remote cluster The following <> API request searches the `twitter` index on a single remote cluster, `cluster_one`. @@ -133,7 +132,7 @@ The API returns the following response: [float] [[ccs-search-multi-remote-cluster]] -=== Search multiple remote clusters +==== Search multiple remote clusters The following <> API request searches the `twitter` index on three clusters: @@ -232,7 +231,7 @@ means the document came from the local cluster. [float] [[skip-unavailable-clusters]] -== Skip unavailable clusters +=== Skip unavailable clusters By default, a {ccs} returns an error if *any* cluster in the request is unavailable. @@ -259,7 +258,7 @@ include matching documents from that cluster in the final results. [discrete] [[ccs-gateway-seed-nodes]] -== Selecting gateway and seed nodes in sniff mode +=== Selecting gateway and seed nodes in sniff mode For remote clusters using the <> mode, gateway and seed nodes need to be accessible from the local cluster via your network. @@ -274,7 +273,7 @@ wanted, the seed nodes for a cluster can be a subset of these gateway nodes. [discrete] [[ccs-proxy-mode]] -== {ccs} in proxy mode +=== {ccs} in proxy mode <> remote cluster connections support {ccs}. All remote connections connect to the configured `proxy_address`. Any desired connection @@ -283,7 +282,7 @@ be implemented by the intermediate proxy at this configured address. [discrete] [[ccs-network-delays]] -== How {ccs} handles network delays +=== How {ccs} handles network delays Because {ccs} involves sending requests to remote clusters, any network delays can impact search speed. To avoid slow searches, {ccs} offers two options for @@ -309,7 +308,7 @@ See <> to learn how this option works. [discrete] [[ccs-min-roundtrips]] -=== Minimize network roundtrips +==== Minimize network roundtrips Here's how {ccs} works when you minimize network roundtrips. @@ -335,7 +334,7 @@ image:images/ccs/ccs-min-roundtrip-client-response.svg[] [discrete] [[ccs-unmin-roundtrips]] -=== Don't minimize network roundtrips +==== Don't minimize network roundtrips Here's how {ccs} works when you don't minimize network roundtrips. diff --git a/docs/reference/search/index.asciidoc b/docs/reference/search/index.asciidoc new file mode 100644 index 0000000000000..e23970e61b4fe --- /dev/null +++ b/docs/reference/search/index.asciidoc @@ -0,0 +1,39 @@ +[[search-your-data]] += Search your data + +[partintro] +-- + +[[search-query]] +A _search query_, or _query_, is a request for information about data in one or +more {es} 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 pages on my website contain a specific word or phrase? +* 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? + +A _search_ consists of one or more queries that are combined and sent to {es}. +Documents that match the 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] +[[search-toc]] +=== In this section + +* <> +* <> +* <> + +-- + +include::run-a-search.asciidoc[] +include::{es-repo-dir}/async-search.asciidoc[] +include::{es-repo-dir}/modules/cross-cluster-search.asciidoc[] \ No newline at end of file diff --git a/docs/reference/search/run-a-search.asciidoc b/docs/reference/search/run-a-search.asciidoc new file mode 100644 index 0000000000000..f6242c569279a --- /dev/null +++ b/docs/reference/search/run-a-search.asciidoc @@ -0,0 +1,289 @@ +[[run-a-search]] +== Run a search + +You can use the <> to search data stored in +one or more {es} indices. + +The API can runs two types of searches, depending on how you provide +<>: + +<>:: + 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 <>. + +.*Example* +[%collapsible] +==== +To get started, ingest or add some data to an {es} index. + +The following <> request adds some example user log data to +the `user_logs_000001` index. + +[source,console] +---- +PUT /user_logs_000001/_bulk?refresh +{"index":{"_index" : "user_logs_000001", "_id" : "1"}} +{ "@timestamp": "2020-12-06T11:04:05.000Z", "user": { "id": "vlb44hny" }, "message": "Login attempt failed" } +{"index":{"_index" : "user_logs_000001", "_id" : "2"}} +{ "@timestamp": "2020-12-07T11:06:07.000Z", "user": { "id": "8a4f500d" }, "message": "Login successful" } +{"index":{"_index" : "user_logs_000001", "_id" : "3"}} +{ "@timestamp": "2020-12-07T11:07:08.000Z", "user": { "id": "l7gk7f82" }, "message": "Logout successful" } +---- + +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 `l7gk7f82`. +Note the query is specified using the `q` query string parameter. + +[source,console] +---- +GET /user_logs_000001/_search?q=user.id:8a4f500d +---- +// TEST[continued] + +The API returns the following response. Note the `hits.hits` property contains +the document that matched the query. + +[source,console-result] +---- +{ + "took": 2, + "timed_out": false, + "_shards": { + "total": 1, + "successful": 1, + "skipped": 0, + "failed": 0 + }, + "hits": { + "total": { + "value": 1, + "relation": "eq" + }, + "max_score": 0.9808291, + "hits": [ + { + "_index": "user_logs_000001", + "_type": "_doc", + "_id": "2", + "_score": 0.9808291, + "_source": { + "@timestamp": "2020-12-07T11:06:07.000Z", + "user": { + "id": "8a4f500d" + }, + "message": "Login successful" + } + } + ] + } +} +---- +// TESTRESPONSE[s/"took": 2/"took": "$body.took"/] +==== + +[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 +<>. + +.*Example* +[%collapsible] +==== +The following request body search uses the <> +query to match documents with a `message` value of `login successful`. Note the +`match` query is specified as a JSON object in the `query` parameter. + +[source,console] +---- +GET /user_logs_000001/_search +{ + "query": { + "match": { + "message": "login successful" + } + } +} +---- +// TEST[continued] + +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": 1, + "timed_out": false, + "_shards": { + "total": 1, + "successful": 1, + "skipped": 0, + "failed": 0 + }, + "hits": { + "total": { + "value": 3, + "relation": "eq" + }, + "max_score": 0.9983525, + "hits": [ + { + "_index": "user_logs_000001", + "_type": "_doc", + "_id": "2", + "_score": 0.9983525, + "_source": { + "@timestamp": "2020-12-07T11:06:07.000Z", + "user": { + "id": "8a4f500d" + }, + "message": "Login successful" + } + }, + { + "_index": "user_logs_000001", + "_type": "_doc", + "_id": "3", + "_score": 0.49917626, + "_source": { + "@timestamp": "2020-12-07T11:07:08.000Z", + "user": { + "id": "l7gk7f82" + }, + "message": "Logout successful" + } + }, + { + "_index": "user_logs_000001", + "_type": "_doc", + "_id": "1", + "_score": 0.42081726, + "_source": { + "@timestamp": "2020-12-06T11:04:05.000Z", + "user": { + "id": "vlb44hny" + }, + "message": "Login attempt failed" + } + } + ] + } +} +---- +// TESTRESPONSE[s/"took": 1/"took": "$body.took"/] +==== + +[discrete] +[[search-multiple-indices]] +=== Search multiple indices + +To search multiple indices, add them as comma-separated values in the search API +request path. + +.*Example* +[%collapsible] +==== +The following request searches the `user_logs_000001` and `user_logs_000002` +indices. + +[source,console] +---- +GET /user_logs_000001,user_logs_000002/_search +{ + "query": { + "match": { + "message": "login successful" + } + } +} +---- +// TEST[continued] +// TEST[s/^/PUT user_logs_000002\n/] +==== + +You can also search multiple indices using an index pattern. + +.*Example* +[%collapsible] +==== +The following request uses the index pattern `user_logs*` in place of the index +name. The request searches any indices in the cluster that start with +`user_logs`. + +[source,console] +---- +GET /user_logs*/_search +{ + "query": { + "match": { + "message": "login successful" + } + } +} +---- +// TEST[continued] +==== + +To search all indices in a cluster, omit the index name from the request path. +Alternatively, you can use `_all` or `*` in place of the index name. + +.*Example* +[%collapsible] +==== +The following requests are equivalent and search all indices in the cluster. + +[source,console] +---- +GET /_search +{ + "query": { + "match": { + "message": "login successful" + } + } +} + +GET /_all/_search +{ + "query": { + "match": { + "message": "login successful" + } + } +} + +GET /*/_search +{ + "query" : { + "match" : { "message" : "login" } + } +} +---- +// TEST[continued] +====