Aliases APIedit

Adds and removes multiple index aliases in a single request. Also deletes concrete indices.

An index alias is a secondary name used to refer to one or more existing indices. Most Elasticsearch APIs accept an index alias in place of an index.

POST /_aliases
{
  "actions" : [
    { "add" : { "index" : "my-index-000001", "alias" : "alias1" } }
  ]
}

Requestedit

POST /_aliases

Prerequisitesedit

  • If the Elasticsearch security features are enabled, you must have the following index privileges:

    • To use the add or remove action, you must have the manage index privilege for both the index and index alias.
    • To use the remove_index action, you must have the manage index privilege for the index.

Descriptionedit

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.

Query parametersedit

master_timeout
(Optional, time units) Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error. Defaults to 30s.
timeout
(Optional, time units) Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error. Defaults to 30s.

Request bodyedit

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 a concrete index, similar to the delete index API. Attempts to remove an index alias will fail.

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.

You cannot add data streams to an index alias.

indices

(Array) Array of index names used to perform the action.

If the index parameter is not specified, this parameter is required.

You cannot add data streams to an index alias.

alias

(String) Comma-separated list or wildcard expression of index alias names to add, remove, or delete. Supports date math.

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. Supports date math.

If the alias parameter is not specified, this parameter is required for the add or remove action.

filter

(Optional, query object) Filter query used to limit the index alias.

If specified, the index alias only applies to documents returned by the filter.

See Filtered aliases for an example.

is_hidden
(Optional, Boolean) If true, the alias will be excluded from wildcard expressions by default, unless overridden in the request using the expand_wildcards parameter, similar to 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 Write index for an example.

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.

routing

(Optional, string) Custom value used to route operations to a specific shard.

See Routing for an example.

index_routing

(Optional, string) Custom routing value used for the alias’s indexing operations.

See Routing for an example.

search_routing

(Optional, string) Custom routing value used for the alias’s search operations.

See Routing for an example.

Examplesedit

Add an aliasedit

The following request adds the alias1 alias to the test1 index.

POST /_aliases
{
  "actions" : [
    { "add" : { "index" : "test1", "alias" : "alias1" } }
  ]
}

Index alias names support date math.

POST /_aliases
{
  "actions" : [
    { "add" : { "index" : "logs", "alias" : "<logs_{now/M}>" } }
  ]
}

Remove an aliasedit

The following request removes the alias1 alias.

POST /_aliases
{
  "actions" : [
    { "remove" : { "index" : "test1", "alias" : "alias1" } }
  ]
}

Rename an aliasedit

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:

POST /_aliases
{
  "actions" : [
    { "remove" : { "index" : "test1", "alias" : "alias1" } },
    { "add" : { "index" : "test1", "alias" : "alias2" } }
  ]
}

Add an alias to multiple indicesedit

Associating an alias with more than one index is simply several add actions:

POST /_aliases
{
  "actions" : [
    { "add" : { "index" : "test1", "alias" : "alias1" } },
    { "add" : { "index" : "test2", "alias" : "alias1" } }
  ]
}

Multiple indices can be specified for an action with the indices array syntax:

POST /_aliases
{
  "actions" : [
    { "add" : { "indices" : ["test1", "test2"], "alias" : "alias1" } }
  ]
}

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:

POST /_aliases
{
  "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.

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.

PUT test     
PUT test_2   
POST /_aliases
{
  "actions" : [
    { "add":  { "index": "test_2", "alias": "test" } },
    { "remove_index": { "index": "test" } }  
  ]
}

An index we’ve added by mistake

The index we should have added

remove_index is just like Delete index and will only remove a concrete index.

Filtered aliasesedit

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:

PUT /my-index-000001
{
  "mappings": {
    "properties": {
      "@timestamp": {
        "type": "date"
      },
      "user": {
        "properties": {
          "id": {
            "type": "keyword"
          }
        }
      }
    }
  }
}

Now we can create an alias that filters on @timestamp and user.id:

POST /_aliases
{
  "actions": [
    {
      "add": {
        "index": "my-index-000001",
        "alias": "alias2",
        "filter": {
          "bool": {
            "filter": [
              {
                "range": {
                  "@timestamp": {
                    "gte": "now-1d/d",
                    "lt": "now/d"
                  }
                }
              },
              {
                "term": {
                  "user.id": "kimchy"
                }
              }
            ]
          }
        }
      }
    }
  ]
}

Routingedit

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:

POST /_aliases
{
  "actions": [
    {
      "add": {
        "index": "test",
        "alias": "alias1",
        "routing": "1"
      }
    }
  ]
}

It’s also possible to specify different routing values for searching and indexing operations:

POST /_aliases
{
  "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 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:

GET /alias2/_search?q=user.id:kimchy&routing=2,3

Write indexedit

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 Rollover With Write Index).

POST /_aliases
{
  "actions": [
    {
      "add": {
        "index": "test",
        "alias": "alias1",
        "is_write_index": true
      }
    },
    {
      "add": {
        "index": "test2",
        "alias": "alias1"
      }
    }
  ]
}

In this example, we associate the alias alias1 to both test and test2, where test will be the index chosen for writing to.

PUT /alias1/_doc/1
{
  "foo": "bar"
}

The new document that was indexed to /alias1/_doc/1 will be indexed as if it were /test/_doc/1.

GET /test/_doc/1

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.

POST /_aliases
{
  "actions": [
    {
      "add": {
        "index": "test",
        "alias": "alias1",
        "is_write_index": false
      }
    }, {
      "add": {
        "index": "test2",
        "alias": "alias1",
        "is_write_index": true
      }
    }
  ]
}