From 75fb81ae712ab5c111b0d4a993141e7a87672185 Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Tue, 27 Aug 2019 21:37:07 -0400 Subject: [PATCH 1/2] [DOCS] Separate add index alias API docs --- docs/reference/indices.asciidoc | 3 + docs/reference/indices/add-alias.asciidoc | 137 ++++++++++ docs/reference/indices/aliases.asciidoc | 236 ------------------ docs/reference/rest-api/common-parms.asciidoc | 20 ++ 4 files changed, 160 insertions(+), 236 deletions(-) create mode 100644 docs/reference/indices/add-alias.asciidoc diff --git a/docs/reference/indices.asciidoc b/docs/reference/indices.asciidoc index 6769d786a6917..17c219705921d 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: +* <> * <> * <> @@ -93,6 +94,8 @@ include::indices/get-field-mapping.asciidoc[] include::indices/types-exists.asciidoc[] +include::indices/add-alias.asciidoc[] + include::indices/alias-exists.asciidoc[] include::indices/aliases.asciidoc[] diff --git a/docs/reference/indices/add-alias.asciidoc b/docs/reference/indices/add-alias.asciidoc new file mode 100644 index 0000000000000..b18adc2b327fc --- /dev/null +++ b/docs/reference/indices/add-alias.asciidoc @@ -0,0 +1,137 @@ +[[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} + +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 bc207b9f226b0..5ea2caa5d77d1 100644 --- a/docs/reference/indices/aliases.asciidoc +++ b/docs/reference/indices/aliases.asciidoc @@ -339,239 +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] - -[float] -[[alias-retrieving]] -==== Retrieving existing aliases - -The get index alias API allows to filter by -alias name and index name. This api redirects to the master and fetches -the requested index aliases, if available. This api only serialises the -found index aliases. - -Possible options: -[horizontal] -`index`:: - The index name to get aliases for. Partial names are - supported via wildcards, also multiple index names can be specified - separated with a comma. Also the alias name for an index can be used. - -`alias`:: - The name of alias to return in the response. Like the index - option, this option supports wildcards and the option the specify - multiple alias names separated by a comma. - -`ignore_unavailable`:: - What to do if an specified index name doesn't - exist. If set to `true` then those indices are ignored. - -The rest endpoint is: `/{index}/_alias/{alias}`. - -[float] -===== Examples: - -All aliases for the index `logs_20162801`: - -[source,js] --------------------------------------------------- -GET /logs_20162801/_alias/* --------------------------------------------------- -// CONSOLE -// TEST[continued] - -Response: - -[source,js] --------------------------------------------------- -{ - "logs_20162801" : { - "aliases" : { - "2016" : { - "filter" : { - "term" : { - "year" : 2016 - } - } - } - } - } -} --------------------------------------------------- -// TESTRESPONSE - -All aliases with the name 2016 in any index: - -[source,js] --------------------------------------------------- -GET /_alias/2016 --------------------------------------------------- -// CONSOLE -// TEST[continued] - -Response: - -[source,js] --------------------------------------------------- -{ - "logs_20162801" : { - "aliases" : { - "2016" : { - "filter" : { - "term" : { - "year" : 2016 - } - } - } - } - } -} --------------------------------------------------- -// TESTRESPONSE - -All aliases that start with 20 in any index: - -[source,js] --------------------------------------------------- -GET /_alias/20* --------------------------------------------------- -// CONSOLE -// TEST[continued] - -Response: - -[source,js] --------------------------------------------------- -{ - "logs_20162801" : { - "aliases" : { - "2016" : { - "filter" : { - "term" : { - "year" : 2016 - } - } - } - } - } -} --------------------------------------------------- -// TESTRESPONSE diff --git a/docs/reference/rest-api/common-parms.asciidoc b/docs/reference/rest-api/common-parms.asciidoc index 82023b70f890a..cc512486e0f09 100644 --- a/docs/reference/rest-api/common-parms.asciidoc +++ b/docs/reference/rest-api/common-parms.asciidoc @@ -50,6 +50,19 @@ tag::help[] to `false`. end::help[] +tag::index-alias-filter[] +`filter`:: ++ +-- +(Required, query object) +<> +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`:: (Optional, string) Short version of the @@ -148,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. From dbd32a533ec229889f7d069ce2376a7fed9c6f8d Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Wed, 28 Aug 2019 13:56:36 -0400 Subject: [PATCH 2/2] change-filter-parm --- docs/reference/indices/add-alias.asciidoc | 2 ++ docs/reference/rest-api/common-parms.asciidoc | 8 ++------ 2 files changed, 4 insertions(+), 6 deletions(-) diff --git a/docs/reference/indices/add-alias.asciidoc b/docs/reference/indices/add-alias.asciidoc index b18adc2b327fc..a5c7d4c49e90b 100644 --- a/docs/reference/indices/add-alias.asciidoc +++ b/docs/reference/indices/add-alias.asciidoc @@ -53,6 +53,8 @@ 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] diff --git a/docs/reference/rest-api/common-parms.asciidoc b/docs/reference/rest-api/common-parms.asciidoc index cc512486e0f09..448a8db773ae9 100644 --- a/docs/reference/rest-api/common-parms.asciidoc +++ b/docs/reference/rest-api/common-parms.asciidoc @@ -50,17 +50,13 @@ tag::help[] to `false`. end::help[] + tag::index-alias-filter[] -`filter`:: -+ --- -(Required, query object) <> 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[]