479 lines
13 KiB
Plaintext
479 lines
13 KiB
Plaintext
[[indices-aliases]]
|
|
=== Update index alias API
|
|
++++
|
|
<titleabbrev>Update index alias</titleabbrev>
|
|
++++
|
|
|
|
Adds or removes index aliases.
|
|
|
|
include::{es-repo-dir}/glossary.asciidoc[tag=index-alias-desc]
|
|
|
|
[source,console]
|
|
----
|
|
POST /_aliases
|
|
{
|
|
"actions" : [
|
|
{ "add" : { "index" : "twitter", "alias" : "alias1" } }
|
|
]
|
|
}
|
|
----
|
|
// 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
|
|
API allows aliasing an index with a name, with all APIs automatically
|
|
converting the alias name to the actual index name. An alias can also be
|
|
mapped to more than one index, and when specifying it, the alias will
|
|
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.
|
|
|
|
|
|
[[indices-aliases-api-query-params]]
|
|
==== {api-query-parms-title}
|
|
|
|
include::{es-repo-dir}/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 <<indices-delete-index,delete index API>>.
|
|
|
|
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`::
|
|
(Array of strings)
|
|
Array 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::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=index-alias-filter]
|
|
+
|
|
See <<filtered>> for an example.
|
|
|
|
`is_hidden`::
|
|
(Optional, boolean)
|
|
If `true`, the alias will be excluded from wildcard expressions by default,
|
|
unless overriden in the request using the `expand_wildcards` parameter,
|
|
similar to <<index-hidden,hidden indices>>. This property must be set to the
|
|
same value on all indices that share an alias. Defaults to `false`.
|
|
|
|
`must_exist`::
|
|
(Optional, boolean)
|
|
If `true`, the alias to remove must exist. Defaults to `false`.
|
|
|
|
`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 <<aliases-write-index>> 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::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=index-routing]
|
|
+
|
|
See <<aliases-routing>> for an example.
|
|
|
|
`index_routing`::
|
|
(Optional, string)
|
|
Custom <<mapping-routing-field, routing value>> used
|
|
for the alias's indexing operations.
|
|
+
|
|
See <<aliases-routing>> for an example.
|
|
|
|
`search_routing`::
|
|
(Optional, string)
|
|
Custom <<mapping-routing-field, routing value>> used
|
|
for the alias's search operations.
|
|
+
|
|
See <<aliases-routing>> 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/]
|
|
|
|
[[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 <<indices-delete-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 /test1
|
|
{
|
|
"mappings": {
|
|
"properties": {
|
|
"user" : {
|
|
"type": "keyword"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
|
|
Now we can create an alias that uses a filter on field `user`:
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
POST /_aliases
|
|
{
|
|
"actions" : [
|
|
{
|
|
"add" : {
|
|
"index" : "test1",
|
|
"alias" : "alias2",
|
|
"filter" : { "term" : { "user" : "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:kimchy&routing=2,3
|
|
--------------------------------------------------
|
|
// TEST[continued]
|
|
|
|
[[aliases-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 <<indices-rollover-index, Rollover With Write Index>>).
|
|
|
|
[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/]
|