Aliasesedit

An alias is a secondary name for a group of data streams or indices. Most Elasticsearch APIs accept an alias in place of a data stream or index name.

You can change the data streams or indices of an alias at any time. If you use aliases in your application’s Elasticsearch requests, you can reindex data with no downtime or changes to your app’s code.

Alias typesedit

There are two types of aliases:

An alias cannot point to both data streams and indices. You also cannot add a data stream’s backing index to an index alias.

Add an aliasedit

To add an existing data stream or index to an alias, use the aliases API's add action. If the alias doesn’t exist, the request creates it.

POST _aliases
{
  "actions": [
    {
      "add": {
        "index": "logs-nginx.access-prod",
        "alias": "logs"
      }
    }
  ]
}

The API’s index and indices parameters support wildcards (*). Wildcard patterns that match both data streams and indices return an error.

POST _aliases
{
  "actions": [
    {
      "add": {
        "index": "logs-*",
        "alias": "logs"
      }
    }
  ]
}

Remove an aliasedit

To remove an alias, use the aliases API’s remove action.

POST _aliases
{
  "actions": [
    {
      "remove": {
        "index": "logs-nginx.access-prod",
        "alias": "logs"
      }
    }
  ]
}

Multiple actionsedit

You can use the aliases API to perform multiple actions in a single atomic operation.

For example, the logs alias points to a single data stream. The following request swaps the stream for the alias. During this swap, the logs alias has no downtime and never points to both streams at the same time.

POST _aliases
{
  "actions": [
    {
      "remove": {
        "index": "logs-nginx.access-prod",
        "alias": "logs"
      }
    },
    {
      "add": {
        "index": "logs-my_app-default",
        "alias": "logs"
      }
    }
  ]
}

Add an alias at index creationedit

You can also use a component or index template to add index or data stream aliases when they are created.

# Component template with index aliases
PUT _component_template/my-aliases
{
  "template": {
    "aliases": {
      "my-alias": {}
    }
  }
}

# Index template with index aliases
PUT _index_template/my-index-template
{
  "index_patterns": [
    "my-index-*"
  ],
  "composed_of": [
    "my-aliases",
    "my-mappings",
    "my-settings"
  ],
  "template": {
    "aliases": {
      "yet-another-alias": {}
    }
  }
}

You can also specify index aliases in create index API requests.

# PUT <my-index-{now/d}-000001>
PUT %3Cmy-index-%7Bnow%2Fd%7D-000001%3E
{
  "aliases": {
    "my-alias": {}
  }
}

View aliasesedit

To get a list of your cluster’s aliases, use the get alias API with no argument.

GET _alias

Specify a data stream or index before _alias to view its aliases.

GET my-data-stream/_alias

Specify an alias after _alias to view its data streams or indices.

GET _alias/logs

Write indexedit

If an alias points to multiple indices, you can use is_write_index to specify a write index or data stream. Elasticsearch routes any write requests for the alias to this index or data stream.

POST _aliases
{
  "actions": [
    {
      "add": {
        "index": "logs-nginx.access-prod",
        "alias": "logs"
      }
    },
    {
      "add": {
        "index": "logs-my_app-default",
        "alias": "logs",
        "is_write_index": true
      }
    }
  ]
}

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.

Filter an aliasedit

The filter option uses Query DSL to limit the documents an alias can access.

POST _aliases
{
  "actions": [
    {
      "add": {
        "index": "my-index-2099.05.06-000001",
        "alias": "my-alias",
        "filter": {
          "bool": {
            "filter": [
              {
                "range": {
                  "@timestamp": {
                    "gte": "now-1d/d",
                    "lt": "now/d"
                  }
                }
              },
              {
                "term": {
                  "user.id": "kimchy"
                }
              }
            ]
          }
        }
      }
    }
  ]
}

Routingedit

Use the routing option to route requests for an alias to a specific shard. This lets you take advantage of shard caches to speed up searches. Data stream aliases do not support routing options.

POST _aliases
{
  "actions": [
    {
      "add": {
        "index": "my-index-2099.05.06-000001",
        "alias": "my-alias",
        "routing": "1"
      }
    }
  ]
}

Use index_routing and search_routing to specify different routing values for indexing and search. If specified, these options overwrite the routing value for their respective operations.

POST _aliases
{
  "actions": [
    {
      "add": {
        "index": "my-index-2099.05.06-000001",
        "alias": "my-alias",
        "search_routing": "1",
        "index_routing": "2"
      }
    }
  ]
}