Create or update an alias

POST also PUT /{index}/_aliases/{name}
POST also PUT /{index}/_alias/{name}

Auth

Adds a data stream or index to an alias.

Required privileges

Index privileges manage

Path parameters

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

Query parameters

master_timeout string · default: 30s: Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.
timeout string · default: 30s: Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.

Request body

filter {} Query: Query used to limit documents the alias can access.
index_routing 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_write_index 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.
routing string: Value used to route indexing and search operations to a specific shard. Data stream aliases don’t support this parameter.
search_routing 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.

Response

application/json

acknowledged boolean required: For a successful response, this value is always true. On failure, an exception is returned instead.
errors boolean: If true, at least one alias action failed. The request still returns HTTP 200.

Examples

Request Console 1 / 8 languages

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

Console Kibana Dev Tools

POST /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"
          }
        }
      ]
    }
  }
}

JavaScript Elasticsearch JavaScript Client

const response = await client.indices.putAlias({
  index: "my-index-2099.05.06-000001",
  name: "my-alias",
  filter: {
    bool: {
      filter: [
        {
          range: {
            "@timestamp": {
              gte: "now-1d/d",
              lt: "now/d",
            },
          },
        },
        {
          term: {
            "user.id": "kimchy",
          },
        },
      ],
    },
  },
});

Python Elasticsearch Python Client

resp = client.indices.put_alias(
    index="my-index-2099.05.06-000001",
    name="my-alias",
    filter={
        "bool": {
            "filter": [
                {
                    "range": {
                        "@timestamp": {
                            "gte": "now-1d/d",
                            "lt": "now/d"
                        }
                    }
                },
                {
                    "term": {
                        "user.id": "kimchy"
                    }
                }
            ]
        }
    },
)

curl Shell

curl -X POST "$ELASTICSEARCH_URL/my-index-2099.05.06-000001/_alias/my-alias" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "bool": {
        "filter": [
          {
            "range": {
              "@timestamp": {
                "gte": "now-1d/d",
                "lt": "now/d"
              }
            }
          },
          {
            "term": {
              "user.id": "kimchy"
            }
          }
        ]
      }
    }
  }'

Java Elasticsearch Java Client

client.indices().putAlias(p -> p
    .filter(f -> f
        .bool(b -> b
            .filter(List.of(Query.of(q -> q
                    .range(r -> r
                        .untyped(u -> u
                            .field("@timestamp")
                            .gte(JsonData.fromJson("\"now-1d/d\""))
                            .lt(JsonData.fromJson("\"now/d\""))
                        )
                    )
                ),Query.of(qu -> qu
                    .term(t -> t
                        .field("user.id")
                        .value(FieldValue.of("kimchy"))
                    )
                )))
        )
    )
    .index("my-index-2099.05.06-000001")
    .name("my-alias")
);

C# Elasticsearch .NET Client

var response = await client.Indices
    .PutAliasAsync(indices: new[] { "my-index-2099.05.06-000001" }, name: "my-alias", d1 => d1
        .Filter(d2 => d2
            .Bool(d3 => d3
                .Filter(d4 => d4
                    .Range(new UntypedRangeQuery()
                    {
                        Field = global::Elastic.Clients.Elasticsearch.Infer.Field<MyDocument>(x => x.Timestamp),
                        Gte = "now-1d/d",
                        Lt = "now/d"
                    }), d4 => d4
                    .Term(d5 => d5
                        .Field(x => x.User.Id)
                        .Value("kimchy")
                    )
                )
            )
        )
    );

PHP Elasticsearch PHP Client

$resp = $client->indices()->putAlias([
    "index" => "my-index-2099.05.06-000001",
    "name" => "my-alias",
    "body" => [
        "filter" => [
            "bool" => [
                "filter" => array(
                    [
                        "range" => [
                            "@timestamp" => [
                                "gte" => "now-1d/d",
                                "lt" => "now/d",
                            ],
                        ],
                    ],
                    [
                        "term" => [
                            "user.id" => "kimchy",
                        ],
                    ],
                ),
            ],
        ],
    ],
]);

