mirror of
https://github.com/honeymoose/OpenSearch.git
synced 2025-02-06 04:58:50 +00:00
f5b2dfd052
Fixes a bug where alias creation would allow `null` for index name, which thereby
applied the alias to _all_ indices. This patch makes the validator throw an
exception if the index is null.
```bash
POST /_aliases
{
"actions": [
{
"add": {
"alias": "empty-alias",
"index": null
}
}
]
}
```
```json
{
"error": "ActionRequestValidationException[Validation Failed: 1: Alias action [add]: [index] may not be null;]",
"status": 400
}
```
The reason this bug wasn't caught by the existing tests is because
the old test for nullness only validated against a cluster which had
zero indices. The null index is translated into "_all", and since
there are no indices, this fails because the index doesn't exist.
So the test passes.
However, as soon as you add an index, "_all" resolves and you get the
situation described in the original bug report: null index is
accepted by the alias, resolves to "_all" and gets applied to everything.
The REST tests, otoh, explicitly tested this bug as a real feature and therefore
passed. The REST tests were modified to change this behavior.
Fixes #7863
417 lines
10 KiB
Plaintext
417 lines
10 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.
|
|
|
|
Here is a sample of associating the alias `alias1` with index `test1`:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
curl -XPOST 'http://localhost:9200/_aliases' -d '
|
|
{
|
|
"actions" : [
|
|
{ "add" : { "index" : "test1", "alias" : "alias1" } }
|
|
]
|
|
}'
|
|
--------------------------------------------------
|
|
|
|
An alias can also be removed, for example:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
curl -XPOST 'http://localhost:9200/_aliases' -d '
|
|
{
|
|
"actions" : [
|
|
{ "remove" : { "index" : "test1", "alias" : "alias1" } }
|
|
]
|
|
}'
|
|
--------------------------------------------------
|
|
|
|
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]
|
|
--------------------------------------------------
|
|
curl -XPOST 'http://localhost:9200/_aliases' -d '
|
|
{
|
|
"actions" : [
|
|
{ "remove" : { "index" : "test1", "alias" : "alias1" } },
|
|
{ "add" : { "index" : "test1", "alias" : "alias2" } }
|
|
]
|
|
}'
|
|
--------------------------------------------------
|
|
|
|
Associating an alias with more than one index are simply several `add`
|
|
actions:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
curl -XPOST 'http://localhost:9200/_aliases' -d '
|
|
{
|
|
"actions" : [
|
|
{ "add" : { "index" : "test1", "alias" : "alias1" } },
|
|
{ "add" : { "index" : "test2", "alias" : "alias1" } }
|
|
]
|
|
}'
|
|
--------------------------------------------------
|
|
|
|
It is an error to index to an alias which points to more than one 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]
|
|
--------------------------------------------------
|
|
curl -XPUT 'http://localhost:9200/test1' -d '{
|
|
"mappings": {
|
|
"type1": {
|
|
"properties": {
|
|
"user" : {
|
|
"type": "string",
|
|
"index": "not_analyzed"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
|
|
Now we can create an alias that uses a filter on field `user`:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
curl -XPOST 'http://localhost:9200/_aliases' -d '{
|
|
"actions" : [
|
|
{
|
|
"add" : {
|
|
"index" : "test1",
|
|
"alias" : "alias2",
|
|
"filter" : { "term" : { "user" : "kimchy" } }
|
|
}
|
|
}
|
|
]
|
|
}'
|
|
--------------------------------------------------
|
|
|
|
[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]
|
|
--------------------------------------------------
|
|
curl -XPOST 'http://localhost:9200/_aliases' -d '
|
|
{
|
|
"actions" : [
|
|
{
|
|
"add" : {
|
|
"index" : "test",
|
|
"alias" : "alias1",
|
|
"routing" : "1"
|
|
}
|
|
}
|
|
]
|
|
}'
|
|
--------------------------------------------------
|
|
|
|
It's also possible to specify different routing values for searching
|
|
and indexing operations:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
curl -XPOST 'http://localhost:9200/_aliases' -d '
|
|
{
|
|
"actions" : [
|
|
{
|
|
"add" : {
|
|
"index" : "test",
|
|
"alias" : "alias2",
|
|
"search_routing" : "1,2",
|
|
"index_routing" : "2"
|
|
}
|
|
}
|
|
]
|
|
}'
|
|
--------------------------------------------------
|
|
|
|
As shown in the example above, search routing may contain several values
|
|
separated by comma. Index routing can contain only a single value.
|
|
|
|
If an operation that uses routing alias also has a routing parameter, an
|
|
intersection of both alias routing and routing specified in the
|
|
parameter is used. For example the following command will use "2" as a
|
|
routing value:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
curl -XGET 'http://localhost:9200/alias2/_search?q=user:kimchy&routing=2,3'
|
|
--------------------------------------------------
|
|
|
|
[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]
|
|
--------------------------------------------------
|
|
curl -XPUT 'localhost:9200/logs_201305/_alias/2013'
|
|
--------------------------------------------------
|
|
--
|
|
|
|
Adding a user alias::
|
|
+
|
|
--
|
|
First create the index and add a mapping for the `user_id` field:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
curl -XPUT 'localhost:9200/users' -d '{
|
|
"mappings" : {
|
|
"user" : {
|
|
"properties" : {
|
|
"user_id" : {"type" : "integer"}
|
|
}
|
|
}
|
|
}
|
|
}'
|
|
--------------------------------------------------
|
|
|
|
Then add the alias for a specific user:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
curl -XPUT 'localhost:9200/users/_alias/user_12' -d '{
|
|
"routing" : "12",
|
|
"filter" : {
|
|
"term" : {
|
|
"user_id" : 12
|
|
}
|
|
}
|
|
}'
|
|
--------------------------------------------------
|
|
|
|
--
|
|
|
|
[float]
|
|
[[alias-index-creation]]
|
|
=== Aliases during index creation
|
|
|
|
Aliases can also be specified during <<create-index-aliases,index creation>>:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
curl -XPUT localhost:9200/logs_20142801 -d '{
|
|
"mappings" : {
|
|
"type" : {
|
|
"properties" : {
|
|
"year" : {"type" : "integer"}
|
|
}
|
|
}
|
|
},
|
|
"aliases" : {
|
|
"current_day" : {},
|
|
"2014" : {
|
|
"filter" : {
|
|
"term" : {"year" : 2014 }
|
|
}
|
|
}
|
|
}
|
|
}'
|
|
--------------------------------------------------
|
|
|
|
[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]
|
|
--------------------------------------------------
|
|
curl -XDELETE 'localhost:9200/users/_alias/user_12'
|
|
--------------------------------------------------
|
|
|
|
[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. Partially 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 is 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]
|
|
--------------------------------------------------
|
|
curl -XGET 'localhost:9200/users/_alias/*'
|
|
--------------------------------------------------
|
|
|
|
Response:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
{
|
|
"users" : {
|
|
"aliases" : {
|
|
"user_13" : {
|
|
"filter" : {
|
|
"term" : {
|
|
"user_id" : 13
|
|
}
|
|
},
|
|
"index_routing" : "13",
|
|
"search_routing" : "13"
|
|
},
|
|
"user_14" : {
|
|
"filter" : {
|
|
"term" : {
|
|
"user_id" : 14
|
|
}
|
|
},
|
|
"index_routing" : "14",
|
|
"search_routing" : "14"
|
|
},
|
|
"user_12" : {
|
|
"filter" : {
|
|
"term" : {
|
|
"user_id" : 12
|
|
}
|
|
},
|
|
"index_routing" : "12",
|
|
"search_routing" : "12"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
|
|
All aliases with the name 2013 in any index:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
curl -XGET 'localhost:9200/_alias/2013'
|
|
--------------------------------------------------
|
|
|
|
Response:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
{
|
|
"logs_201304" : {
|
|
"aliases" : {
|
|
"2013" : { }
|
|
}
|
|
},
|
|
"logs_201305" : {
|
|
"aliases" : {
|
|
"2013" : { }
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
|
|
All aliases that start with 2013_01 in any index:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
curl -XGET 'localhost:9200/_alias/2013_01*'
|
|
--------------------------------------------------
|
|
|
|
Response:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
{
|
|
"logs_20130101" : {
|
|
"aliases" : {
|
|
"2013_01" : { }
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
|
|
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]
|
|
--------------------------------------------------
|
|
curl -XHEAD 'localhost:9200/_alias/2013'
|
|
curl -XHEAD 'localhost:9200/_alias/2013_01*'
|
|
curl -XHEAD 'localhost:9200/users/_alias/*'
|
|
--------------------------------------------------
|