From d3a6847b36729ba7815e6c7fd4cbd86cde0acc7b Mon Sep 17 00:00:00 2001 From: James Rodewig <40268737+jrodewig@users.noreply.github.com> Date: Wed, 2 Jun 2021 08:43:19 -0400 Subject: [PATCH] [DOCS] Reuse `aliases` object properties in API docs (#73421) (#73661) Changes: * Reuses the same `aliases` object properties in the following API docs: * Clone index API * Create index API * Put component template API * Put legacy index template API * Put index template API * Rollover index API * Shrink index API * Simulate template API * Split index API * Updates the `aliases` object properties for the simulate index API docs. Closes #73044 --- docs/reference/indices/clone-index.asciidoc | 5 ++- docs/reference/indices/create-index.asciidoc | 26 ++++++++------ .../indices/put-component-template.asciidoc | 13 +++++-- .../indices/put-index-template-v1.asciidoc | 7 ++-- .../indices/put-index-template.asciidoc | 6 ++-- .../reference/indices/rollover-index.asciidoc | 6 ++-- docs/reference/indices/shrink-index.asciidoc | 5 ++- .../reference/indices/simulate-index.asciidoc | 35 +++++++++++++++++-- .../indices/simulate-template.asciidoc | 6 +++- docs/reference/indices/split-index.asciidoc | 5 ++- docs/reference/rest-api/common-parms.asciidoc | 6 ---- 11 files changed, 88 insertions(+), 32 deletions(-) diff --git a/docs/reference/indices/clone-index.asciidoc b/docs/reference/indices/clone-index.asciidoc index 8e4faf3ba7873..b8f3ac6ebac22 100644 --- a/docs/reference/indices/clone-index.asciidoc +++ b/docs/reference/indices/clone-index.asciidoc @@ -174,6 +174,9 @@ include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=timeoutparms] [[clone-index-api-request-body]] ==== {api-request-body-title} -include::{es-repo-dir}/indices/create-index.asciidoc[tag=aliases] +`aliases`:: +(Optional, object of objects) Aliases for the resulting index. ++ +include::{es-repo-dir}/indices/create-index.asciidoc[tag=aliases-props] include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=target-index-settings] diff --git a/docs/reference/indices/create-index.asciidoc b/docs/reference/indices/create-index.asciidoc index 2384fc535ce4b..42690658f1b1e 100644 --- a/docs/reference/indices/create-index.asciidoc +++ b/docs/reference/indices/create-index.asciidoc @@ -21,7 +21,9 @@ PUT /my-index-000001 ==== {api-prereq-title} * If the {es} {security-features} are enabled, you must have the `create_index` -or `manage` <> for the target index. +or `manage` <> for the target index. To +add the index to an alias, you must have the `manage` index privilege for the +alias. [[indices-create-api-desc]] ==== {api-description-title} @@ -68,13 +70,14 @@ include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=timeoutparms] [[indices-create-api-request-body]] ==== {api-request-body-title} -// tag::aliases[] `aliases`:: -(Optional, object) Aliases for the index. +(Optional, object of objects) Aliases for the index. + -.Properties of `aliases` objects +-- +// tag::aliases-props[] [%collapsible%open] -==== +.Properties of `aliases` objects +======= ``:: (Required, object) The key is the alias name. Supports <>. @@ -83,9 +86,9 @@ The object body contains options for the alias. Supports an empty object. + .Properties of `` [%collapsible%open] -===== +====== `filter`:: -(Optional, <>) Query used to limit the documents the +(Optional, <>) Query used to limit documents the alias can access. `index_routing`:: @@ -94,7 +97,7 @@ If specified, this overwrites the `routing` value for indexing operations. `is_hidden`:: (Optional, Boolean) If `true`, the alias is <>. Defaults to -`false`. +`false`. All indices for the alias must have the same `is_hidden` value. `is_write_index`:: (Optional, Boolean) If `true`, the index is the <> for @@ -107,9 +110,10 @@ specific shard. `search_routing`:: (Optional, string) Value used to route search operations to a specific shard. If specified, this overwrites the `routing` value for search operations. -===== -==== -// end::aliases[] +====== +======= +// end::aliases-props[] +-- include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=mappings] diff --git a/docs/reference/indices/put-component-template.asciidoc b/docs/reference/indices/put-component-template.asciidoc index e5000a59e496b..7100f0dbd9706 100644 --- a/docs/reference/indices/put-component-template.asciidoc +++ b/docs/reference/indices/put-component-template.asciidoc @@ -119,6 +119,7 @@ Defaults to `false`. include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=master-timeout] +[role="child_attributes"] [[put-component-template-api-request-body]] ==== {api-request-body-title} @@ -126,14 +127,20 @@ include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=master-timeout] (Required, object) This is the template to be applied, may optionally include a `mappings`, `settings`, or `aliases` configuration. - -include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=aliases] + -NOTE: You cannot add data streams to an index alias. +.Properties of `template` +[%collapsible%open] +==== +`aliases`:: +(Optional, object of objects) Aliases for the index. If an index template +includes `data_stream`, this parameter is not supported. ++ +include::{es-repo-dir}/indices/create-index.asciidoc[tag=aliases-props] include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=mappings] include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=settings] +==== `version`:: (Optional, integer) diff --git a/docs/reference/indices/put-index-template-v1.asciidoc b/docs/reference/indices/put-index-template-v1.asciidoc index 2de6d0bacdc73..7b898c6e5d4a3 100644 --- a/docs/reference/indices/put-index-template-v1.asciidoc +++ b/docs/reference/indices/put-index-template-v1.asciidoc @@ -114,7 +114,7 @@ overriding templates with lower values. include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=master-timeout] - +[role="child_attributes"] [[put-index-template-v1-api-request-body]] ==== {api-request-body-title} @@ -123,7 +123,10 @@ include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=master-timeout] Array of wildcard expressions used to match the names of indices during creation. -include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=aliases] +`aliases`:: +(Optional, object of objects) Aliases for the index. ++ +include::{es-repo-dir}/indices/create-index.asciidoc[tag=aliases-props] include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=mappings] diff --git a/docs/reference/indices/put-index-template.asciidoc b/docs/reference/indices/put-index-template.asciidoc index df31fc142f942..8968cccbb9118 100644 --- a/docs/reference/indices/put-index-template.asciidoc +++ b/docs/reference/indices/put-index-template.asciidoc @@ -136,9 +136,11 @@ Template to be applied. It may optionally include an `aliases`, `mappings`, or .Properties of `template` [%collapsible%open] ==== -include::{docdir}/rest-api/common-parms.asciidoc[tag=aliases] +`aliases`:: +(Optional, object of objects) Aliases for the index. If the index template +includes `data_stream`, this parameter is not supported. + -NOTE: You cannot add data streams to an index alias. +include::{es-repo-dir}/indices/create-index.asciidoc[tag=aliases-props] include::{docdir}/rest-api/common-parms.asciidoc[tag=mappings] diff --git a/docs/reference/indices/rollover-index.asciidoc b/docs/reference/indices/rollover-index.asciidoc index 5e7ea331fd471..26d13634b5c89 100644 --- a/docs/reference/indices/rollover-index.asciidoc +++ b/docs/reference/indices/rollover-index.asciidoc @@ -124,9 +124,11 @@ include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=timeoutparms] [[rollover-index-api-request-body]] ==== {api-request-body-title} -include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=aliases] +`aliases`:: +(Optional, object of objects) Aliases for the target index. Data streams do not +support this parameter. + -Data streams do not support this parameter. +include::{es-repo-dir}/indices/create-index.asciidoc[tag=aliases-props] [[rollover-conditions]] `conditions`:: diff --git a/docs/reference/indices/shrink-index.asciidoc b/docs/reference/indices/shrink-index.asciidoc index bdd508d83410e..6b5cbe0fdc0a4 100644 --- a/docs/reference/indices/shrink-index.asciidoc +++ b/docs/reference/indices/shrink-index.asciidoc @@ -227,7 +227,10 @@ include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=timeoutparms] [[shrink-index-api-request-body]] ==== {api-request-body-title} -include::{es-repo-dir}/indices/create-index.asciidoc[tag=aliases] +`aliases`:: +(Optional, object of objects) Aliases for the resulting index. ++ +include::{es-repo-dir}/indices/create-index.asciidoc[tag=aliases-props] include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=target-index-settings] diff --git a/docs/reference/indices/simulate-index.asciidoc b/docs/reference/indices/simulate-index.asciidoc index 2546e15965a2a..9783cca0b1712 100644 --- a/docs/reference/indices/simulate-index.asciidoc +++ b/docs/reference/indices/simulate-index.asciidoc @@ -89,9 +89,40 @@ The settings, mappings, and aliases that would be applied to the index. .Properties of `template` [%collapsible%open] ==== -include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=aliases] +`aliases`:: +(object) Aliases for the index. If no aliases apply, the response returns an +empty `aliases` object. + -Response includes an empty object if no aliases would be applied. +===== +``:: +(object) The key is the alias name. The object body contains options for the +alias. ++ +.Properties of `` +[%collapsible%open] +====== +`filter`:: +(<>) Query used to limit documents the alias can +access. + +`index_routing`:: +(string) Value used to route indexing operations to a specific shard. This +overwrites the `routing` value for indexing operations. + +`is_hidden`:: +(Boolean) If `true`, the alias is <>. + +`is_write_index`:: +(Boolean) If `true`, the index is the <> for the alias. + +`routing`:: +(string) Value used to route indexing and search operations to a specific shard. + +`search_routing`:: +(string) Value used to route search operations to a specific shard. This +overwrites the `routing` value for search operations. +====== +===== include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=mappings] + diff --git a/docs/reference/indices/simulate-template.asciidoc b/docs/reference/indices/simulate-template.asciidoc index d26585a3894ea..b40fde77036d6 100644 --- a/docs/reference/indices/simulate-template.asciidoc +++ b/docs/reference/indices/simulate-template.asciidoc @@ -124,7 +124,11 @@ The settings, mappings, and aliases that would be applied to matching indices. .Properties of `template` [%collapsible%open] ==== -include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=aliases] +`aliases`:: +(Optional, object of objects) Aliases for the index. If the index template +includes `data_stream`, this parameter is not supported. ++ +include::{es-repo-dir}/indices/create-index.asciidoc[tag=aliases-props] include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=mappings] diff --git a/docs/reference/indices/split-index.asciidoc b/docs/reference/indices/split-index.asciidoc index 437e264e6a0b0..83d4183dcc2f4 100644 --- a/docs/reference/indices/split-index.asciidoc +++ b/docs/reference/indices/split-index.asciidoc @@ -277,6 +277,9 @@ include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=timeoutparms] [[split-index-api-request-body]] ==== {api-request-body-title} -include::{es-repo-dir}/indices/create-index.asciidoc[tag=aliases] +`aliases`:: +(Optional, object of objects) Aliases for the resulting index. ++ +include::{es-repo-dir}/indices/create-index.asciidoc[tag=aliases-props] include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=target-index-settings] diff --git a/docs/reference/rest-api/common-parms.asciidoc b/docs/reference/rest-api/common-parms.asciidoc index 9cd55230e7fca..de0f4335df547 100644 --- a/docs/reference/rest-api/common-parms.asciidoc +++ b/docs/reference/rest-api/common-parms.asciidoc @@ -20,12 +20,6 @@ the response only includes ongoing shard recoveries. Defaults to `false`. end::active-only[] -tag::aliases[] -`aliases`:: -(Optional, <>) Index aliases which include the index. Index -alias names support <>. -end::aliases[] - tag::allow-no-indices[] `allow_no_indices`:: (Optional, Boolean)