Browse Source

[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
James Rodewig 4 years ago
parent
commit
7940e0777c

+ 22 - 6
docs/reference/rest-api/common-parms.asciidoc

@@ -67,12 +67,18 @@ end::allow-no-match-transforms2[]
 tag::analyzer[]
 tag::analyzer[]
 `analyzer`::
 `analyzer`::
 (Optional, string) Analyzer to use for the query string.
 (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[]
 end::analyzer[]
 
 
 tag::analyze_wildcard[]
 tag::analyze_wildcard[]
 `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[]
 end::analyze_wildcard[]
 
 
 tag::bytes[]
 tag::bytes[]
@@ -132,6 +138,9 @@ tag::default_operator[]
 `default_operator`::
 `default_operator`::
 (Optional, string) The default operator for query string query: AND or OR.
 (Optional, string) The default operator for query string query: AND or OR.
 Defaults to `OR`.
 Defaults to `OR`.
++
+This parameter can only be used when the `q` query string parameter is
+specified.
 end::default_operator[]
 end::default_operator[]
 
 
 tag::dest[]
 tag::dest[]
@@ -160,8 +169,11 @@ end::detailed[]
 
 
 tag::df[]
 tag::df[]
 `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[]
 end::df[]
 
 
 tag::docs-count[]
 tag::docs-count[]
@@ -530,8 +542,12 @@ end::component-template[]
 
 
 tag::lenient[]
 tag::lenient[]
 `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[]
 end::lenient[]
 
 
 tag::level[]
 tag::level[]

+ 33 - 0
docs/reference/search/search.asciidoc

@@ -70,6 +70,10 @@ no partial results. Defaults to `true`.
 To override the default for this field, set the
 To override the default for this field, set the
 `search.default_allow_partial_results` cluster setting to `false`.
 `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`::
 `batched_reduce_size`::
 (Optional, integer) The number of shard results that should be reduced at once
 (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
 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
 coordinating node and the remote clusters are minimized when executing
 {ccs} (CCS) requests. See <<ccs-network-delays>>. Defaults to `true`.
 {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`::
 `docvalue_fields`::
 (Optional, string) A comma-separated list of fields to return as the docvalue
 (Optional, string) A comma-separated list of fields to return as the docvalue
 representation of a field for each hit.
 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=index-ignore-unavailable]
 
 
+include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=lenient]
+
 `max_concurrent_shard_requests`::
 `max_concurrent_shard_requests`::
 (Optional, integer) Defines the number of concurrent shard requests per node
 (Optional, integer) Defines the number of concurrent shard requests per node
 this search executes concurrently. This value should be used to limit the
 this search executes concurrently. This value should be used to limit the
@@ -274,9 +284,32 @@ stored fields in the search response.
 `suggest_field`::
 `suggest_field`::
 (Optional, string) Specifies which field to use for suggestions.
 (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`::
 `suggest_text`::
 (Optional, string) The source text for which the suggestions should be
 (Optional, string) The source text for which the suggestions should be
 returned.
 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]
 include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=terminate_after]
 +
 +