Aliases
editAliases
editAn 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
editThere 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
editTo 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
editTo 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
editYou 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
editYou 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 aliases
editTo 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
editYou 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 frequently update or delete existing time series data, use an index alias with a write index instead. See Manage time series data without data streams.
Filter an alias
editThe 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
editUse 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" } } ] }