› › ›

Create or update alias API

Adds a data stream or index to an alias.

resp = client.indices.put_alias(
    index="my-data-stream",
    name="my-alias",
)
print(resp)

response = client.indices.put_alias(
  index: 'my-data-stream',
  name: 'my-alias'
)
puts response

const response = await client.indices.putAlias({
  index: "my-data-stream",
  name: "my-alias",
});
console.log(response);

PUT my-data-stream/_alias/my-alias

Request

POST <target>/_alias/<alias>

POST <target>/_aliases/<alias>

PUT <target>/_alias/<alias>

PUT <target>/_aliases/<alias>

Prerequisites

If the Elasticsearch security features are enabled, you must have the manage index privilege for the alias and its data streams or indices.

Path parameters

<alias>: (Required, string) Alias to update. If the alias doesn’t exist, the request creates it. Index alias names support date math.
<target>: (Required, string) Comma-separated list of data streams or indices to add. Supports wildcards (*). Wildcard patterns that match both data streams and indices return an error.

Query parameters

master_timeout: (Optional, time units) Period to wait for the master node. If the master node is not available before the timeout expires, the request fails and returns an error. Defaults to 30s. Can also be set to -1 to indicate that the request should never timeout.
timeout: (Optional, time units) Period to wait for a response from all relevant nodes in the cluster after updating the cluster metadata. If no response is received before the timeout expires, the cluster metadata update still applies but the response will indicate that it was not completely acknowledged. Defaults to 30s. Can also be set to -1 to indicate that the request should never timeout.

Request body

filter

(Optional, Query DSL object Query used to limit documents the alias can access.

index_routing

(Optional, string) Value used to route indexing operations to a specific shard. If specified, this overwrites the routing value for indexing operations. Data stream aliases don’t support this parameter.

is_hidden

(Optional, Boolean) If true, the alias is hidden. Defaults to false. All data streams or indices for the alias must have the same is_hidden value.

is_write_index

(Optional, Boolean) If true, sets the write index or data stream for the alias.

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.

must_exist

(Optional, Boolean) Affects the behavior when attempting to remove an alias which does not exist. If true, removing an alias which does not exist will cause all actions to fail. If false, removing an alias which does not exist will only cause that removal to fail. Defaults to false.

routing

(Optional, string) Value used to route indexing and search operations to a specific shard. Data stream aliases don’t support this parameter.

search_routing

(Optional, string) Value used to route search operations to a specific shard. If specified, this overwrites the routing value for search operations. Data stream aliases don’t support this parameter.

© 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/indices-add-alias.html