[DOCS] Create top-level "Search your data" page (#56058)

* [DOCS] Create top-level "Search your data" page

**Goal**

Create a top-level search section. This will let us clean up our search
API reference docs, particularly content from [`Request body search`][0].

**Changes**

* Creates a top-level `Search your data` page. This page is designed to
  house concept and tutorial docs related to search.

* Creates a `Run a search` page under `Search your data`. For now, This
  contains a basic search tutorial. The goal is to add content from
  [`Request body search`][0] to this in the future.

* Relocates `Long-running searches` and `Search across clusters` under
  `Search your data`. Increments several headings in that content.

* Reorders the top-level TOC to move `Search your data` higher. Also
  moves the `Query DSL`, `EQL`, and `SQL access` chapters immediately
  after.

Relates to #48194

[0]: https://www.elastic.co/guide/en/elasticsearch/reference/master/search-request-body.html

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[]
 
@@ -44,12 +48,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[]

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
 <<modules-remote-clusters,remote clusters>>. For example, you can use a {ccs} to
@@ -10,7 +9,7 @@ IMPORTANT: {ccs-cap} requires <<modules-remote-clusters, remote clusters>>.
 
 [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 <<search-search,search>> API request searches the
 `twitter` index on a single remote cluster, `cluster_one`.
@@ -132,7 +131,7 @@ The API returns the following response:
 
 [float]
 [[ccs-search-multi-remote-cluster]]
-=== Search multiple remote clusters
+==== Search multiple remote clusters
 
 The following <<search,search>> API request searches the `twitter` index on
 three clusters:
@@ -228,7 +227,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.
@@ -255,7 +254,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 <<sniff-mode,sniff connection>> mode, gateway and
 seed nodes need to be accessible from the local cluster via your network.
@@ -270,7 +269,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
 
 <<proxy-mode,Proxy mode>> remote cluster connections support {ccs}. All remote
 connections connect to the configured `proxy_address`. Any desired connection
@@ -279,7 +278,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
@@ -305,7 +304,7 @@ See <<ccs-unmin-roundtrips>> 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.
 
@@ -331,7 +330,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.
 

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
+
+* <<run-a-search>>
+* <<modules-cross-cluster-search>>
+* <<async-search-intro>>
+
+--
+
+include::run-a-search.asciidoc[]
+include::{es-repo-dir}/async-search.asciidoc[]
+include::{es-repo-dir}/modules/cross-cluster-search.asciidoc[]

docs/reference/search/run-a-search.asciidoc

@@ -0,0 +1,285 @@
+[[run-a-search]]
+== Run a search
+
+You can use the <<search-search,search API>> to search data stored in
+one or more {es} indices.
+
+The API can runs two types of searches, depending on how you provide
+<<search-query,queries>>:
+
+<<run-uri-search,URI searches>>::
+  Queries are provided through a query parameter. URI searches tend to be
+  simpler and best suited for testing.
+
+<<run-request-body-search,Request body searches>>::
+  Queries are provided through the JSON body of the API request. These queries
+  are written in <<query-dsl,Query DSL>>. 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 <<search-api-query-params-q,`q` query string
+parameter>> to run a search in the request's URI. The `q` parameter only accepts
+queries written in Lucene's <<query-string-syntax,query string syntax>>.
+
+.*Example*
+[%collapsible]
+====
+To get started, ingest or add some data to an {es} index.
+
+The following <<docs-bulk,bulk API>> 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",
+        "_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 <<search-api-request-body-query,`query` request
+body parameter>> to provide a query as a JSON object, written in
+<<query-dsl,Query DSL>>.
+
+.*Example*
+[%collapsible]
+====
+The following request body search uses the <<query-dsl-match-query,`match`>>
+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 <<relevance-scores,relevance
+score>> 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",
+        "_id": "2",
+        "_score": 0.9983525,
+        "_source": {
+          "@timestamp": "2020-12-07T11:06:07.000Z",
+          "user": {
+            "id": "8a4f500d"
+          },
+          "message": "Login successful"
+        }
+      },
+      {
+        "_index": "user_logs_000001",
+        "_id": "3",
+        "_score": 0.49917626,
+        "_source": {
+          "@timestamp": "2020-12-07T11:07:08.000Z",
+          "user": {
+            "id": "l7gk7f82"
+          },
+          "message": "Logout successful"
+        }
+      },
+      {
+        "_index": "user_logs_000001",
+        "_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]
+====

docs/reference/search/search.asciidoc

@@ -126,6 +126,7 @@ include::{docdir}/rest-api/common-parms.asciidoc[tag=index-ignore-unavailable]
   (Optional, string) Specifies the node or shard the operation should be
   performed on. Random by default.
 
+[[search-api-query-params-q]]
 `q`::
   (Optional, string) Query in the Lucene query string syntax.
 
@@ -222,6 +223,7 @@ include::{docdir}/rest-api/common-parms.asciidoc[tag=index-ignore-unavailable]
 [[search-search-api-request-body]]
 ==== {api-request-body-title}
 
+[[search-api-request-body-query]]
 `query`::
   (Optional, <<query-dsl,query object>>) Defines the search definition using the
   <<query-dsl,Query DSL>>.