Create or update an alias Generally available

POST /{index}/_aliases/{name}

All methods and paths for this operation:

PUT /{index}/_alias/{name}

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

Adds a data stream or index to an alias.

Aliases

Path parameters

  • index string | array[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

    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.

    External documentation
  • timeout string

    Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.

    External documentation
application/json

Body

  • filter object

    Query used to limit documents the alias can access.

    External documentation
  • 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.

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
    • acknowledged boolean Required

      For a successful response, this value is always true. On failure, an exception is returned instead.

POST /{index}/_aliases/{name}
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"
          }
        }
      ]
    }
  }
}
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"
                    }
                }
            ]
        }
    },
)
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",
          },
        },
      ],
    },
  },
});
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"
            }
          }
        ]
      }
    }
  }
)
$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",
                        ],
                    ],
                ),
            ],
        ],
    ],
]);
curl -X POST -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"}}]}}}' "$ELASTICSEARCH_URL/my-index-2099.05.06-000001/_alias/my-alias"
Request examples
The filter option uses Query DSL to limit the documents an alias can access.
{
  "filter": {
    "bool": {
      "filter": [
        {
          "range": {
            "@timestamp": {
              "gte": "now-1d/d",
              "lt": "now/d"
            }
          }
        },
        {
          "term": {
            "user.id": "kimchy"
          }
        }
      ]
    }
  }
}
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.
{
  "is_write_index": true
}
Use the routing option to route requests for an alias to a specific shard.
{
  "routing": "1"
}