Aliases
An alias points to one or more indices or data streams. Most Elasticsearch APIs accept an alias in place of a data stream or index name.
Aliases enable you to:
- Query multiple indices/data streams together with a single name
- Change which indices/data streams your application uses in real time
- Reindex data without downtime
Alias types
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
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.
resp = client.indices.update_aliases(
actions=[
{
"add": {
"index": "logs-nginx.access-prod",
"alias": "logs"
}
}
],
)
print(resp) response = client.indices.update_aliases(
body: {
actions: [
{
add: {
index: 'logs-nginx.access-prod',
alias: 'logs'
}
}
]
}
)
puts response const response = await client.indices.updateAliases({
actions: [
{
add: {
index: "logs-nginx.access-prod",
alias: "logs",
},
},
],
});
console.log(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.
resp = client.indices.update_aliases(
actions=[
{
"add": {
"index": "logs-*",
"alias": "logs"
}
}
],
)
print(resp) const response = await client.indices.updateAliases({
actions: [
{
add: {
index: "logs-*",
alias: "logs",
},
},
],
});
console.log(response); POST _aliases
{
"actions": [
{
"add": {
"index": "logs-*",
"alias": "logs"
}
}
]
} Remove an alias
To remove an alias, use the aliases API’s remove action.
resp = client.indices.update_aliases(
actions=[
{
"remove": {
"index": "logs-nginx.access-prod",
"alias": "logs"
}
}
],
)
print(resp) response = client.indices.update_aliases(
body: {
actions: [
{
remove: {
index: 'logs-nginx.access-prod',
alias: 'logs'
}
}
]
}
)
puts response const response = await client.indices.updateAliases({
actions: [
{
remove: {
index: "logs-nginx.access-prod",
alias: "logs",
},
},
],
});
console.log(response); POST _aliases
{
"actions": [
{
"remove": {
"index": "logs-nginx.access-prod",
"alias": "logs"
}
}
]
} Multiple actions
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.
resp = client.indices.update_aliases(
actions=[
{
"remove": {
"index": "logs-nginx.access-prod",
"alias": "logs"
}
},
{
"add": {
"index": "logs-my_app-default",
"alias": "logs"
}
}
],
)
print(resp) 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 const response = await client.indices.updateAliases({
actions: [
{
remove: {
index: "logs-nginx.access-prod",
alias: "logs",
},
},
{
add: {
index: "logs-my_app-default",
alias: "logs",
},
},
],
});
console.log(response); POST _aliases
{
"actions": [
{
"remove": {
"index": "logs-nginx.access-prod",
"alias": "logs"
}
},
{
"add": {
"index": "logs-my_app-default",
"alias": "logs"
}
}
]
} Multiple action results
When using multiple actions, if some succeed and some fail, a list of per-action results will be returned.
Consider a similar action list to the previous example, but now with an alias log-non-existing, which does not yet exist. In this case, the remove action will fail, but the add action will succeed. The response will contain the list action_results, with a result for every requested action.
resp = client.indices.update_aliases(
actions=[
{
"remove": {
"index": "index1",
"alias": "logs-non-existing"
}
},
{
"add": {
"index": "index2",
"alias": "logs-non-existing"
}
}
],
)
print(resp) response = client.indices.update_aliases(
body: {
actions: [
{
remove: {
index: 'index1',
alias: 'logs-non-existing'
}
},
{
add: {
index: 'index2',
alias: 'logs-non-existing'
}
}
]
}
)
puts response const response = await client.indices.updateAliases({
actions: [
{
remove: {
index: "index1",
alias: "logs-non-existing",
},
},
{
add: {
index: "index2",
alias: "logs-non-existing",
},
},
],
});
console.log(response); POST _aliases
{
"actions": [
{
"remove": {
"index": "index1",
"alias": "logs-non-existing"
}
},
{
"add": {
"index": "index2",
"alias": "logs-non-existing"
}
}
]
} The API returns the following result:
{
"acknowledged": true,
"errors": true,
"action_results": [
{
"action": {
"type": "remove",
"indices": [ "index1" ],
"aliases": [ "logs-non-existing" ],
},
"status": 404,
"error": {
"type": "aliases_not_found_exception",
"reason": "aliases [logs-non-existing] missing",
"resource.type": "aliases",
"resource.id": "logs-non-existing"
}
},
{
"action": {
"type": "add",
"indices": [ "index2" ],
"aliases": [ "logs-non-existing" ],
},
"status": 200
}
]
} Allowing the action list to succeed partially may not provide the desired result. It may be more appropriate to set must_exist to true, which will cause the entire action list to fail if a single action fails.
Add an alias at index creation
You can also use a component or index template to add index or data stream aliases when they are created.
resp = client.cluster.put_component_template(
name="my-aliases",
template={
"aliases": {
"my-alias": {}
}
},
)
print(resp)
resp1 = client.indices.put_index_template(
name="my-index-template",
index_patterns=[
"my-index-*"
],
composed_of=[
"my-aliases",
"my-mappings",
"my-settings"
],
template={
"aliases": {
"yet-another-alias": {}
}
},
)
print(resp1) 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 const response = await client.cluster.putComponentTemplate({
name: "my-aliases",
template: {
aliases: {
"my-alias": {},
},
},
});
console.log(response);
const response1 = await client.indices.putIndexTemplate({
name: "my-index-template",
index_patterns: ["my-index-*"],
composed_of: ["my-aliases", "my-mappings", "my-settings"],
template: {
aliases: {
"yet-another-alias": {},
},
},
});
console.log(response1); # 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.
resp = client.indices.create(
index="<my-index-{now/d}-000001>",
aliases={
"my-alias": {}
},
)
print(resp) response = client.indices.create(
index: '<my-index-{now/d}-000001>',
body: {
aliases: {
"my-alias": {}
}
}
)
puts response const response = await client.indices.create({
index: "<my-index-{now/d}-000001>",
aliases: {
"my-alias": {},
},
});
console.log(response); # PUT <my-index-{now/d}-000001>
PUT %3Cmy-index-%7Bnow%2Fd%7D-000001%3E
{
"aliases": {
"my-alias": {}
}
} View aliases
To get a list of your cluster’s aliases, use the get alias API with no argument.
resp = client.indices.get_alias() print(resp)
response = client.indices.get_alias puts response
const response = await client.indices.getAlias(); console.log(response);
GET _alias
Specify a data stream or index before _alias to view its aliases.
resp = client.indices.get_alias(
index="my-data-stream",
)
print(resp) response = client.indices.get_alias( index: 'my-data-stream' ) puts response
const response = await client.indices.getAlias({
index: "my-data-stream",
});
console.log(response); GET my-data-stream/_alias
Specify an alias after _alias to view its data streams or indices.
resp = client.indices.get_alias(
name="logs",
)
print(resp) response = client.indices.get_alias( name: 'logs' ) puts response
const response = await client.indices.getAlias({
name: "logs",
});
console.log(response); GET _alias/logs
Write index
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.
resp = client.indices.update_aliases(
actions=[
{
"add": {
"index": "logs-nginx.access-prod",
"alias": "logs"
}
},
{
"add": {
"index": "logs-my_app-default",
"alias": "logs",
"is_write_index": True
}
}
],
)
print(resp) 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 const response = await client.indices.updateAliases({
actions: [
{
add: {
index: "logs-nginx.access-prod",
alias: "logs",
},
},
{
add: {
index: "logs-my_app-default",
alias: "logs",
is_write_index: true,
},
},
],
});
console.log(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
The filter option uses Query DSL to limit the documents an alias can access.
resp = client.indices.update_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"
}
}
]
}
}
}
}
],
)
print(resp) 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 const response = await client.indices.updateAliases({
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",
},
},
],
},
},
},
},
],
});
console.log(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"
}
}
]
}
}
}
}
]
} Filters are only applied when using the Query DSL, and are not applied when retrieving a document by ID.
Routing
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.
resp = client.indices.update_aliases(
actions=[
{
"add": {
"index": "my-index-2099.05.06-000001",
"alias": "my-alias",
"routing": "1"
}
}
],
)
print(resp) response = client.indices.update_aliases(
body: {
actions: [
{
add: {
index: 'my-index-2099.05.06-000001',
alias: 'my-alias',
routing: '1'
}
}
]
}
)
puts response const response = await client.indices.updateAliases({
actions: [
{
add: {
index: "my-index-2099.05.06-000001",
alias: "my-alias",
routing: "1",
},
},
],
});
console.log(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.
resp = client.indices.update_aliases(
actions=[
{
"add": {
"index": "my-index-2099.05.06-000001",
"alias": "my-alias",
"search_routing": "1",
"index_routing": "2"
}
}
],
)
print(resp) 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 const response = await client.indices.updateAliases({
actions: [
{
add: {
index: "my-index-2099.05.06-000001",
alias: "my-alias",
search_routing: "1",
index_routing: "2",
},
},
],
});
console.log(response); POST _aliases
{
"actions": [
{
"add": {
"index": "my-index-2099.05.06-000001",
"alias": "my-alias",
"search_routing": "1",
"index_routing": "2"
}
}
]
} Remove an index
To remove an index, use the aliases API’s remove_index action.
resp = client.indices.update_aliases(
actions=[
{
"remove_index": {
"index": "my-index-2099.05.06-000001"
}
}
],
)
print(resp) const response = await client.indices.updateAliases({
actions: [
{
remove_index: {
index: "my-index-2099.05.06-000001",
},
},
],
});
console.log(response); POST _aliases
{
"actions": [
{
"remove_index": {
"index": "my-index-2099.05.06-000001"
}
}
]
}
© 2023-2025 Elasticsearch
As of September 2024, Elasticsearch is available under a choice of three licenses: the Server Side Public License (SSPL), the Elastic License, or the AGPLv3 (OSI approved).
Elasticsearch and the Elasticsearch logo are trademarks of Elasticsearch B.V., registered in the U.S. and in other countries.
https://www.elastic.co/guide/en/elasticsearch/reference/8.17/aliases.html
