Skip to content

Commit

Permalink
[DOCS] Re-add several query params to search API docs (elastic#79716)
Browse files Browse the repository at this point in the history
PR elastic#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 elastic#79674
  • Loading branch information
jrodewig authored and Adam Locke committed Oct 28, 2021
1 parent 1daa56e commit d547eae
Show file tree
Hide file tree
Showing 2 changed files with 55 additions and 6 deletions.
28 changes: 22 additions & 6 deletions docs/reference/rest-api/common-parms.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -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[]
Expand Down Expand Up @@ -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[]
Expand Down Expand Up @@ -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[]
Expand Down Expand Up @@ -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[]
Expand Down
33 changes: 33 additions & 0 deletions docs/reference/search/search.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.
Expand All @@ -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
Expand Down Expand Up @@ -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]
+
Expand Down

0 comments on commit d547eae

Please sign in to comment.