diff --git a/docs/reference/alias.asciidoc b/docs/reference/alias.asciidoc new file mode 100644 index 0000000000000..4dee84b719ddb --- /dev/null +++ b/docs/reference/alias.asciidoc @@ -0,0 +1,326 @@ +[chapter] +[[alias]] += Aliases + +An alias is a secondary name for a group of data streams or indices. Most {es} +APIs accept an alias in place of a data stream or index name. + +You can change the data streams or indices of an alias at any time. If you use +aliases in your application's {es} requests, you can reindex data with no +downtime or changes to your app's code. + +[discrete] +[[alias-types]] +=== Alias types + +There are two types of aliases: + +* A **data stream alias** points to one or more data streams. +* An **index alias** points to one or more indices. + +An alias cannot point to both data streams and indices. You also cannot add a +data stream's backing index to an index alias. + +[discrete] +[[add-alias]] +=== Add an alias + +To add an existing data stream or index to an alias, use the +<>'s `add` action. If the alias doesn't exist, the +request creates it. + +[source,console] +---- +POST _aliases +{ + "actions": [ + { + "add": { + "index": "logs-nginx.access-prod", + "alias": "logs" + } + } + ] +} +---- +// TEST[s/^/PUT _data_stream\/logs-nginx.access-prod\n/] + +The API's `index` and `indices` parameters support wildcards (`*`). If a +wildcard pattern matches both data streams and indices, the action only uses +matching data streams. + +[source,console] +---- +POST _aliases +{ + "actions": [ + { + "add": { + "index": "logs-*", + "alias": "logs" + } + } + ] +} +---- +// TEST[s/^/PUT _data_stream\/logs-nginx.access-prod\n/] + +[discrete] +[[remove-alias]] +=== Remove an alias + +To remove an alias, use the aliases API's `remove` action. + +[source,console] +---- +POST _aliases +{ + "actions": [ + { + "remove": { + "index": "logs-nginx.access-prod", + "alias": "logs" + } + } + ] +} +---- +// TEST[continued] + +[discrete] +[[multiple-actions]] +=== Multiple actions + +You can use the aliases API to perform multiple actions in a single atomic +operation. + +For example, the `logs` alias points to a single data stream. The following +request swaps the stream for the alias. During this swap, the `logs` alias has +no downtime and never points to both streams at the same time. + +[source,console] +---- +POST _aliases +{ + "actions": [ + { + "remove": { + "index": "logs-nginx.access-prod", + "alias": "logs" + } + }, + { + "add": { + "index": "logs-my_app-default", + "alias": "logs" + } + } + ] +} +---- +// TEST[s/^/PUT _data_stream\/logs-nginx.access-prod\nPUT _data_stream\/logs-my_app-default\n/] + +[discrete] +[[add-alias-at-creation]] +=== Add an alias at index creation + +You can also use a <> or +<> to add index aliases at index creation. +You cannot use a component or index template to add a data stream alias. + +[source,console] +---- +# Component template with index aliases +PUT _component_template/my-aliases +{ + "template": { + "aliases": { + "my-alias": {} + } + } +} + +# Index template with index aliases +PUT _index_template/my-index-template +{ + "index_patterns": [ + "my-index-*" + ], + "composed_of": [ + "my-aliases", + "my-mappings", + "my-settings" + ], + "template": { + "aliases": { + "yet-another-alias": {} + } + } +} +---- +// TEST[s/,\n "my-mappings",\n "my-settings"//] +// TEST[teardown:data_stream_cleanup] + +You can also specify index aliases in <> +requests. + +[source,console] +---- +# PUT +PUT %3Cmy-index-%7Bnow%2Fd%7D-000001%3E +{ + "aliases": { + "my-alias": {} + } +} +---- + +[discrete] +[[view-aliases]] +=== View aliases + +To get a list of your cluster's aliases, use the <> with no argument. + +[source,console] +---- +GET _alias +---- +// TEST[s/^/PUT _data_stream\/logs-nginx.access-prod\nPUT logs-nginx.access-prod\/_alias\/logs\n/] + +Specify a data stream or index before `_alias` to view its aliases. + +[source,console] +---- +GET my-data-stream/_alias +---- +// TEST[s/^/PUT _data_stream\/logs-nginx.access-prod\nPUT logs-nginx.access-prod\/_alias\/logs\n/] +// TEST[s/my-data-stream/logs-nginx.access-prod/] + +Specify an alias after `_alias` to view its data streams or indices. + +[source,console] +---- +GET _alias/logs +---- +// TEST[s/^/PUT _data_stream\/logs-nginx.access-prod\nPUT logs-nginx.access-prod\/_alias\/logs\n/] + +[discrete] +[[write-index]] +=== Write index + +If an alias points to multiple indices, you can use `is_write_index` to specify +a write index. {es} routes any write requests for the alias to this index. + +[source,console] +---- +POST _aliases +{ + "actions": [ + { + "add": { + "index": "my-index-2099.05.06-000001", + "alias": "my-alias" + } + }, + { + "add": { + "index": "my-index-2099.05.07-000002", + "alias": "my-alias", + "is_write_index": true + } + } + ] +} +---- +// TEST[s/^/PUT my-index-2099.05.06-000001\nPUT my-index-2099.05.07-000002\n/] + +TIP: We recommend using data streams to store append-only time series data. If +you frequently update or delete existing time series data, use an index alias +with a write index instead. See +<>. + +If an alias points to multiple indices with no write index, the alias rejects +write requests. If an alias points to one index and `is_write_index` is not set, +the index automatically acts as the write index. Data stream aliases do not +support `is_write_index`. + +[discrete] +[[filter-alias]] +=== Filter an alias + +The `filter` option uses <> to limit the documents an alias +can access. Data stream aliases do not support `filter`. + +[source,console] +---- +POST _aliases +{ + "actions": [ + { + "add": { + "index": "my-index-2099.05.07-000002", + "alias": "my-alias", + "is_write_index": true, + "filter": { + "range": { + "@timestamp": { + "gte": "now-1d/d", + "lt": "now/d" + } + } + } + } + } + ] +} +---- +// TEST[s/^/PUT my-index-2099.05.07-000002\n/] + +[discrete] +[[alias-routing]] +=== Routing + +Use the `routing` option to <> requests for an +alias to a specific shard. This lets you take advantage of +<> to speed up searches. Data stream aliases +do not support routing options. + +[source,console] +---- +POST _aliases +{ + "actions": [ + { + "add": { + "index": "my-index-2099.05.06-000001", + "alias": "my-alias", + "routing": "1" + } + } + ] +} +---- +// TEST[s/^/PUT my-index-2099.05.06-000001\n/] + +Use the `index_routing` and `search_routing` to use different routing values for +indexing and search. If specified, these options overwrite the `routing` value +for their respective operations. + +[source,console] +---- +POST _aliases +{ + "actions": [ + { + "add": { + "index": "my-index-2099.05.06-000001", + "alias": "my-alias", + "search_routing": "1", + "index_routing": "2" + } + } + ] +} +---- +// TEST[s/^/PUT my-index-2099.05.06-000001\n/] diff --git a/docs/reference/cat/alias.asciidoc b/docs/reference/cat/alias.asciidoc index dffb039abcc00..ab6f7a0be75f8 100644 --- a/docs/reference/cat/alias.asciidoc +++ b/docs/reference/cat/alias.asciidoc @@ -4,8 +4,8 @@ cat aliases ++++ -Returns information about currently configured aliases to indices, including -filter and routing information. +Retrieves the cluster's <>, including filter and routing +information. The API does not return data stream aliases. [[cat-alias-api-request]] diff --git a/docs/reference/glossary.asciidoc b/docs/reference/glossary.asciidoc index e431afe2ee36b..0fe939cd32c87 100644 --- a/docs/reference/glossary.asciidoc +++ b/docs/reference/glossary.asciidoc @@ -15,7 +15,7 @@ https://github.com/elastic/stack-docs/tree/master/docs/en/glossary // tag::alias-def[] An alias is a secondary name for a group of <> or <>. Most {es} APIs accept an alias in place -of a data stream or index name. +of a data stream or index name. See {ref}/alias.html[Aliases]. // end::alias-def[] [[glossary-analysis]] analysis:: diff --git a/docs/reference/index.asciidoc b/docs/reference/index.asciidoc index ce2055b81be4b..68cd35fdf5ff0 100644 --- a/docs/reference/index.asciidoc +++ b/docs/reference/index.asciidoc @@ -33,6 +33,8 @@ include::data-streams/data-streams.asciidoc[] include::ingest.asciidoc[] +include::alias.asciidoc[] + include::search/search-your-data/search-your-data.asciidoc[] include::query-dsl.asciidoc[] diff --git a/docs/reference/indices.asciidoc b/docs/reference/indices.asciidoc index bdb9aa17733ae..dfc4cfa99f99d 100644 --- a/docs/reference/indices.asciidoc +++ b/docs/reference/indices.asciidoc @@ -89,37 +89,36 @@ For more information, see <>. * <> * <> - +include::indices/alias-exists.asciidoc[] include::indices/aliases.asciidoc[] include::indices/analyze.asciidoc[] include::indices/clearcache.asciidoc[] include::indices/clone-index.asciidoc[] include::indices/close.asciidoc[] include::indices/create-index.asciidoc[] -include::indices/put-component-template.asciidoc[] include::indices/add-alias.asciidoc[] +include::indices/put-component-template.asciidoc[] include::indices/put-index-template.asciidoc[] include::indices/put-index-template-v1.asciidoc[] include::indices/delete-component-template.asciidoc[] include::indices/dangling-index-delete.asciidoc[] -include::indices/delete-index.asciidoc[] include::indices/delete-alias.asciidoc[] +include::indices/delete-index.asciidoc[] include::indices/delete-index-template.asciidoc[] include::indices/delete-index-template-v1.asciidoc[] include::indices/indices-exists.asciidoc[] include::indices/flush.asciidoc[] include::indices/forcemerge.asciidoc[] include::indices/apis/freeze.asciidoc[] +include::indices/get-alias.asciidoc[] include::indices/get-component-template.asciidoc[] include::indices/get-field-mapping.asciidoc[] include::indices/get-index.asciidoc[] -include::indices/get-alias.asciidoc[] include::indices/get-settings.asciidoc[] include::indices/get-index-template.asciidoc[] include::indices/get-index-template-v1.asciidoc[] include::indices/get-mapping.asciidoc[] include::indices/dangling-index-import.asciidoc[] -include::indices/alias-exists.asciidoc[] include::indices/recovery.asciidoc[] include::indices/segments.asciidoc[] include::indices/shard-stores.asciidoc[] diff --git a/docs/reference/indices/add-alias.asciidoc b/docs/reference/indices/add-alias.asciidoc index 8826b998183db..3ae66daf160ed 100644 --- a/docs/reference/indices/add-alias.asciidoc +++ b/docs/reference/indices/add-alias.asciidoc @@ -1,15 +1,10 @@ [[indices-add-alias]] -=== Create or update index alias API +=== Create or update alias API ++++ -Create or update index alias +Create or update alias ++++ -Creates or updates an index alias. - -//tag::index-alias-desc[] -An index alias is a secondary name for one or more indices. Most {es} APIs -accept an index alias in place of an index name. -//end::index-alias-desc[] +Adds a data stream or index to an <>. [source,console] ---- diff --git a/docs/reference/indices/alias-exists.asciidoc b/docs/reference/indices/alias-exists.asciidoc index 8e81915262a12..ab6cd3038ae2c 100644 --- a/docs/reference/indices/alias-exists.asciidoc +++ b/docs/reference/indices/alias-exists.asciidoc @@ -1,12 +1,10 @@ [[indices-alias-exists]] -=== Index alias exists API +=== Alias exists API ++++ -Index alias exists +Alias exists ++++ -Checks if an index alias exists. - -include::{es-repo-dir}/indices/add-alias.asciidoc[tag=index-alias-desc] +Checks if an <> exists. [source,console] ---- diff --git a/docs/reference/indices/aliases.asciidoc b/docs/reference/indices/aliases.asciidoc index 31b56c5e8cba1..34825c6a6f399 100644 --- a/docs/reference/indices/aliases.asciidoc +++ b/docs/reference/indices/aliases.asciidoc @@ -4,11 +4,7 @@ Aliases ++++ -Adds and removes multiple index aliases in a single request. Also deletes -concrete indices. - -An index alias is a secondary name used to refer to one or more existing -indices. Most {es} APIs accept an index alias in place of an index. +Performs one or more <> actions in a single atomic operation. [source,console] ---- @@ -121,7 +117,7 @@ If the `alias` parameter is not specified, this parameter is required for the (Optional, query object) include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=index-alias-filter] + -See <> for an example. +See <> for an example. `is_hidden`:: (Optional, Boolean) @@ -153,456 +149,19 @@ writes will be rejected. include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=routing] + -See <> for an example. +See <> for an example. `index_routing`:: (Optional, string) Custom <> used for the alias's indexing operations. + -See <> for an example. +See <> for an example. `search_routing`:: (Optional, string) Custom <> used for the alias's search operations. + -See <> for an example. +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,console] --------------------------------------------------- -POST /_aliases -{ - "actions" : [ - { "add" : { "index" : "test1", "alias" : "alias1" } } - ] -} --------------------------------------------------- -// TEST[s/^/PUT test1\nPUT test2\n/] - -Index alias names support <>. - -[source,console] ----- -POST /_aliases -{ - "actions" : [ - { "add" : { "index" : "logs", "alias" : "" } } - ] -} ----- -// TEST[s/^/PUT logs\n/] -// TEST[continued] - -[[indices-aliases-api-remove-alias-ex]] -===== Remove an alias - -The following request removes the `alias1` alias. - -[source,console] --------------------------------------------------- -POST /_aliases -{ - "actions" : [ - { "remove" : { "index" : "test1", "alias" : "alias1" } } - ] -} --------------------------------------------------- -// 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: - -[source,console] --------------------------------------------------- -POST /_aliases -{ - "actions" : [ - { "remove" : { "index" : "test1", "alias" : "alias1" } }, - { "add" : { "index" : "test1", "alias" : "alias2" } } - ] -} --------------------------------------------------- -// 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: - -[source,console] --------------------------------------------------- -POST /_aliases -{ - "actions" : [ - { "add" : { "index" : "test1", "alias" : "alias1" } }, - { "add" : { "index" : "test2", "alias" : "alias1" } } - ] -} --------------------------------------------------- -// TEST[s/^/PUT test1\nPUT test2\n/] - -Multiple indices can be specified for an action with the `indices` array syntax: - -[source,console] --------------------------------------------------- -POST /_aliases -{ - "actions" : [ - { "add" : { "indices" : ["test1", "test2"], "alias" : "alias1" } } - ] -} --------------------------------------------------- -// TEST[s/^/PUT test1\nPUT test2\n/] - -To specify multiple aliases in one action, the corresponding `aliases` array -syntax exists as well. - -For the example above, a glob pattern can also be used to associate an alias to -more than one index that share a common name: - -[source,console] --------------------------------------------------- -POST /_aliases -{ - "actions" : [ - { "add" : { "index" : "test*", "alias" : "all_test_indices" } } - ] -} --------------------------------------------------- -// TEST[s/^/PUT test1\nPUT test2\n/] - -In this case, the alias is a point-in-time alias that will group all -current indices that match, it will not automatically update as new -indices that match this pattern are added/removed. - -It is an error to index to an alias which points to more than one index. - -It is also possible to swap an index with an alias in one, atomic operation. -This means there will be no point in time where the alias points to no -index in the cluster state. However, as indexing and searches involve multiple -steps, it is possible for the in-flight or queued requests to fail -due to a temporarily non-existent index. - -[source,console] --------------------------------------------------- -PUT test <1> -PUT test_2 <2> -POST /_aliases -{ - "actions" : [ - { "add": { "index": "test_2", "alias": "test" } }, - { "remove_index": { "index": "test" } } <3> - ] -} --------------------------------------------------- - -<1> An index we've added by mistake -<2> The index we should have added -<3> `remove_index` is just like <> and will only remove a concrete index. - -[[filtered]] -===== 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 -to all Search, Count, Delete By Query and More Like This operations with -this alias. - -To create a filtered alias, first we need to ensure that the fields already -exist in the mapping: - -[source,console] --------------------------------------------------- -PUT /my-index-000001 -{ - "mappings": { - "properties": { - "user": { - "properties": { - "id": { - "type": "keyword" - } - } - } - } - } -} --------------------------------------------------- - -Now we can create an alias that uses a filter on field `user.id`: - -[source,console] --------------------------------------------------- -POST /_aliases -{ - "actions": [ - { - "add": { - "index": "my-index-000001", - "alias": "alias2", - "filter": { "term": { "user.id": "kimchy" } } - } - } - ] -} --------------------------------------------------- -// TEST[continued] - -[[aliases-routing]] -===== Routing - -It is possible to associate routing values with aliases. This feature -can be used together with filtering aliases in order to avoid -unnecessary shard operations. - -The following command creates a new alias `alias1` that points to index -`test`. After `alias1` is created, all operations with this alias are -automatically modified to use value `1` for routing: - -[source,console] --------------------------------------------------- -POST /_aliases -{ - "actions": [ - { - "add": { - "index": "test", - "alias": "alias1", - "routing": "1" - } - } - ] -} --------------------------------------------------- -// TEST[s/^/PUT test\n/] - -It's also possible to specify different routing values for searching -and indexing operations: - -[source,console] --------------------------------------------------- -POST /_aliases -{ - "actions": [ - { - "add": { - "index": "test", - "alias": "alias2", - "search_routing": "1,2", - "index_routing": "2" - } - } - ] -} --------------------------------------------------- -// TEST[s/^/PUT test\n/] - -As shown in the example above, search routing may contain several values -separated by comma. Index routing can contain only a single value. - -If a search operation that uses routing alias also has a routing parameter, an -intersection of both search alias routing and routing specified in the -parameter is used. For example the following command will use "2" as a -routing value: - -[source,console] --------------------------------------------------- -GET /alias2/_search?q=user.id:kimchy&routing=2,3 --------------------------------------------------- -// TEST[continued] - -[[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 -indices will attempt to resolve to the one index that is the write index. -Only one index per alias can be assigned to be the write index at a time. If no write index is specified -and there are multiple indices referenced by an alias, then writes will not be allowed. - -It is possible to specify an index associated with an alias as a write index using both the aliases API -and index creation API. - -Setting an index to be the write index with an alias also affects how the alias is manipulated during -Rollover (see <>). - -[source,console] --------------------------------------------------- -POST /_aliases -{ - "actions": [ - { - "add": { - "index": "test", - "alias": "alias1", - "is_write_index": true - } - }, - { - "add": { - "index": "test2", - "alias": "alias1" - } - } - ] -} --------------------------------------------------- -// TEST[s/^/PUT test\nPUT test2\n/] - -In this example, we associate the alias `alias1` to both `test` and `test2`, where -`test` will be the index chosen for writing to. - -[source,console] --------------------------------------------------- -PUT /alias1/_doc/1 -{ - "foo": "bar" -} --------------------------------------------------- -// TEST[continued] - -The new document that was indexed to `/alias1/_doc/1` will be indexed as if it were -`/test/_doc/1`. - -[source,console] --------------------------------------------------- -GET /test/_doc/1 --------------------------------------------------- -// TEST[continued] - -To swap which index is the write index for an alias, the Aliases API can be leveraged to -do an atomic swap. The swap is not dependent on the ordering of the actions. - -[source,console] --------------------------------------------------- -POST /_aliases -{ - "actions": [ - { - "add": { - "index": "test", - "alias": "alias1", - "is_write_index": false - } - }, { - "add": { - "index": "test2", - "alias": "alias1", - "is_write_index": true - } - } - ] -} --------------------------------------------------- -// TEST[s/^/PUT test\nPUT test2\n/] - -[[aliases-data-streams]] -===== Data stream aliases - -An alias can also point to one or more data streams. To add a data stream to an -alias, specify the stream's name in the `index` parameter. Wildcards (`*`) are -supported. If a wildcard pattern matches both data streams and indices, the -action only uses the matching data streams. - -You can only specify data streams in the `add` and `remove` actions. Aliases -that point to data streams do not support the following parameters: - -* `filter` -* `index_routing` -* `is_write_index` -* `routing` -* `search_routing` - -For example, the following request adds two data streams to the `logs` alias. - -//// -[source,console] ----- -PUT _data_stream/logs-my_app-default - -PUT _data_stream/logs-nginx.access-prod ----- -//// - -[source,console] ----- -POST _aliases -{ - "actions": [ - { "add": { "index": "logs-my_app-default", "alias": "logs" }}, - { "add": { "index": "logs-nginx.access-prod", "alias": "logs" }} - ] -} ----- -// TEST[continued] - -To verify the alias points to both data streams, use the -<>. - -[source,console] ----- -GET logs-*/_alias ----- -// TEST[continued] - -The API returns: - -[source,console-result] ----- -{ - "logs-my_app-default": { - "aliases": { - "logs": {} - } - }, - "logs-nginx.access-prod": { - "aliases": { - "logs": {} - } - } -} ----- - -Use the `remove` action to remove a data stream from an alias. - -[source,console] ----- -POST _aliases -{ - "actions": [ - { "remove": { "index": "logs-my_app-default", "alias": "logs" }} - ] -} - -GET logs-*/_alias ----- -// TEST[continued] - -The get index alias API returns: - -[source,console-result] ----- -{ - "logs-nginx.access-prod": { - "aliases": { - "logs": {} - } - } -} ----- diff --git a/docs/reference/indices/delete-alias.asciidoc b/docs/reference/indices/delete-alias.asciidoc index 29fb8a442531d..6b9a5bd3d8d3c 100644 --- a/docs/reference/indices/delete-alias.asciidoc +++ b/docs/reference/indices/delete-alias.asciidoc @@ -1,12 +1,10 @@ [[indices-delete-alias]] -=== Delete index alias API +=== Delete alias API ++++ -Delete index alias +Delete alias ++++ -Deletes an existing index alias. - -include::{es-repo-dir}/indices/add-alias.asciidoc[tag=index-alias-desc] +Deletes an <>. [source,console] ---- diff --git a/docs/reference/indices/get-alias.asciidoc b/docs/reference/indices/get-alias.asciidoc index ac841fd282251..74285ba792027 100644 --- a/docs/reference/indices/get-alias.asciidoc +++ b/docs/reference/indices/get-alias.asciidoc @@ -1,12 +1,10 @@ [[indices-get-alias]] -=== Get index alias API +=== Get alias API ++++ -Get index alias +Get alias ++++ -Returns information about one or more index aliases. - -include::{es-repo-dir}/indices/add-alias.asciidoc[tag=index-alias-desc] +Retrieves information for one or more <>. [source,console] ---- diff --git a/docs/reference/indices/migrate-to-data-stream.asciidoc b/docs/reference/indices/migrate-to-data-stream.asciidoc index dcf707df7935a..e9f270acc113d 100644 --- a/docs/reference/indices/migrate-to-data-stream.asciidoc +++ b/docs/reference/indices/migrate-to-data-stream.asciidoc @@ -90,8 +90,8 @@ following criteria: - The alias must have a <>. - All indices for the alias have a `@timestamp` field mapping of a `date` or `date_nanos` field type. -- The alias must not have any <>. -- The alias must not use <>. +- The alias must not have any <>. +- The alias must not use <>. If successful, the request removes the alias and creates a data stream with the same name. The alias's indices become hidden backing indices for the stream. The