OpenSearch/docs/reference/indices/aliases.asciidoc

[[indices-aliases]]
=== Update index alias API
++++
<titleabbrev>Update index alias</titleabbrev>
++++

Adds or removes index aliases.

include::{es-repo-dir}/glossary.asciidoc[tag=index-alias-desc]

[source,console]
----
POST /_aliases
{
  "actions" : [
    { "add" : { "index" : "my-index-000001", "alias" : "alias1" } }
  ]
}
----
// TEST[setup:my_index]


[[indices-aliases-api-request]]
==== {api-request-title}

`POST /_aliases`


[[indices-aliases-api-desc]]
==== {api-description-title}

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.


[[indices-aliases-api-query-params]]
==== {api-query-parms-title}

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=timeoutparms]


[[indices-aliases-api-request-body]]
==== {api-request-body-title}

`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 an index or index alias,
like the <<indices-delete-index,delete index API>>.

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.
+
NOTE: You cannot add <<data-streams,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.
+
NOTE: You cannot add <<data-streams,data streams>> to an index alias.

`alias`::
(String)
Comma-separated list or wildcard expression of index alias names to
add, remove, or delete.
+
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.
+
If the `alias` parameter is not specified,
this parameter is required for the `add` or `remove` action.

`filter`::
(Optional, query object)
include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=index-alias-filter]
+
See <<filtered>> for an example.

`is_hidden`::
(Optional, boolean)
If `true`, the alias will be excluded from wildcard expressions by default,
unless overriden in the request using the `expand_wildcards` parameter,
similar to <<index-hidden,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 <<aliases-write-index>> for an example.
+
[IMPORTANT]
====
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.
====

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=index-routing]
+
See <<aliases-routing>> for an example.

`index_routing`::
(Optional, string)
Custom <<mapping-routing-field, routing value>> used
for the alias's indexing operations.
+
See <<aliases-routing>> for an example.

`search_routing`::
(Optional, string)
Custom <<mapping-routing-field, routing value>> used
for the alias's search operations.
+
See <<aliases-routing>> for an example.
--


[[indices-aliases-api-example]]
==== {api-examples-title}

[[indices-aliases-api-add-alias-ex]]
===== Add an alias

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

[source,console]
--------------------------------------------------
POST /_aliases
{
  "actions" : [
    { "add" : { "index" : "test1", "alias" : "alias1" } }
  ]
}
--------------------------------------------------
// TEST[s/^/PUT test1\nPUT test2\n/]

[[indices-aliases-api-remove-alias-ex]]
===== Remove an alias

The following request removes the `alias1` alias.

[source,console]
--------------------------------------------------
POST /_aliases
{
  "actions" : [
    { "remove" : { "index" : "test1", "alias" : "alias1" } }
  ]
}
--------------------------------------------------
// TEST[continued]

[[indices-aliases-api-rename-alias-ex]]
===== Rename an alias

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,console]
--------------------------------------------------
POST /_aliases
{
  "actions" : [
    { "remove" : { "index" : "test1", "alias" : "alias1" } },
    { "add" : { "index" : "test1", "alias" : "alias2" } }
  ]
}
--------------------------------------------------
// TEST[continued]

[[indices-aliases-api-add-multi-alias-ex]]
===== Add an alias to multiple indices

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

[source,console]
--------------------------------------------------
POST /_aliases
{
  "actions" : [
    { "add" : { "index" : "test1", "alias" : "alias1" } },
    { "add" : { "index" : "test2", "alias" : "alias1" } }
  ]
}
--------------------------------------------------
// TEST[s/^/PUT test1\nPUT test2\n/]

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

[source,console]
--------------------------------------------------
POST /_aliases
{
  "actions" : [
    { "add" : { "indices" : ["test1", "test2"], "alias" : "alias1" } }
  ]
}
--------------------------------------------------
// 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,console]
--------------------------------------------------
POST /_aliases
{
  "actions" : [
    { "add" : { "index" : "test*", "alias" : "all_test_indices" } }
  ]
}
--------------------------------------------------
// 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, 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.

[source,console]
--------------------------------------------------
PUT test     <1>
PUT test_2   <2>
POST /_aliases
{
  "actions" : [
    { "add":  { "index": "test_2", "alias": "test" } },
    { "remove_index": { "index": "test" } }  <3>
  ]
}
--------------------------------------------------

<1> An index we've added by mistake
<2> The index we should have added
<3> `remove_index` is just like <<indices-delete-index>>

[[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,console]
--------------------------------------------------
PUT /my-index-000001
{
  "mappings": {
    "properties": {
      "user": {
        "properties": {
          "id": {
            "type": "keyword"
          }
        }
      }
    }
  }
}
--------------------------------------------------

Now we can create an alias that uses a filter on field `user.id`:

[source,console]
--------------------------------------------------
POST /_aliases
{
  "actions": [
    {
      "add": {
        "index": "my-index-000001",
        "alias": "alias2",
        "filter": { "term": { "user.id": "kimchy" } }
      }
    }
  ]
}
--------------------------------------------------
// TEST[continued]

[[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,console]
--------------------------------------------------
POST /_aliases
{
  "actions": [
    {
      "add": {
        "index": "test",
        "alias": "alias1",
        "routing": "1"
      }
    }
  ]
}
--------------------------------------------------
// TEST[s/^/PUT test\n/]

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

[source,console]
--------------------------------------------------
POST /_aliases
{
  "actions": [
    {
      "add": {
        "index": "test",
        "alias": "alias2",
        "search_routing": "1,2",
        "index_routing": "2"
      }
    }
  ]
}
--------------------------------------------------
// 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,console]
--------------------------------------------------
GET /alias2/_search?q=user.id:kimchy&routing=2,3
--------------------------------------------------
// TEST[continued]

[[aliases-write-index]]
===== Write index

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 <<indices-rollover-index, Rollover With Write Index>>).

[source,console]
--------------------------------------------------
POST /_aliases
{
  "actions": [
    {
      "add": {
        "index": "test",
        "alias": "alias1",
        "is_write_index": true
      }
    },
    {
      "add": {
        "index": "test2",
        "alias": "alias1"
      }
    }
  ]
}
--------------------------------------------------
// TEST[s/^/PUT test\nPUT test2\n/]

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

[source,console]
--------------------------------------------------
PUT /alias1/_doc/1
{
  "foo": "bar"
}
--------------------------------------------------
// TEST[continued]

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

[source,console]
--------------------------------------------------
GET /test/_doc/1
--------------------------------------------------
// TEST[continued]

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.

[source,console]
--------------------------------------------------
POST /_aliases
{
  "actions": [
    {
      "add": {
        "index": "test",
        "alias": "alias1",
        "is_write_index": false
      }
    }, {
      "add": {
        "index": "test2",
        "alias": "alias1",
        "is_write_index": true
      }
    }
  ]
}
--------------------------------------------------
// TEST[s/^/PUT test\nPUT test2\n/]