elasticsearch/docs/reference/indices/aliases.asciidoc

[[indices-aliases]]
=== Aliases API
++++
<titleabbrev>Aliases</titleabbrev>
++++

Performs one or more <<alias,alias>> actions in a single atomic operation.

[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-prereqs]]
==== {api-prereq-title}

* If the {es} {security-features} are enabled, you must have the following
<<privileges-list-indices,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.

[[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 a concrete index, similar to the <<indices-delete-index, 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.
+
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. Supports <<date-math-index-names,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-index-names,date math>>.
+
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 <<filter-alias>> 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 <<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 <<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=routing]
+
See <<alias-routing>> for an example.

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

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