Index aliases

If your data is spread across multiple indexes, rather than keeping track of which indexes to query, you can create an alias and query it instead.

For example, if you’re storing logs into indexes based on the month and you frequently query the logs for the previous two months, you can create a alias and update the indexes it points to each month.

Because you can change the indexes an alias points to at any time, referring to indexes using aliases in your applications allows you to reindex your data without any downtime.

To create an alias, use a POST request:

Use the actions method to specify the list of actions that you want to perform. This command creates an alias named alias1 and adds index-1 to this alias:

  1. POST _aliases
  2. {
  3.   "actions": [
  4.     {
  5.       "add": {
  6.         "index": "index-1",
  7.         "alias": "alias1"
  8.       }
  9.     }
  10.   ]
  11. }

You should see the following response:

  1. {
  2.    "acknowledged": true
  3. }

If this request fails, make sure the index that you’re adding to the alias already exists.

You can also create an alias using one of the following requests:

  1. PUT <index>/_aliases/<alias name>
  2. PUT <index>/_aliases/<alias name>
  3. POST <index>/_alias/<alias name>

To check if alias1 refers to index-1, run one of the following commands:

  1. GET /_alias/alias1
  2. GET /index-1/_alias/alias1

To get the mappings and settings information of the indexes that the alias references, run the following command:

  1. GET alias1

Add or remove indexes

You can perform multiple actions in the same _aliases operation. For example, the following command removes index-1 and adds index-2 to alias1:

The add and remove actions occur atomically, which means that at no point will alias1 point to both and index-2.

You can also add indexes based on an index pattern:

  1. POST _aliases
  2. {
  3.   "actions": [
  4.     {
  5.       "add": {
  6.         "index": "index*",
  7.         "alias": "alias1"
  8.       }
  9.     }
  10.   ]
  11. }

To list the mapping of aliases to indexes, run the following command:

  1. GET _cat/aliases?v

Sample response

  1. alias     index   filter    routing.index   routing.search
  2. alias1    index-1   *             -                 -

To check which indexes an alias points to, run the following command:

  1. GET _alias/alias1

Sample response

  1. {
  2.   "index-2": {
  3.     "aliases": {
  4.       "alias1": {}
  5.     }
  6.   }
  7. }

Conversely, to find which alias points to a specific index, run the following command:

  1. GET /_alias

To check if an alias exists, run one of the following commands:

  1. HEAD /_alias/alias1/
  2. HEAD index-1/_alias/alias1/

Add aliases at index creation

You can add an index to an alias as you create the index:

  1. PUT index-1
  2. {
  3.   "aliases": {
  4.     "alias1": {}
  5.   }
  6. }

You can create a filtered alias to access a subset of documents or fields from the underlying indexes.

This command adds only a specific timestamp field to alias1:

  1. POST _aliases
  3.   "actions": [
  4.     {
  5.       "add": {
  6.         "index": "index-1",
  7.         "alias": "alias1",
  8.         "filter": {
  9.           "term": {
  10.             "timestamp": "1574641891142"
  11.           }
  12.         }
  13.       }
  14.     }
  15.   ]
  16. }

Index alias options

You can specify the options shown in the following table.

To delete one or more aliases from an index, use the following request:

  1. DELETE <index>/_alias/<alias>
  2. DELETE <index>/_aliases/<alias>

Both <index> and <alias> in the above request support comma-separated lists and wildcard expressions. Use _all in place of <alias> to delete all aliases for the indexes listed in <index>.

For example, if alias1 refers to index-1 and index-2, you can run the following command to remove alias1 from index-1: