From 5fb393f8af863a1d1270fd4ac92d83e574eacc95 Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Wed, 28 Aug 2019 14:36:49 -0400 Subject: [PATCH] [DOCS] Reformat update index aliases API docs --- docs/reference/indices/aliases.asciidoc | 409 +++++++----------- docs/reference/rest-api/common-parms.asciidoc | 15 + 2 files changed, 171 insertions(+), 253 deletions(-) diff --git a/docs/reference/indices/aliases.asciidoc b/docs/reference/indices/aliases.asciidoc index bc207b9f226b0..8d08894a1e341 100644 --- a/docs/reference/indices/aliases.asciidoc +++ b/docs/reference/indices/aliases.asciidoc @@ -1,5 +1,34 @@ [[indices-aliases]] -=== Index Aliases +=== Update index alias API +++++ +Update index alias +++++ + +Adds or removes index aliases. + +include::alias-exists.asciidoc[tag=index-alias-def] + +[source,js] +---- +POST /_aliases +{ + "actions" : [ + { "add" : { "index" : "twitter", "alias" : "alias1" } } + ] +} +---- +// CONSOLE +// TEST[setup:twitter] + + +[[indices-aliases-api-request]] +==== {api-request-title} + +`POST /_aliases` + + +[[indices-aliases-api-desc]] +==== {api-description-title} APIs in Elasticsearch accept an index name when working against a specific index, and several indices when applicable. The index aliases @@ -10,7 +39,119 @@ automatically expand to the aliased indices. An alias can also be associated with a filter that will automatically be applied when searching, and routing values. An alias cannot have the same name as an index. -Here is a sample of associating the alias `alias1` with index `test1`: + +[[indices-aliases-api-query-params]] +==== {api-query-parms-title} + +include::{docdir}/rest-api/common-parms.asciidoc[tag=timeoutparms] + + +[[indices-aliases-api-request-body]] +==== {api-request-body-title} + +`actions`:: ++ +-- +(Required, array of actions) +Set of actions to perform. +Valid actions include: + +`add`:: +Adds an alias to an index. + +`remove`:: +Removes an alias from an index. + +`remove_index`:: +Deletes an index or index alias, +like the <>. + +You can perform these actions on alias objects. +Valid parameters for alias objects include: + +`index`:: +(String) +Wildcard expression of index names +used to perform the action. ++ +If the `indices` parameter is not specified, +this parameter is required. + +`indices`:: +(Array) +Array of index names +used to perform the action. ++ +If the `index` parameter is not specified, +this parameter is required. + +`alias`:: +(String) +Comma-separated list or wildcard expression of index alias names to +add, remove, or delete. ++ +If the `aliases` parameter is not specified, +this parameter is required for the `add` or `remove` action. + +`aliases`:: +(String) +Comma-separated list or wildcard expression of index alias names to +add, remove, or delete. ++ +If the `alias` parameter is not specified, +this parameter is required for the `add` or `remove` action. + +`filter`:: +(Optional, query object) +include::{docdir}/rest-api/common-parms.asciidoc[tag=index-alias-filter] ++ +See <> for an example. + +`is_write_index`:: +(Optional, boolean) +If `true`, assigns the index as an alias's write index. +Defaults to `false`. ++ +An alias can have one write index at a time. ++ +See <> for an example. ++ +[IMPORTANT] +==== +Aliases that do not explicitly set `is_write_index: true` for an index, and +only reference one index, will have that referenced index behave as if it is the write index +until an additional index is referenced. At that point, there will be no write index and +writes will be rejected. +==== + +include::{docdir}/rest-api/common-parms.asciidoc[tag=index-alias-routing] ++ +See <> for an example. + +`index_routing`:: +(Optional, string) +Custom <> used +for the alias's indexing operations. ++ +See <> for an example. + +`search_routing`:: +`index_routing`:: +(Optional, string) +Custom <> used +for the alias's search operations. ++ +See <> for an example. +-- + + +[[indices-aliases-api-example]] +==== {api-examples-title} + +[[indices-aliases-api-add-alias-ex]] +===== Add an alias + +The following request adds the `alias1` alias to the `test1` index. [source,js] -------------------------------------------------- @@ -24,7 +165,10 @@ POST /_aliases // CONSOLE // TEST[s/^/PUT test1\nPUT test2\n/] -And here is removing that same alias: +[[indices-aliases-api-remove-alias-ex]] +===== Remove an alias + +The following request removes the `alias1` alias. [source,js] -------------------------------------------------- @@ -38,6 +182,9 @@ POST /_aliases // CONSOLE // TEST[continued] +[[indices-aliases-api-rename-alias-ex]] +===== Rename an alias + Renaming an alias is a simple `remove` then `add` operation within the same API. This operation is atomic, no need to worry about a short period of time where the alias does not point to an index: @@ -48,13 +195,16 @@ POST /_aliases { "actions" : [ { "remove" : { "index" : "test1", "alias" : "alias1" } }, - { "add" : { "index" : "test2", "alias" : "alias1" } } + { "add" : { "index" : "test1", "alias" : "alias2" } } ] } -------------------------------------------------- // CONSOLE // TEST[continued] +[[indices-aliases-api-add-multi-alias-ex]] +===== Add an alias to multiple indices + Associating an alias with more than one index is simply several `add` actions: @@ -128,9 +278,8 @@ POST /_aliases <2> The index we should have added <3> `remove_index` is just like <> -[float] [[filtered]] -==== Filtered Aliases +===== Filtered aliases Aliases with filters provide an easy way to create different "views" of the same index. The filter can be defined using Query DSL and is applied @@ -175,7 +324,6 @@ POST /_aliases // CONSOLE // TEST[continued] -[float] [[aliases-routing]] ===== Routing @@ -242,9 +390,8 @@ GET /alias2/_search?q=user:kimchy&routing=2,3 // CONSOLE // TEST[continued] -[float] [[aliases-write-index]] -===== Write Index +===== Write index It is possible to associate the index pointed to by an alias as the write index. When specified, all index and update requests against an alias that point to multiple @@ -331,247 +478,3 @@ POST /_aliases -------------------------------------------------- // CONSOLE // TEST[s/^/PUT test\nPUT test2\n/] - -[IMPORTANT] -===================================== -Aliases that do not explicitly set `is_write_index: true` for an index, and -only reference one index, will have that referenced index behave as if it is the write index -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..ae7ce2d92fb90 100644 --- a/docs/reference/rest-api/common-parms.asciidoc +++ b/docs/reference/rest-api/common-parms.asciidoc @@ -50,6 +50,14 @@ tag::help[] 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`:: (Optional, string) Short version of the @@ -148,6 +156,13 @@ tag::doc-routing[] (Optional, string) Target the specified primary shard. end::doc-routing[] +tag::index-alias-routing[] +`routing`:: +(Optional, string) +Custom <> +used to route operations to a specific shard. +end::index-alias-routing[] + tag::doc-version[] `version`:: (Optional, integer) Explicit version number for concurrency control.