[DOCS] Remove invalid search API query parameters (#55884) (#56212)

This is a backport of #55884 with redirects removed.

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`
* Replaces the URI search page's query parameter docs with a xref
* Updates the headings of several examples

docs/reference/search/search.asciidoc

@@ -1,11 +1,14 @@
 [[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]
 
@@ -15,10 +18,10 @@ GET /twitter/_search?q=tag:wow
 
 `GET /<index>/_search`
 
-`POST /<index>/_search`
-
 `GET /_search`
 
+`POST /<index>/_search`
+
 `POST /_search`
 
 
@@ -26,23 +29,14 @@ GET /twitter/_search?q=tag:wow
 ==== {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
+query. You can provide search queries using the <<search-api-query-params-q,`q`
-<<search-uri-request,query string as a parameter>>, or using a
+query string parameter>> or <<search-request-body,request body>>.
-<<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.
 
 [[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 +44,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
+(Optional, boolean)
-  partial search failure or timeout. Defaults to `true`.
+If `true`, returns partial results if there are request timeouts or
-
+<<shard-failures,shard failures>>. If `false`, returns an error with
-`analyzer`::
+no partial results. Defaults to `true`.
-  (Optional, string) Defines the analyzer to use for the query string.
++
-
+To override the default for this field, set the 
-`analyze_wildcard`::
+`search.default_allow_partial_results` cluster setting to `false`.
-  (Optional, boolean) If `true`, wildcard and prefix queries will also be
-  analyzed. Defaults to `false`.
 
 `batched_reduce_size`::
   (Optional, integer) The number of shard results that should be reduced at once
@@ -71,14 +64,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 +76,7 @@ Defaults to `open`.
   (Optional, boolean) If `true`, returns detailed information about score
   computation as part of a hit. Defaults to `false`.
 
-`from`::
+include::{docdir}/rest-api/common-parms.asciidoc[tag=from]
-  (Optional, integer) Defines the starting offset. Defaults to `0`.
 
 `ignore_throttled`::
   (Optional, boolean) If `true`, concrete, expanded or aliased indices will be
@@ -100,10 +84,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
@@ -126,8 +106,21 @@ 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.
 
-`q`::
+[[search-api-query-params-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.
@@ -141,11 +134,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`::
+include::{docdir}/rest-api/common-parms.asciidoc[tag=search_type]
-  (Optional, string) Defines the type of the search operation. Available
-  options:
-  * `query_then_fetch`
-  * `dfs_query_then_fetch`
 
 `seq_no_primary_term`::
   (Optional, boolean) If `true`, returns sequence number and primary term of the
@@ -158,16 +147,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
+(Optional, boolean)
-  list of fields to return.
+If `true`, the response includes the `_source` of matching documents under
+`hits`. Defaults to `true`.
 
-`_source_excludes`::
+include::{docdir}/rest-api/common-parms.asciidoc[tag=source_excludes]
-  (Optional, string) A list of fields to exclude from the returned `_source`
-  field.
 
-`_source_includes`::
+include::{docdir}/rest-api/common-parms.asciidoc[tag=source_includes]
-  (Optional, string) A list of fields to extract and return from the `_source`
-  field.
 
 `stats`::
   (Optional, string) Specific `tag` of the request for logging and statistical
@@ -175,28 +161,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`::
+include::{docdir}/rest-api/common-parms.asciidoc[tag=terminate_after]
-  (Optional, integer) The maximum number of documents to collect for each shard,
++
-  upon reaching which the query execution will terminate early.
+Defaults to `0`, which does not terminate query execution early.
 
 `timeout`::
   (Optional, <<time-units, time units>>) Specifies the period of time to wait
@@ -204,24 +181,29 @@ 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
+  (Optional, boolean) If `true`, calculate and return document scores, even if
-  are not used for sorting.
+  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
+(Optional, integer or boolean)
-  should be tracked.
+Number of hits matching the query to count accurately. Defaults to `10000`.
++
+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
+  (Optional, boolean) If `true`, aggregation and suggester names are be prefixed
-  be prefixed by their respective types in the response.
+  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]]
 ==== {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>>.
@@ -367,7 +349,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]
 ----
@@ -414,7 +396,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]
 ----
@@ -423,7 +405,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

@@ -33,77 +33,7 @@ include::{docdir}/rest-api/common-parms.asciidoc[tag=index]
 [[search-uri-request-api-query-params]]
 ==== {api-query-parms-title}
 
-`allow_partial_search_results`:: 
+See the <<search-search-api-query-params,search API's query parameters>>.
-  (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]]