From 79f26f83082c551e8a557398f0c7790e5972be2d Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Thu, 29 Aug 2019 10:38:48 -0400 Subject: [PATCH] [DOCS] Separate add index alias API docs (#46086) --- docs/reference/indices.asciidoc | 3 + docs/reference/indices/add-alias.asciidoc | 139 ++++++++++++++++++ docs/reference/indices/aliases.asciidoc | 119 --------------- docs/reference/rest-api/common-parms.asciidoc | 35 +++-- 4 files changed, 167 insertions(+), 129 deletions(-) create mode 100644 docs/reference/indices/add-alias.asciidoc diff --git a/docs/reference/indices.asciidoc b/docs/reference/indices.asciidoc index 7d1bf2fb30f..e9f617c6b72 100644 --- a/docs/reference/indices.asciidoc +++ b/docs/reference/indices.asciidoc @@ -34,6 +34,7 @@ index settings, aliases, mappings, and index templates. [float] [[alias-management]] === Alias management: +* <> * <> * <> * <> @@ -94,6 +95,8 @@ include::indices/get-field-mapping.asciidoc[] include::indices/types-exists.asciidoc[] +include::indices/add-alias.asciidoc[] + include::indices/get-alias.asciidoc[] include::indices/alias-exists.asciidoc[] diff --git a/docs/reference/indices/add-alias.asciidoc b/docs/reference/indices/add-alias.asciidoc new file mode 100644 index 00000000000..a5c7d4c49e9 --- /dev/null +++ b/docs/reference/indices/add-alias.asciidoc @@ -0,0 +1,139 @@ +[[indices-add-alias]] +=== Add index alias API +++++ +Add index alias +++++ + +Creates or updates an index alias. + +include::alias-exists.asciidoc[tag=index-alias-def] + +[source,js] +---- +PUT /twitter/_alias/alias1 +---- +// CONSOLE +// TEST[setup:twitter] + + +[[add-alias-api-request]] +==== {api-request-title} + +`PUT //_alias/` + +`POST //_alias/` + +`PUT //_aliases/` + +`POST //_aliases/` + + +[[add-alias-api-path-params]] +==== {api-path-parms-title} + +``:: +(Required, string) +Comma-separated list or wildcard expression of index names +to add to the alias. ++ +To add all indices in the cluster to the alias, +use a value of `_all`. + +``:: +(Required, string) +Name of the index alias to create or update. + + +[[add-alias-api-query-params]] +==== {api-query-parms-title} + +include::{docdir}/rest-api/common-parms.asciidoc[tag=timeoutparms] + + +[[add-alias-api-request-body]] +==== {api-request-body-title} + +`filter`:: +(Required, query object) +include::{docdir}/rest-api/common-parms.asciidoc[tag=index-alias-filter] + +include::{docdir}/rest-api/common-parms.asciidoc[tag=index-routing] + +[[add-alias-api-example]] +==== {api-examples-title} + +[[alias-adding]] +===== Add a time-based alias + +The following request creates an alias, `2030`, +for the `logs_20302801` index. + +[source,js] +-------------------------------------------------- +PUT /logs_20302801/_alias/2030 +-------------------------------------------------- +// CONSOLE +// TEST[s/^/PUT logs_20302801\n/] + +[[add-alias-api-user-ex]] +===== Add a user-based alias + +First, create an index, `users`, +with a mapping for the `user_id` field: + +[source,js] +-------------------------------------------------- +PUT /users +{ + "mappings" : { + "properties" : { + "user_id" : {"type" : "integer"} + } + } +} +-------------------------------------------------- +// CONSOLE + +Then add the index alias for a specific user, `user_12`: + +[source,js] +-------------------------------------------------- +PUT /users/_alias/user_12 +{ + "routing" : "12", + "filter" : { + "term" : { + "user_id" : 12 + } + } +} +-------------------------------------------------- +// CONSOLE +// TEST[continued] + +[[alias-index-creation]] +===== Add an alias during index creation + +You can use the <> +to add an index alias during index creation. + +[source,js] +-------------------------------------------------- +PUT /logs_20302801 +{ + "mappings" : { + "properties" : { + "year" : {"type" : "integer"} + } + }, + "aliases" : { + "current_day" : {}, + "2030" : { + "filter" : { + "term" : {"year" : 2030 } + } + } + } +} +-------------------------------------------------- +// CONSOLE diff --git a/docs/reference/indices/aliases.asciidoc b/docs/reference/indices/aliases.asciidoc index 03ef3a4ca5c..5ea2caa5d77 100644 --- a/docs/reference/indices/aliases.asciidoc +++ b/docs/reference/indices/aliases.asciidoc @@ -339,122 +339,3 @@ only reference one index, will have that referenced index behave as if it is the until an additional index is referenced. At that point, there will be no write index and writes will be rejected. ===================================== - -[float] -[[alias-adding]] -==== Add a single alias - -An alias can also be added with the endpoint - -`PUT /{index}/_alias/{name}` - - -where - -[horizontal] -`index`:: The index the alias refers to. Can be any of `* | _all | glob pattern | name1, name2, …` -`name`:: The name of the alias. This is a required option. -`routing`:: An optional routing that can be associated with an alias. -`filter`:: An optional filter that can be associated with an alias. - -You can also use the plural `_aliases`. - -[float] -===== Examples: - -Adding time based alias:: -+ --- -[source,js] --------------------------------------------------- -PUT /logs_201305/_alias/2013 --------------------------------------------------- -// CONSOLE -// TEST[s/^/PUT logs_201305\n/] --- - -Adding a user alias:: -+ --- -First create the index and add a mapping for the `user_id` field: - -[source,js] --------------------------------------------------- -PUT /users -{ - "mappings" : { - "properties" : { - "user_id" : {"type" : "integer"} - } - } -} --------------------------------------------------- -// CONSOLE - -Then add the alias for a specific user: - -[source,js] --------------------------------------------------- -PUT /users/_alias/user_12 -{ - "routing" : "12", - "filter" : { - "term" : { - "user_id" : 12 - } - } -} --------------------------------------------------- -// CONSOLE -// TEST[continued] - --- - -[float] -[[alias-index-creation]] -==== Aliases during index creation - -Aliases can also be specified during <>: - -[source,js] --------------------------------------------------- -PUT /logs_20162801 -{ - "mappings" : { - "properties" : { - "year" : {"type" : "integer"} - } - }, - "aliases" : { - "current_day" : {}, - "2016" : { - "filter" : { - "term" : {"year" : 2016 } - } - } - } -} --------------------------------------------------- -// CONSOLE - -[float] -[[deleting]] -==== Delete aliases - - -The rest endpoint is: `/{index}/_alias/{name}` - -where - -[horizontal] -`index`:: `* | _all | glob pattern | name1, name2, …` -`name`:: `* | _all | glob pattern | name1, name2, …` - -Alternatively you can use the plural `_aliases`. Example: - -[source,js] --------------------------------------------------- -DELETE /logs_20162801/_alias/current_day --------------------------------------------------- -// CONSOLE -// TEST[continued] diff --git a/docs/reference/rest-api/common-parms.asciidoc b/docs/reference/rest-api/common-parms.asciidoc index 897d2a4c41f..932e891a8c3 100644 --- a/docs/reference/rest-api/common-parms.asciidoc +++ b/docs/reference/rest-api/common-parms.asciidoc @@ -38,22 +38,19 @@ Wildcard expressions are not accepted. -- end::expand-wildcards[] -tag::cat-h[] -`h`:: -(Optional, string) Comma-separated list of column names to display. -end::cat-h[] - tag::flat-settings[] `flat_settings`:: (Optional, boolean) If `true`, returns settings in flat format. Defaults to `false`. end::flat-settings[] -tag::help[] -`help`:: -(Optional, boolean) If `true`, the response returns help information. Defaults -to `false`. -end::help[] +tag::index-alias-filter[] +<> +used to limit the index alias. ++ +If specified, +the index alias only applies to documents returned by the filter. +end::index-alias-filter[] tag::http-format[] `format`:: @@ -62,6 +59,17 @@ https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html[HTTP accept header]. Valid values include JSON, YAML, etc. end::http-format[] +tag::cat-h[] +`h`:: +(Optional, string) Comma-separated list of column names to display. +end::cat-h[] + +tag::help[] +`help`:: +(Optional, boolean) If `true`, the response returns help information. Defaults +to `false`. +end::help[] + tag::include-defaults[] `include_defaults`:: (Optional, string) If `true`, return all default settings in the response. @@ -153,6 +161,13 @@ tag::doc-routing[] (Optional, string) Target the specified primary shard. end::doc-routing[] +tag::index-routing[] +`routing`:: +(Optional, string) +Custom <> +used to route operations to a specific shard. +end::index-routing[] + tag::doc-version[] `version`:: (Optional, integer) Explicit version number for concurrency control.