Ruby Elasticsearch Ruby Client

response = client.indices.put_alias(
  index: "my-index-2099.05.06-000001",
  name: "my-alias",
  body: {
    "filter": {
      "bool": {
        "filter": [
          {
            "range": {
              "@timestamp": {
                "gte": "now-1d/d",
                "lt": "now/d"
              }
            }
          },
          {
            "term": {
              "user.id": "kimchy"
            }
          }
        ]
      }
    }
  }
)

Response

{
  "acknowledged": false,
  "errors": false
}

Generated from the API spec

Request Console 1 / 8 languages

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.

Console Kibana Dev Tools

POST /logs-my_app-default/_alias/logs
{
  "is_write_index": true
}

JavaScript Elasticsearch JavaScript Client

const response = await client.indices.putAlias({
  index: "logs-my_app-default",
  name: "logs",
  is_write_index: true,
});

Python Elasticsearch Python Client

resp = client.indices.put_alias(
    index="logs-my_app-default",
    name="logs",
    is_write_index=True,
)

curl Shell

curl -X POST "$ELASTICSEARCH_URL/logs-my_app-default/_alias/logs" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "is_write_index": true
  }'

Java Elasticsearch Java Client

client.indices().putAlias(p -> p
    .index("logs-my_app-default")
    .isWriteIndex(true)
    .name("logs")
);

C# Elasticsearch .NET Client

var response = await client.Indices
    .PutAliasAsync(indices: new[] { "logs-my_app-default" }, name: "logs", d1 => d1
        .IsWriteIndex(true)
    );

PHP Elasticsearch PHP Client

$resp = $client->indices()->putAlias([
    "index" => "logs-my_app-default",
    "name" => "logs",
    "body" => [
        "is_write_index" => true,
    ],
]);

Ruby Elasticsearch Ruby Client

response = client.indices.put_alias(
  index: "logs-my_app-default",
  name: "logs",
  body: {
    "is_write_index": true
  }
)

Response

{
  "acknowledged": false,
  "errors": false
}

Generated from the API spec

Request Console 1 / 8 languages

Use the routing option to route requests for an alias to a specific shard.

Console Kibana Dev Tools

POST /my-index-2099.05.06-000001/_alias/my-alias
{
  "routing": "1"
}

JavaScript Elasticsearch JavaScript Client

const response = await client.indices.putAlias({
  index: "my-index-2099.05.06-000001",
  name: "my-alias",
  routing: 1,
});

Python Elasticsearch Python Client

resp = client.indices.put_alias(
    index="my-index-2099.05.06-000001",
    name="my-alias",
    routing="1",
)

curl Shell

curl -X POST "$ELASTICSEARCH_URL/my-index-2099.05.06-000001/_alias/my-alias" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "routing": "1"
  }'

Java Elasticsearch Java Client

client.indices().putAlias(p -> p
    .index("my-index-2099.05.06-000001")
    .name("my-alias")
    .routing("1")
);

C# Elasticsearch .NET Client

var response = await client.Indices
    .PutAliasAsync(indices: new[] { "my-index-2099.05.06-000001" }, name: "my-alias", d1 => d1
        .Routing("1")
    );

PHP Elasticsearch PHP Client

$resp = $client->indices()->putAlias([
    "index" => "my-index-2099.05.06-000001",
    "name" => "my-alias",
    "body" => [
        "routing" => "1",
    ],
]);

Ruby Elasticsearch Ruby Client

response = client.indices.put_alias(
  index: "my-index-2099.05.06-000001",
  name: "my-alias",
  body: {
    "routing": "1"
  }
)

Response

{
  "acknowledged": false,
  "errors": false
}

Generated from the API spec