IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.

« Create or update component template API Create or update index template API »

› › ›

Create or update index alias API

edit

Create or update index alias API

edit

Creates or updates an index alias.

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

PUT /my-index-000001/_alias/alias1

Request

edit

PUT /<index>/_alias/<alias>

POST /<index>/_alias/<alias>

PUT /<index>/_aliases/<alias>

POST /<index>/_aliases/<alias>

Prerequisites

edit

If the Elasticsearch security features are enabled, you must have the manage index privilege for both the index and index alias.

Path parameters

edit

<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.

You cannot add data streams to an index alias.

<alias>

(Required, string) Name of the index alias to create or update. Supports date math.

Query parameters

edit

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 body

edit

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.

routing

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

Examples

edit

Date math support

edit

Index alias names support date math.

# POST /logs/_alias/<logs_{now/M}>
POST /logs/_alias/%3Clogs_%7Bnow%2FM%7D%3E

Add a time-based alias

edit

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

PUT /logs_20302801/_alias/2030

Add a user-based alias

edit

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

PUT /users
{
  "mappings" : {
    "properties" : {
      "user_id" : {"type" : "integer"}
    }
  }
}

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

PUT /users/_alias/user_12
{
  "routing" : "12",
  "filter" : {
    "term" : {
      "user_id" : 12
    }
  }
}

Add an alias during index creation

edit

You can use the create index API to add an index alias during index creation.

PUT /logs_20302801
{
  "mappings": {
    "properties": {
      "year": { "type": "integer" }
    }
  },
  "aliases": {
    "current_day": {},
    "2030": {
      "filter": {
        "term": { "year": 2030 }
      }
    }
  }
}

The create index API also supports date math in index alias names.

PUT /logs
{
  "aliases": {
    "<logs_{now/M}>": {}
  }
}

« Create or update component template API Create or update index template API »