elasticsearch/docs/reference/indices/aliases.asciidoc

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

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

[source,console]
----
POST _aliases
{
  "actions": [
    {
      "add": {
        "index": "my-data-stream",
        "alias": "my-alias"
      }
    }
  ]
}
----
// TEST[setup:my_data_stream]
// TEST[teardown:data_stream_cleanup]

[[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 the alias and its data streams or indices.

** To use the `remove_index` action, you must have the `manage` index privilege
for the index.

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

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

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

`actions`::
(Required, array of objects) Actions to perform.
+
.Properties of `actions` objects
[%collapsible%open]
====
`<action>`::
(Required, object) The key is the action type. At least one action is required.
+
.Valid `<action>` keys
[%collapsible%open]
=====
`add`::
Adds a data stream or index to an alias. If the alias doesn't exist, the `add`
action creates it.

`remove`::
Removes a data stream or index from an alias.

`remove_index`::
Deletes an index. You cannot use this action on aliases or data streams.
=====
+
The object body contains options for the alias. Supports an empty object.
+
.Properties of `<action>`
[%collapsible%open]
=====
`alias`::
(Required*, string) Alias for the action. Index alias names support
<<api-date-math-index-names,date math>>. If `aliases` is not specified, the `add`
and `remove` actions require this parameter. For the `remove` action, this
parameter supports wildcards (`*`). The `remove_index` action doesn't support
this parameter.

`aliases`::
(Required*, array of strings) Aliases for the action. Index alias names support
<<api-date-math-index-names,date math>>. If `alias` is not specified, the `add` and
`remove` actions require this parameter. For the `remove` action, this parameter
supports wildcards (`*`). The `remove_index` action doesn't support this
parameter.

// tag::alias-options[]
`filter`::
(Optional, <<query-dsl,Query DSL object>> Query used to limit documents the
alias can access.
// end::alias-options[]
+
Only the `add` action supports this parameter.

`index`::
(Required*, string) Data stream or index for the action. Supports wildcards
(`*`). If `indices` is not specified, this parameter is required. For the `add`
and `remove_index` actions, wildcard patterns that match both data streams and
indices return an error.

`indices`::
(Required*, array of strings) Data streams or indices for the action. Supports
wildcards (`*`). If `index` is not specified, this parameter is required. For
the `add` and `remove_index` actions, wildcard patterns that match both data
streams and indices return an error.

// tag::alias-options[]
`index_routing`::
(Optional, string) Value used to route indexing operations to a specific shard.
If specified, this overwrites the `routing` value for indexing operations. Data
stream aliases don't support this parameter.
// end::alias-options[]
+
Only the `add` action supports this parameter.

// tag::alias-options[]
`is_hidden`::
(Optional, Boolean) If `true`, the alias is <<multi-hidden,hidden>>. Defaults to
`false`. All data streams or indices for the alias must have the same
`is_hidden` value.
// end::alias-options[]
+
Only the `add` action supports this parameter.

// tag::alias-options[]
`is_write_index`::
(Optional, Boolean) If `true`, sets the write index or data stream for the
alias.
+
// tag::write-index-defaults[]
If an alias points to multiple indices or data streams and `is_write_index`
isn't set, the alias rejects write requests. If an index alias points to one
index and `is_write_index` isn't set, the index automatically acts as the write
index. Data stream aliases don't automatically set a write data stream, even if
the alias points to one data stream.
// end::write-index-defaults[]
// end::alias-options[]
+
Only the `add` action supports this parameter.

// tag::alias-options[]
`must_exist`::
(Optional, Boolean)
Affects the behavior when attempting to remove an alias which does not exist.
If `true`, removing an alias which does not exist will cause all actions to fail.
If `false`, removing an alias which does not exist will only cause that removal to fail.
Defaults to `false`.
// end::alias-options[]
+
Only the `remove` action supports this parameter.

// tag::alias-options[]
`routing`::
(Optional, string) Value used to route indexing and search operations to a
specific shard. Data stream aliases don't support this parameter.
// end::alias-options[]
+
Only the `add` action supports this parameter.

// tag::alias-options[]
`search_routing`::
(Optional, string) Value used to route search operations to a specific shard. If
specified, this overwrites the `routing` value for search operations. Data
stream aliases don't support this parameter.
// end::alias-options[]
+
Only the `add` action supports this parameter.
=====
====



[role="child_attributes"]
[[indices-aliases-api-response-body]]
==== {api-response-body-title}

`acknowledged`::
(Boolean)
If `true`, the request received a response from the master node within the
`timeout` period.

`errors`::
(Boolean)
If `true`, at least one of the requested actions failed.

`action_results`::
(Optional, array of objects) Results for each requested action.
+
.Properties of `action_results` objects
[%collapsible%open]
====

`action`::
(object)
Description of the associated action request.
+
.Properties of `action` object
[%collapsible%open]
=====
`type`::
(string) The type of the associated action, one of `add`, `remove`, or `remove_index`.

`indices`::
(array of strings) List of indices in the associated action.

`aliases`::
(array of strings) List of aliases in the associated action.
=====

`status`::
(integer) HTTP status code returned for the action.

`error`::
(Optional, object) Contains additional information about the failed action.
+
Only present if the action failed.
====