Admin Indices 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 a routing values.

Here is a sample of associating the alias alias1 with index test1:

curl -XPOST 'http://localhost:9200/_aliases' -d '
{
    "actions" : [
        { "add" : { "index" : "test1", "alias" : "alias1" } }
    ]
}'

An alias can also be removed, for example:

curl -XPOST 'http://localhost:9200/_aliases' -d '
{
    "actions" : [
        { "remove" : { "index" : "test1", "alias" : "alias1" } }
    ]
}'

Renaming an index is a simple remove then add operation within the same API:

curl -XPOST 'http://localhost:9200/_aliases' -d '
{
    "actions" : [
        { "remove" : { "index" : "test1", "alias" : "alias1" } },
        { "add" : { "index" : "test1", "alias" : "alias2" } }
    ]
}'

Associating an alias with more then one index are simply several add actions:

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.

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. Here is an example:

curl -XPOST 'http://localhost:9200/_aliases' -d '
{
    "actions" : [
        {
            "add" : {
                 "index" : "test1",
                 "alias" : "alias2",
                 "filter" : { "term" : { "user" : "kimchy" } }
            }
        }
    ]
}'

Routing

Allow 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:

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:

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:

curl -XGET 'http://localhost:9200/alias2/_search?q=user:kimchy&routing=2,3'

Retrieving existing aliases

Aliases can be retrieved using the get aliases API, which can either return all indices with all aliases, or just for specific indices:

curl -XGET 'localhost:9200/test/_aliases'
curl -XGET 'localhost:9200/test1,test2/_aliases'
curl -XGET 'localhost:9200/_aliases'