From 7940e0777ce1f167a40eab55e57b4ce36c796aa6 Mon Sep 17 00:00:00 2001
From: James Rodewig <40268737+jrodewig@users.noreply.github.com>
Date: Mon, 25 Oct 2021 11:58:54 -0400
Subject: [PATCH] [DOCS] Re-add several query params to search API docs
 (#79716)

PR #55884 removed documentation for several query parameters from the search API
docs. During tests, I failed to notice that these are valid parameters but require other parameters to use.

Changes:

* Notes the following search API parameters require the `q` query string parameter:

  * `analyzer`
  * `analyze_wildcard`
  * `default_operator`
  * `df`
  * `lenient`

* Notes the following search API parameters require the `suggest_field` and `suggest_text` query parameters:

  * `suggest_mode`
  * `suggest_size`

* Re-adds the above parameters to the search API docs.

These changes also affect API documentation that reuses the search API parameters:

* Delete by query API
* Update by query API
* Count API
* Explain API
* Validate API

Closes #79674
---
 docs/reference/rest-api/common-parms.asciidoc | 28 ++++++++++++----
 docs/reference/search/search.asciidoc         | 33 +++++++++++++++++++
 2 files changed, 55 insertions(+), 6 deletions(-)

diff --git a/docs/reference/rest-api/common-parms.asciidoc b/docs/reference/rest-api/common-parms.asciidoc
index f886bd2fd27fa..c0fe9c9d244f8 100644
--- a/docs/reference/rest-api/common-parms.asciidoc
+++ b/docs/reference/rest-api/common-parms.asciidoc
@@ -67,12 +67,18 @@ end::allow-no-match-transforms2[]
 tag::analyzer[]
 `analyzer`::
 (Optional, string) Analyzer to use for the query string.
++
+This parameter can only be used when the `q` query string parameter is
+specified.
 end::analyzer[]
 
 tag::analyze_wildcard[]
 `analyze_wildcard`::
-(Optional, Boolean) If `true`, wildcard and prefix queries are
-analyzed. Defaults to `false`.
+(Optional, Boolean) If `true`, wildcard and prefix queries are analyzed.
+Defaults to `false`.
++
+This parameter can only be used when the `q` query string parameter is
+specified.
 end::analyze_wildcard[]
 
 tag::bytes[]
@@ -132,6 +138,9 @@ tag::default_operator[]
 `default_operator`::
 (Optional, string) The default operator for query string query: AND or OR.
 Defaults to `OR`.
++
+This parameter can only be used when the `q` query string parameter is
+specified.
 end::default_operator[]
 
 tag::dest[]
@@ -160,8 +169,11 @@ end::detailed[]
 
 tag::df[]
 `df`::
-(Optional, string) Field to use as default where no field prefix is
-given in the query string.
+(Optional, string) Field to use as default where no field prefix is given in the
+query string.
++
+This parameter can only be used when the `q` query string parameter is
+specified.
 end::df[]
 
 tag::docs-count[]
@@ -530,8 +542,12 @@ end::component-template[]
 
 tag::lenient[]
 `lenient`::
-(Optional, Boolean) If `true`, format-based query failures (such as
-providing text to a numeric field) will be ignored. Defaults to `false`.
+(Optional, Boolean) If `true`, format-based query failures (such as providing
+text to a numeric field) in the query string will be ignored. Defaults to
+`false`.
++
+This parameter can only be used when the `q` query string parameter is
+specified.
 end::lenient[]
 
 tag::level[]
diff --git a/docs/reference/search/search.asciidoc b/docs/reference/search/search.asciidoc
index 6173727d345f1..e09e924528c7b 100644
--- a/docs/reference/search/search.asciidoc
+++ b/docs/reference/search/search.asciidoc
@@ -70,6 +70,10 @@ no partial results. Defaults to `true`.
 To override the default for this field, set the
 `search.default_allow_partial_results` cluster setting to `false`.
 
+include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=analyzer]
+
+include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=analyze_wildcard]
+
 `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
@@ -82,6 +86,10 @@ shards in the request can be large. Defaults to `512`.
 coordinating node and the remote clusters are minimized when executing
 {ccs} (CCS) requests. See <<ccs-network-delays>>. Defaults to `true`.
 
+include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=default_operator]
+
+include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=df]
+
 `docvalue_fields`::
 (Optional, string) A comma-separated list of fields to return as the docvalue
 representation of a field for each hit.
@@ -106,6 +114,8 @@ ignored when frozen. Defaults to `true`.
 
 include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=index-ignore-unavailable]
 
+include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=lenient]
+
 `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
@@ -274,9 +284,32 @@ stored fields in the search response.
 `suggest_field`::
 (Optional, string) Specifies which field to use for suggestions.
 
+`suggest_mode`::
+(Optional, string) Specifies the <<search-suggesters,suggest mode>>. Defaults to
+`missing`. Available options:
++
+--
+
+* `always`
+* `missing`
+* `popular`
+
+This parameter can only be used when the `suggest_field` and `suggest_text`
+query string parameters are specified.
+--
+
+`suggest_size`::
+(Optional, integer) Number of <<search-suggesters,suggestions>> to return.
++
+This parameter can only be used when the `suggest_field` and `suggest_text`
+query string parameters are specified.
+
 `suggest_text`::
 (Optional, string) The source text for which the suggestions should be
 returned.
++
+This parameter can only be used when the `suggest_field` query string parameter
+is specified.
 
 include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=terminate_after]
 +