elasticsearch/docs/reference/indices/add-alias.asciidoc

[[indices-add-alias]]
=== Create or update index alias API
++++
<titleabbrev>Create or update index alias</titleabbrev>
++++

Creates or updates an index alias.

//tag::index-alias-desc[]
An index alias is a secondary name for one or more indices. Most {es} APIs
accept an index alias in place of an index name.
//end::index-alias-desc[]

[source,console]
----
PUT /my-index-000001/_alias/alias1
----
// TEST[setup:my_index]


[[add-alias-api-request]]
==== {api-request-title}

`PUT /<index>/_alias/<alias>`

`POST /<index>/_alias/<alias>`

`PUT /<index>/_aliases/<alias>`

`POST /<index>/_aliases/<alias>`

[[add-alias-api-prereqs]]
==== {api-prereq-title}

* If the {es} {security-features} are enabled, you must have the `manage`
<<privileges-list-indices,index privilege>> for both the index and index alias.

[[add-alias-api-path-params]]
==== {api-path-parms-title}

`<index>`::
(Required, string)
Comma-separated list or wildcard expression of index names
to add to the alias.
+
To add all indices in the cluster to the alias,
use a value of `_all`.
+
NOTE: You cannot add <<data-streams,data streams>> to an index alias.

`<alias>`::
(Required, string)
Name of the index alias to create or update. Supports
<<date-math-index-names,date math>>.


[[add-alias-api-query-params]]
==== {api-query-parms-title}

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


[[add-alias-api-request-body]]
==== {api-request-body-title}

`filter`::
(Required, query object)
include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=index-alias-filter]

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

[[add-alias-api-example]]
==== {api-examples-title}

[[alias-date-math-support]]
===== Date math support

Index alias names support <<date-math-index-names,date math>>.

[source,console]
----
# POST /logs/_alias/<logs_{now/M}>
POST /logs/_alias/%3Clogs_%7Bnow%2FM%7D%3E
----
// TEST[s/^/PUT logs\n/]

[[alias-adding]]
===== Add a time-based alias

The following request creates an alias, `2030`,
for the `logs_20302801` index.

[source,console]
--------------------------------------------------
PUT /logs_20302801/_alias/2030
--------------------------------------------------
// TEST[s/^/PUT logs_20302801\n/]

[[add-alias-api-user-ex]]
===== Add a user-based alias

First, create an index, `users`,
with a mapping for the `user_id` field:

[source,console]
--------------------------------------------------
PUT /users
{
  "mappings" : {
    "properties" : {
      "user_id" : {"type" : "integer"}
    }
  }
}
--------------------------------------------------

Then add the index alias for a specific user, `user_12`:

[source,console]
--------------------------------------------------
PUT /users/_alias/user_12
{
  "routing" : "12",
  "filter" : {
    "term" : {
      "user_id" : 12
    }
  }
}
--------------------------------------------------
// TEST[continued]

[[alias-index-creation]]
===== Add an alias during index creation

You can use the <<create-index-aliases,create index API>>
to add an index alias during index creation.

[source,console]
--------------------------------------------------
PUT /logs_20302801
{
  "mappings": {
    "properties": {
      "year": { "type": "integer" }
    }
  },
  "aliases": {
    "current_day": {},
    "2030": {
      "filter": {
        "term": { "year": 2030 }
      }
    }
  }
}
--------------------------------------------------

The create index API also supports <<date-math-index-names,date math>> in index
alias names.

[source,console]
----
PUT /logs
{
  "aliases": {
    "<logs_{now/M}>": {}
  }
}
----