502 lines
12 KiB
Plaintext
502 lines
12 KiB
Plaintext
[[indices-aliases]]
|
|
== Index Aliases
|
|
|
|
APIs in Elasticsearch accept an index name when working against a
|
|
specific index, and several indices when applicable. The index aliases
|
|
API allow to alias 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 aliases 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`:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
POST /_aliases
|
|
{
|
|
"actions" : [
|
|
{ "add" : { "index" : "test1", "alias" : "alias1" } }
|
|
]
|
|
}
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
// TEST[s/^/PUT test1\nPUT test2\n/]
|
|
|
|
And here is removing that same alias:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
POST /_aliases
|
|
{
|
|
"actions" : [
|
|
{ "remove" : { "index" : "test1", "alias" : "alias1" } }
|
|
]
|
|
}
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
// TEST[continued]
|
|
|
|
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,js]
|
|
--------------------------------------------------
|
|
POST /_aliases
|
|
{
|
|
"actions" : [
|
|
{ "remove" : { "index" : "test1", "alias" : "alias1" } },
|
|
{ "add" : { "index" : "test2", "alias" : "alias1" } }
|
|
]
|
|
}
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
// TEST[continued]
|
|
|
|
Associating an alias with more than one index are simply several `add`
|
|
actions:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
POST /_aliases
|
|
{
|
|
"actions" : [
|
|
{ "add" : { "index" : "test1", "alias" : "alias1" } },
|
|
{ "add" : { "index" : "test2", "alias" : "alias1" } }
|
|
]
|
|
}
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
// TEST[s/^/PUT test1\nPUT test2\n/]
|
|
|
|
Multiple indices can be specified for an action with the `indices` array syntax:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
POST /_aliases
|
|
{
|
|
"actions" : [
|
|
{ "add" : { "indices" : ["test1", "test2"], "alias" : "alias1" } }
|
|
]
|
|
}
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
// 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,js]
|
|
--------------------------------------------------
|
|
POST /_aliases
|
|
{
|
|
"actions" : [
|
|
{ "add" : { "index" : "test*", "alias" : "all_test_indices" } }
|
|
]
|
|
}
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
// 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 operation:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
PUT test <1>
|
|
PUT test_2 <2>
|
|
POST /_aliases
|
|
{
|
|
"actions" : [
|
|
{ "add": { "index": "test_2", "alias": "test" } },
|
|
{ "remove_index": { "index": "test" } } <3>
|
|
]
|
|
}
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
<1> An index we've added by mistake
|
|
<2> The index we should have added
|
|
<3> `remove_index` is just like <<indices-delete-index>>
|
|
|
|
[float]
|
|
[[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,js]
|
|
--------------------------------------------------
|
|
PUT /test1
|
|
{
|
|
"mappings": {
|
|
"type1": {
|
|
"properties": {
|
|
"user" : {
|
|
"type": "keyword"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
|
|
Now we can create an alias that uses a filter on field `user`:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
POST /_aliases
|
|
{
|
|
"actions" : [
|
|
{
|
|
"add" : {
|
|
"index" : "test1",
|
|
"alias" : "alias2",
|
|
"filter" : { "term" : { "user" : "kimchy" } }
|
|
}
|
|
}
|
|
]
|
|
}
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
// TEST[continued]
|
|
|
|
[float]
|
|
[[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,js]
|
|
--------------------------------------------------
|
|
POST /_aliases
|
|
{
|
|
"actions" : [
|
|
{
|
|
"add" : {
|
|
"index" : "test",
|
|
"alias" : "alias1",
|
|
"routing" : "1"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
// TEST[s/^/PUT test\n/]
|
|
|
|
It's also possible to specify different routing values for searching
|
|
and indexing operations:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
POST /_aliases
|
|
{
|
|
"actions" : [
|
|
{
|
|
"add" : {
|
|
"index" : "test",
|
|
"alias" : "alias2",
|
|
"search_routing" : "1,2",
|
|
"index_routing" : "2"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
// 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,js]
|
|
--------------------------------------------------
|
|
GET /alias2/_search?q=user:kimchy&routing=2,3
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
// TEST[continued]
|
|
|
|
If an index operation that uses index routing alias also has a parent routing, the
|
|
parent routing is ignored.
|
|
|
|
[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" : {
|
|
"user" : {
|
|
"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 <<create-index-aliases,index creation>>:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
PUT /logs_20162801
|
|
{
|
|
"mappings" : {
|
|
"type" : {
|
|
"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 users:
|
|
|
|
[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
|
|
|
|
There is also a HEAD variant of the get indices aliases api to check if
|
|
index aliases exist. The indices aliases exists api supports the same
|
|
option as the get indices aliases api. Examples:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
HEAD /_alias/2016
|
|
HEAD /_alias/20*
|
|
HEAD /logs_20162801/_alias/*
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
// TEST[continued]
|