[DOCS] Combine search API and URI search API reference docs (#55884)

The search API and URI search pages document the same `_search` API.
This combines the documentation from each page under the search API
docs.

Changes:

* Adds an abbreviated title for the search API page.
* Removes the following invalid query parameters:
  * `analyzer`
  * `analyze_wildcard`
  * `default_operator`
  * `df`
  * `lenient`
  * `suggest_mode`
  * `suggest_size`
* Removes the URI search docs page and adds a related redirect.
* Updates the headings of several examples

Co-authored-by: debadair <debadair@elastic.co>

docs/reference/redirects.asciidoc

@@ -493,3 +493,8 @@ See <<ilm-actions>>.
 === {ilm-init} policy definition
 
 See <<ilm-index-lifecycle>>.
+
+[role="exclude",id="search-uri-request"]
+=== URI Search
+
+See <<search-search>>.

docs/reference/search.asciidoc

@@ -154,8 +154,6 @@ include::search/search.asciidoc[]
 
 include::search/async-search.asciidoc[]
 
-include::search/uri-request.asciidoc[]
-
 include::search/request-body.asciidoc[]
 
 include::search/search-template.asciidoc[]

docs/reference/search/search.asciidoc

@@ -1,48 +1,40 @@
 [[search-search]]
-=== Search
+=== Search API
+++++
+<titleabbrev>Search</titleabbrev>
+++++
 
 Returns search hits that match the query defined in the request.
 
 [source,console]
 ----
-GET /twitter/_search?q=tag:wow
+GET /twitter/_search
 ----
 // TEST[setup:twitter]
 
-
 [[search-search-api-request]]
 ==== {api-request-title}
 
 `GET /<index>/_search`
 
-`POST /<index>/_search`
-
 `GET /_search`
 
-`POST /_search`
+`POST /<index>/_search`
 
+`POST /_search`
 
 [[search-search-api-desc]]
 ==== {api-description-title}
 
 Allows you to execute a search query and get back search hits that match the
-query. The query can either be provided using a simple
-<<search-uri-request,query string as a parameter>>, or using a
-<<search-request-body,request body>>.
-
-[[search-partial-responses]]
-===== Partial responses
-
-To ensure fast responses, the search API will respond with partial results if
-one or more shards fail. See <<shard-failures, Shard failures>> for more
-information.
+query. You can provide search queries using the <<search-api-query-params-q,`q`
+query string parameter>> or <<search-request-body,request body>>.
 
 [[search-search-api-path-params]]
 ==== {api-path-parms-title}
 
 include::{docdir}/rest-api/common-parms.asciidoc[tag=index]
 
-
 [[search-search-api-query-params]]
 ==== {api-query-parms-title}
 
@@ -50,16 +42,15 @@ include::{docdir}/rest-api/common-parms.asciidoc[tag=allow-no-indices]
 +
 Defaults to `true`.
 
+[[search-partial-responses]]
 `allow_partial_search_results`::
-  (Optional, boolean) Indicates if an error should be returned if there is a
-  partial search failure or timeout. Defaults to `true`.
-
-`analyzer`::
-  (Optional, string) Defines the analyzer to use for the query string.
-
-`analyze_wildcard`::
-  (Optional, boolean) If `true`, wildcard and prefix queries will also be
-  analyzed. Defaults to `false`.
+(Optional, boolean)
+If `true`, returns partial results if there are request timeouts or
+<<shard-failures,shard failures>>. If `false`, returns an error with
+no partial results. Defaults to `true`.
++
+To override the default for this field, set the 
+`search.default_allow_partial_results` cluster setting to `false`.
 
 `batched_reduce_size`::
   (Optional, integer) The number of shard results that should be reduced at once
@@ -71,14 +62,6 @@ Defaults to `true`.
   (Optional, boolean) Indicates whether network round-trips should be minimized
   as part of cross-cluster search requests execution. Defaults to `true`.
 
-`default_operator`::
-  (Optional, string) The default operator for query string query (AND or OR).
-  Defaults to `OR`.
-
-`df`::
-  (Optional, string) Defines the field to use as default where no field prefix
-  is given in the query string.
-
 `docvalue_fields`::
   (Optional, string) A comma-separated list of fields to return as the docvalue
   representation of a field for each hit.
@@ -91,8 +74,7 @@ Defaults to `open`.
   (Optional, boolean) If `true`, returns detailed information about score
   computation as part of a hit. Defaults to `false`.
 
-`from`::
-  (Optional, integer) Defines the starting offset. Defaults to `0`.
+include::{docdir}/rest-api/common-parms.asciidoc[tag=from]
 
 `ignore_throttled`::
   (Optional, boolean) If `true`, concrete, expanded or aliased indices will be
@@ -100,10 +82,6 @@ Defaults to `open`.
 
 include::{docdir}/rest-api/common-parms.asciidoc[tag=index-ignore-unavailable]
 
-`lenient`::
-  (Optional, boolean) If `true`, format-based query failures (such as
-  providing text to a numeric field) will be ignored. Defaults to `false`.
-
 `max_concurrent_shard_requests`::
   (Optional, integer) Defines the number of concurrent shard requests per node
   this search executes concurrently. This value should be used to limit the
@@ -127,8 +105,20 @@ include::{docdir}/rest-api/common-parms.asciidoc[tag=index-ignore-unavailable]
   performed on. Random by default.
 
 [[search-api-query-params-q]]
-`q`::
-  (Optional, string) Query in the Lucene query string syntax.
+include::{docdir}/rest-api/common-parms.asciidoc[tag=search-q]
++
+--
+You can use the `q` parameter to run a query parameter search. Query parameter
+searches do not support the full {es} <<query-dsl,Query DSL>> but are handy for
+testing.
+
+[IMPORTANT]
+====
+The `q` parameter overrides the <<search-api-request-body-query,`query`>>
+parameter in the request body. If both parameters are specified, documents
+matching the `query` request body parameter are not returned.
+====
+--
 
 `request_cache`::
   (Optional, boolean) If `true`, request cache will be used for this request.
@@ -142,11 +132,7 @@ include::{docdir}/rest-api/common-parms.asciidoc[tag=index-ignore-unavailable]
   (Optional, <<time-units, time units>>) Specifies how long a consistent view of
   the index should be maintained for scrolled search.
 
-`search_type`::
-  (Optional, string) Defines the type of the search operation. Available
-  options:
-  * `query_then_fetch`
-  * `dfs_query_then_fetch`
+include::{docdir}/rest-api/common-parms.asciidoc[tag=search_type]
 
 `seq_no_primary_term`::
   (Optional, boolean) If `true`, returns sequence number and primary term of the
@@ -159,16 +145,13 @@ include::{docdir}/rest-api/common-parms.asciidoc[tag=index-ignore-unavailable]
   (Optional, string) A comma-separated list of <field>:<direction> pairs.
 
 `_source`::
-  (Optional, string) True or false to return the `_source` field or not, or a
-  list of fields to return.
+(Optional, boolean)
+If `true`, the response includes the `_source` of matching documents under
+`hits`. Defaults to `true`.
 
-`_source_excludes`::
-  (Optional, string) A list of fields to exclude from the returned `_source`
-  field.
+include::{docdir}/rest-api/common-parms.asciidoc[tag=source_excludes]
 
-`_source_includes`::
-  (Optional, string) A list of fields to extract and return from the `_source`
-  field.
+include::{docdir}/rest-api/common-parms.asciidoc[tag=source_includes]
 
 `stats`::
   (Optional, string) Specific `tag` of the request for logging and statistical
@@ -176,28 +159,19 @@ include::{docdir}/rest-api/common-parms.asciidoc[tag=index-ignore-unavailable]
 
 `stored_fields`::
   (Optional, string) A comma-separated list of stored fields to return as part
-  of a hit.
+  of a hit. If no fields are specified, no stored fields are included in the
+  response.
 
 `suggest_field`::
   (Optional, string) Specifies which field to use for suggestions.
 
-`suggest_mode`::
-  (Optional, string) Specifies suggest mode. Defaults to `missing`. Available
-  options:
-  * `always`
-  * `missing`
-  * `popular`
-
-`suggest_size`::
-  (Optional, integer) Defines how many suggestions to return in response.
-
 `suggest_text`::
   (Optional, string) The source text for which the suggestions should be
   returned.
 
-`terminate_after`::
-  (Optional, integer) The maximum number of documents to collect for each shard,
-  upon reaching which the query execution will terminate early.
+include::{docdir}/rest-api/common-parms.asciidoc[tag=terminate_after]
++
+Defaults to `0`, which does not terminate query execution early.
 
 `timeout`::
   (Optional, <<time-units, time units>>) Specifies the period of time to wait
@@ -205,19 +179,23 @@ include::{docdir}/rest-api/common-parms.asciidoc[tag=index-ignore-unavailable]
   request fails and returns an error. Defaults to no timeout.
 
 `track_scores`::
-  (Optional, boolean) If `true`, then calculates and returns scores even if they
-  are not used for sorting.
+  (Optional, boolean) If `true`, calculate and return document scores, even if
+  the scores are not used for sorting. Defaults to `false`.
 
 `track_total_hits`::
-  (Optional, boolean) Indicates if the number of documents that match the query
-  should be tracked.
+  (Optional, integer or boolean)
+  Number of hits matching the query to count accurately. Defaults to `10,000`.
+  +
+  If `true`, the default value is used. If `false`, the response does not
+  include the total number of hits matching the query.
 
 `typed_keys`::
-  (Optional, boolean) Specifies whether aggregation and suggester names should
-  be prefixed by their respective types in the response.
+  (Optional, boolean) If `true`, aggregation and suggester names are be prefixed
+  by their respective types in the response. Defaults to `true`.
 
 `version`::
-  (Optional, boolean) If `true`, returns document version as part of a hit.
+  (Optional, boolean)
+  If `true`, returns document version as part of a hit. Defaults to `false.
 
 
 [[search-search-api-request-body]]
@@ -364,7 +342,7 @@ Original JSON body passed for the document at index time.
 ==== {api-examples-title}
 
 [[search-api-specific-ex]]
-===== Search a specific index
+===== Search an index using the `q` query parameter
 
 [source,console]
 ----
@@ -410,7 +388,7 @@ The API returns the following response:
 // TESTRESPONSE[s/"took" : 5/"took": $body.took/]
 
 [[search-multi-index]]
-===== Search several indices
+===== Search several indices using the `q` query parameter
 
 [source,console]
 ----
@@ -419,7 +397,7 @@ GET /kimchy,elasticsearch/_search?q=user:kimchy
 // TEST[s/^/PUT kimchy\nPUT elasticsearch\n/]
 
 [[search-api-all-ex]]
-===== Search all indices
+===== Search all indices using the `q` query parameter
 
 To search all indices in a cluster,
 omit the `<index>` parameter.

docs/reference/search/uri-request.asciidoc

@@ -1,154 +0,0 @@
-[[search-uri-request]]
-=== URI Search
-
-Specifies search criteria as query parameters in the request URI.
-
-[source,console]
---------------------------------------------------
-GET twitter/_search?q=user:kimchy
---------------------------------------------------
-// TEST[setup:twitter]
-
-
-[[search-uri-request-api-request]]
-==== {api-request-title}
-
-`GET /<index>/_search?q=<parameter>`
-
-
-[[search-uri-request-api-desc]]
-==== {api-description-title}
-
-You can use query parameters to define your search criteria directly in the 
-request URI, rather than in the request body. Request URI searches do not 
-support the full {es} Query DSL, but are handy for testing.
-
-
-[[search-uri-request-api-path-params]]
-==== {api-path-parms-title}
-
-include::{docdir}/rest-api/common-parms.asciidoc[tag=index]
-
-
-[[search-uri-request-api-query-params]]
-==== {api-query-parms-title}
-
-`allow_partial_search_results`:: 
-  (Optional, boolean) Set to `false` to fail the request if only partial results 
-  are available. Defaults to `true`, which returns partial results in the event 
-  of timeouts or partial failures You can override the default behavior for all 
-  requests by setting `search.default_allow_partial_results` to `false` in the 
-  cluster settings.
-
-include::{docdir}/rest-api/common-parms.asciidoc[tag=analyze_wildcard]
-  
-include::{docdir}/rest-api/common-parms.asciidoc[tag=analyzer]
-
-`batched_reduce_size`:: 
-  (Optional, integer) The number of shard results that should be reduced at once 
-  on the coordinating node. This value should be used as a protection mechanism 
-  to reduce the memory overhead per search request if the potential number of 
-  shards in the request can be large.
-
-include::{docdir}/rest-api/common-parms.asciidoc[tag=default_operator]
-
-include::{docdir}/rest-api/common-parms.asciidoc[tag=df]
-
-`explain`:: 
-  (Optional, string) For each hit, include an explanation of how the score was 
-  computed.
-
-include::{docdir}/rest-api/common-parms.asciidoc[tag=from]
-
-include::{docdir}/rest-api/common-parms.asciidoc[tag=lenient]
-
-include::{docdir}/rest-api/common-parms.asciidoc[tag=search-q]
-
-include::{docdir}/rest-api/common-parms.asciidoc[tag=search_type]
-
-`size`:: 
-  (Optional, integer) The number of hits to return. Defaults to `10`.
-
-include::{docdir}/rest-api/common-parms.asciidoc[tag=source]
-
-include::{docdir}/rest-api/common-parms.asciidoc[tag=source_excludes]
-
-include::{docdir}/rest-api/common-parms.asciidoc[tag=source_includes]
-
-`stored_fields`:: 
-  (Optional, string) The selective stored fields of the document to return for 
-  each hit, comma delimited. Not specifying any value will cause no fields to 
-  return.
-
-`sort`:: 
-  (Optional, string) Sorting to perform. Can either be in the form of 
-  `fieldName`, or `fieldName:asc`/`fieldName:desc`. The fieldName can either be 
-  an actual field within the document, or the special `_score` name to indicate 
-  sorting based on scores. There can be several `sort` parameters (order is 
-  important).
-
-`track_scores`:: 
-  (Optional, boolean) When sorting, set to `true` in order to still track scores 
-  and return them as part of each hit.
-
-`track_total_hits`:: 
-  (Optional, integer) Defaults to `10,000`. Set to `false` in order to disable 
-  the tracking of the total number of hits that match the query. It also accepts 
-  an integer which in this case represents the number of hits to count 
-  accurately. (See the <<request-body-search-track-total-hits, request body>> 
-  documentation for more details).
-
-`timeout`::
-  (Optional, <<time-units, time units>>) A search timeout, bounding the search 
-  request to be executed within the specified time value and bail with the hits 
-  accumulated up to that point when expired. Defaults to no timeout.
-
-include::{docdir}/rest-api/common-parms.asciidoc[tag=terminate_after]
-
-
-[[search-uri-request-api-example]]
-==== {api-examples-title}
-
-[source,console]
---------------------------------------------------
-GET twitter/_search?q=user:kimchy
---------------------------------------------------
-// TEST[setup:twitter]
-
-
-The API returns the following response:
-
-[source,console-result]
---------------------------------------------------
-{
-    "timed_out": false,
-    "took": 62,
-    "_shards":{
-        "total" : 1,
-        "successful" : 1,
-        "skipped" : 0,
-        "failed" : 0
-    },
-    "hits":{
-        "total" : {
-            "value": 1,
-            "relation": "eq"
-        },
-        "max_score": 1.3862942,
-        "hits" : [
-            {
-                "_index" : "twitter",
-                "_id" : "0",
-                "_score": 1.3862942,
-                "_source" : {
-                    "user" : "kimchy",
-                    "date" : "2009-11-15T14:12:12",
-                    "message" : "trying out Elasticsearch",
-                    "likes": 0
-                }
-            }
-        ]
-    }
-}
---------------------------------------------------
-// TESTRESPONSE[s/"took": 62/"took": "$body.took"/]