From 3bb11cf2694aac41f8015c388f53bb8bb914da0f Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Tue, 2 Jun 2020 11:58:46 -0400 Subject: [PATCH] [DOCS] Refactor admons for multi-parameter options (#57491) Several APIs support options that can be specified as a query parameter or a request body parameter. Currently, this is documented using notes, which can get rather lengthy. This replaces those multiple notes with a single note and a footnote. --- docs/reference/search/search.asciidoc | 131 ++---------------- .../apis/put-repo-api.asciidoc | 25 +--- 2 files changed, 15 insertions(+), 141 deletions(-) diff --git a/docs/reference/search/search.asciidoc b/docs/reference/search/search.asciidoc index 4a6e9cbabe793..40a66e221710d 100644 --- a/docs/reference/search/search.asciidoc +++ b/docs/reference/search/search.asciidoc @@ -38,6 +38,10 @@ include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=index] [[search-search-api-query-params]] ==== {api-query-parms-title} +IMPORTANT: Several options for this API can be specified using a query parameter +or a request body parameter. If both parameters are specified, only the query +parameter is used. + include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=allow-no-indices] + Defaults to `true`. @@ -75,14 +79,6 @@ Defaults to `open`. `explain`:: (Optional, boolean) If `true`, returns detailed information about score computation as part of a hit. Defaults to `false`. -+ --- -[IMPORTANT] -==== -You can also specify this value using the `explain` request body parameter. If -both parameters are specified, only the query parameter is used. -==== --- include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=from] + @@ -100,12 +96,6 @@ correct. As an alternative to deep paging, we recommend using <> or the <> parameter. - -[IMPORTANT] -==== -You can also specify this value using the `from` request body parameter. If -both parameters are specified, only the query parameter is used. -==== -- `ignore_throttled`:: @@ -139,18 +129,14 @@ include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=index-ignore-unavailab [[search-api-query-params-q]] include::{es-repo-dir}/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} <> but are handy for testing. - -[IMPORTANT] -==== -The `q` parameter overrides the <> ++ +IMPORTANT: The `q` parameter overrides the <> parameter in the request body. If both parameters are specified, documents -matching the `query` request body parameter are not returned. -==== --- +matching the `query` request body parameter are not returned. + `request_cache`:: (Optional, boolean) If `true`, the caching of search results is enabled for @@ -177,18 +163,9 @@ this limit using the `search.max_keep_alive` cluster-level setting. include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=search_type] `seq_no_primary_term`:: -+ --- (Optional, boolean) If `true`, returns sequence number and primary term of the last modification of each hit. See <>. -[IMPORTANT] -==== -You can also specify this value using the `seq_no_primary_term` request body -parameter. If both parameters are specified, only the query parameter is used. -==== --- - `size`:: (Optional, integer) Defines the number of hits to return. Defaults to `10`. + @@ -208,13 +185,7 @@ As an alternative to deep paging, we recommend using <> parameter. If the <> is specified, this -value cannot be zero (`0`). - -[IMPORTANT] -==== -You can also specify this value using the `size` request body parameter. If -both parameters are specified, only the query parameter is used. -==== +value cannot be `0`. -- `sort`:: @@ -247,30 +218,13 @@ include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=source_includes] include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=terminate_after] + --- Defaults to `0`, which does not terminate query execution early. -[IMPORTANT] -==== -You can also specify this value using the `terminate_after` request body -parameter. If both parameters are specified, only the query parameter is used. -==== --- - `timeout`:: -+ --- (Optional, <>) Specifies the period of time to wait for a response. If no response is received before the timeout expires, the request fails and returns an error. Defaults to no timeout. -[IMPORTANT] -==== -You can also specify this value using the `timeout` request body -parameter. If both parameters are specified, only the query parameter is used. -==== --- - `track_scores`:: (Optional, boolean) If `true`, calculate and return document scores, even if the scores are not used for sorting. Defaults to `false`. @@ -287,19 +241,9 @@ include the total number of hits matching the query. by their respective types in the response. Defaults to `true`. `version`:: -+ --- (Optional, boolean) If `true`, returns document version as part of a hit. Defaults to `false`. -[IMPORTANT] -==== -You can also specify this value using the `version` request body parameter. If -both parameters are specified, only the query parameter is used. -==== --- - - [[search-search-api-request-body]] ==== {api-request-body-title} @@ -307,14 +251,6 @@ both parameters are specified, only the query parameter is used. `explain`:: (Optional, boolean) If `true`, returns detailed information about score computation as part of a hit. Defaults to `false`. -+ --- -[IMPORTANT] -==== -You can also specify this value using the `explain` query parameter. If -both parameters are specified, only the query parameter is used. -==== --- include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=from] + @@ -332,12 +268,6 @@ correct. As an alternative to deep paging, we recommend using <> or the <> parameter. - -[IMPORTANT] -==== -You can also specify this value using the `from` query parameter. If both -parameters are specified, only the query parameter is used. -==== -- [[request-body-search-query]] @@ -347,18 +277,9 @@ parameters are specified, only the query parameter is used. [[request-body-search-seq-no-primary-term]] `seq_no_primary_term`:: -+ --- (Optional, boolean) If `true`, returns sequence number and primary term of the last modification of each hit. See <>. -[IMPORTANT] -==== -You can also specify this value using the `seq_no_primary_term` query parameter. -If both parameters are specified, only the query parameter is used. -==== --- - `size`:: (Optional, integer) The number of hits to return. Needs to be non-negative and defaults to `10`. + @@ -378,55 +299,23 @@ As an alternative to deep paging, we recommend using <> parameter. If the <> is specified, this -value cannot be zero (`0`). - -[IMPORTANT] -==== -You can also specify this value using the `size` query parameter. If both -parameters are specified, only the query parameter is used. -==== +value cannot be `0`. -- include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=terminate_after] + --- Defaults to `0`, which does not terminate query execution early. -[IMPORTANT] -==== -You can also specify this value using the `terminate_after` query parameter. If -both parameters are specified, only the query parameter is used. -==== --- - `timeout`:: -+ --- (Optional, <>) Specifies the period of time to wait for a response. If no response is received before the timeout expires, the request fails and returns an error. Defaults to no timeout. -[IMPORTANT] -==== -You can also specify this value using the `timeout` query parameter. If both -parameters are specified, only the query parameter is used. -==== --- - [[request-body-search-version]] `version`:: -+ --- (Optional, boolean) If `true`, returns document version as part of a hit. Defaults to `false`. -[IMPORTANT] -==== -You can also specify this value using the `version` query parameter. If both -parameters are specified, only the query parameter is used. -==== --- - [role="child_attributes"] [[search-api-response-body]] diff --git a/docs/reference/snapshot-restore/apis/put-repo-api.asciidoc b/docs/reference/snapshot-restore/apis/put-repo-api.asciidoc index 11f9b4d3f2a77..714554a410475 100644 --- a/docs/reference/snapshot-restore/apis/put-repo-api.asciidoc +++ b/docs/reference/snapshot-restore/apis/put-repo-api.asciidoc @@ -46,22 +46,19 @@ Name of the snapshot repository to register or update. [[put-snapshot-repo-api-query-params]] ==== {api-query-parms-title} +IMPORTANT: Several options for this API can be specified using a query parameter +or a request body parameter. If both parameters are specified, only the query +parameter is used. + `master_timeout`:: (Optional, <>) Specifies the period of time to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error. Defaults to `30s`. -+ -IMPORTANT: You can also specify this value using the `master_timeout` request -body parameter. If both parameters are specified, only the query parameter is -used. `timeout`:: (Optional, <>) Specifies the period of time to wait for a response. If no response is received before the timeout expires, the request fails and returns an error. Defaults to `30s`. -+ -IMPORTANT: You can also specify this value using the `timeout` request body -parameter. If both parameters are specified, only the query parameter is used. `verify`:: (Optional, boolean) @@ -71,9 +68,6 @@ data nodes in the cluster. If `false`, this verification is skipped. Defaults to + You can manually perform this verification using the <>. -+ -IMPORTANT: You can also specify this value using the `verify` request body -parameter. If both parameters are specified, only the query parameter is used. [role="child_attributes"] [[put-snapshot-repo-api-request-body]] @@ -84,18 +78,12 @@ parameter. If both parameters are specified, only the query parameter is used. Specifies the period of time to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error. Defaults to `30s`. -+ -IMPORTANT: You can also specify this value using the `master_timeout` query -parameter. If both parameters are specified, only the query parameter is used. `timeout`:: (Optional, <>) Specifies the period of time to wait for a response. If no response is received before the timeout expires, the request fails and returns an error. Defaults to `30s`. -+ -IMPORTANT: You can also specify this value using the `timeout` query -parameter. If both parameters are specified, only the query parameter is used. [[put-snapshot-repo-api-request-type]] `type`:: @@ -261,7 +249,4 @@ data nodes in the cluster. If `false`, this verification is skipped. Defaults to `true`. + You can manually perform this verification using the -<>. -+ -IMPORTANT: You can also specify this value using the `verify` query -parameter. If both parameters are specified, only the query parameter is used. \ No newline at end of file +<>. \ No newline at end of file