IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.
« Tutorial: Natural language processing (NLP) Search your data »
Elastic Docs ›Elasticsearch Guide [8.12]

Aliases

edit

Aliases

edit

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 types

edit

There are two types of aliases:

  • A data stream alias points to one or more data streams.
  • An index alias points to one or more indices.

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 alias

edit

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.

response = client.indices.update_aliases(
  body: {
    actions: [
      {
        add: {
          index: 'logs-nginx.access-prod',
          alias: 'logs'
        }
      }
    ]
  }
)
puts response
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 alias

edit

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

response = client.indices.update_aliases(
  body: {
    actions: [
      {
        remove: {
          index: 'logs-nginx.access-prod',
          alias: 'logs'
        }
      }
    ]
  }
)
puts response
POST _aliases
{
  "actions": [
    {
      "remove": {
        "index": "logs-nginx.access-prod",
        "alias": "logs"
      }
    }
  ]
}

Multiple actions

edit

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.

response = client.indices.update_aliases(
  body: {
    actions: [
      {
        remove: {
          index: 'logs-nginx.access-prod',
          alias: 'logs'
        }
      },
      {
        add: {
          index: 'logs-my_app-default',
          alias: 'logs'
        }
      }
    ]
  }
)
puts response
POST _aliases
{
  "actions": [
    {
      "remove": {
        "index": "logs-nginx.access-prod",
        "alias": "logs"
      }
    },
    {
      "add": {
        "index": "logs-my_app-default",
        "alias": "logs"
      }
    }
  ]
}

Add an alias at index creation

edit

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

response = client.cluster.put_component_template(
  name: 'my-aliases',
  body: {
    template: {
      aliases: {
        "my-alias": {}
      }
    }
  }
)
puts response

response = client.indices.put_index_template(
  name: 'my-index-template',
  body: {
    index_patterns: [
      'my-index-*'
    ],
    composed_of: [
      'my-aliases',
      'my-mappings',
      'my-settings'
    ],
    template: {
      aliases: {
        "yet-another-alias": {}
      }
    }
  }
)
puts response
# 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.

response = client.indices.create(
  index: '<my-index-{now/d}-000001>',
  body: {
    aliases: {
      "my-alias": {}
    }
  }
)
puts response
# PUT <my-index-{now/d}-000001>
PUT %3Cmy-index-%7Bnow%2Fd%7D-000001%3E
{
  "aliases": {
    "my-alias": {}
  }
}

View aliases

edit

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

response = client.indices.get_alias
puts response
GET _alias

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

response = client.indices.get_alias(
  index: 'my-data-stream'
)
puts response
GET my-data-stream/_alias

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

response = client.indices.get_alias(
  name: 'logs'
)
puts response
GET _alias/logs

Write index

edit

You can use is_write_index to specify a write index or data stream for an alias. Elasticsearch routes any write requests for the alias to this index or data stream.

response = client.indices.update_aliases(
  body: {
    actions: [
      {
        add: {
          index: 'logs-nginx.access-prod',
          alias: 'logs'
        }
      },
      {
        add: {
          index: 'logs-my_app-default',
          alias: 'logs',
          is_write_index: true
        }
      }
    ]
  }
)
puts response
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.

We recommend using data streams to store append-only time series data. If you need to update or delete existing time series data, you can perform update or delete operations directly on the data stream backing index. If you frequently send multiple documents using the same _id expecting last-write-wins, you may want to use an index alias with a write index instead. See Manage time series data without data streams.

Filter an alias

edit

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

response = client.indices.update_aliases(
  body: {
    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'
                  }
                }
              ]
            }
          }
        }
      }
    ]
  }
)
puts response
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"
                }
              }
            ]
          }
        }
      }
    }
  ]
}

Routing

edit

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.

response = client.indices.update_aliases(
  body: {
    actions: [
      {
        add: {
          index: 'my-index-2099.05.06-000001',
          alias: 'my-alias',
          routing: '1'
        }
      }
    ]
  }
)
puts response
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.

response = client.indices.update_aliases(
  body: {
    actions: [
      {
        add: {
          index: 'my-index-2099.05.06-000001',
          alias: 'my-alias',
          search_routing: '1',
          index_routing: '2'
        }
      }
    ]
  }
)
puts response
POST _aliases
{
  "actions": [
    {
      "add": {
        "index": "my-index-2099.05.06-000001",
        "alias": "my-alias",
        "search_routing": "1",
        "index_routing": "2"
      }
    }
  ]
}
« Tutorial: Natural language processing (NLP) Search your data »