New

The executive guide to generative AI

Read more
About usPartnersSupport|Login

WARNING: Version 2.1 of Elasticsearch has passed its EOL date.

This documentation is no longer being maintained and may be removed. If you are running this version, we strongly advise you to upgrade. For the latest information, see the current release documentation.

« Types Exists Update Indices Settings »
Elastic Docs ›Elasticsearch Guide [2.1] ›Indices APIs

Index Aliases

edit

Index Aliases

edit

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:

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

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:

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

Alternatively, you can use a glob pattern to associate an alias to more than one index that share a common name:

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

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.

Filtered Aliases

edit

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:

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:

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

Routing

edit

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:

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'

Add a single alias

edit

An alias can also be added with the endpoint

PUT /{index}/_alias/{name}

where

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.

Examples:

edit
Adding time based alias 
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:

curl -XPUT 'localhost:9200/users' -d '{
    "mappings" : {
        "user" : {
            "properties" : {
                "user_id" : {"type" : "integer"}
            }
        }
    }
}'

Then add the alias for a specific user:

curl -XPUT 'localhost:9200/users/_alias/user_12' -d '{
    "routing" : "12",
    "filter" : {
        "term" : {
            "user_id" : 12
        }
    }
}'

Aliases during index creation

edit

Aliases can also be specified during index creation:

curl -XPUT localhost:9200/logs_20142801 -d '{
    "mappings" : {
        "type" : {
            "properties" : {
                "year" : {"type" : "integer"}
            }
        }
    },
    "aliases" : {
        "current_day" : {},
        "2014" : {
            "filter" : {
                "term" : {"year" : 2014 }
            }
        }
    }
}'

Delete aliases

edit

The rest endpoint is: /{index}/_alias/{name}

where

index

* | _all | glob pattern | name1, name2, …

name

* | _all | glob pattern | name1, name2, …

Alternatively you can use the plural _aliases. Example:

curl -XDELETE 'localhost:9200/users/_alias/user_12'

Retrieving existing aliases

edit

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:

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 if an specified index name doesn’t exist. If set to true then those indices are ignored.

The rest endpoint is: /{index}/_alias/{alias}.

Examples:

edit

All aliases for the index users:

curl -XGET 'localhost:9200/users/_alias/*'

Response:

 {
  "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:

curl -XGET 'localhost:9200/_alias/2013'

Response:

{
  "logs_201304" : {
    "aliases" : {
      "2013" : { }
    }
  },
  "logs_201305" : {
    "aliases" : {
      "2013" : { }
    }
  }
}

All aliases that start with 2013_01 in any index:

curl -XGET 'localhost:9200/_alias/2013_01*'

Response:

{
  "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:

curl -XHEAD -i 'localhost:9200/_alias/2013'
curl -XHEAD -i 'localhost:9200/_alias/2013_01*'
curl -XHEAD -i 'localhost:9200/users/_alias/*'
« Types Exists Update Indices Settings »