Update aliases and delete indices atomically

POST /_aliases

Auth

Applies one or more actions in a single request:

Add a data stream or index to an alias.
Remove a data stream or index from an alias.
Delete an index in that same request, so the deletion and the alias changes are applied together.

For example, you can replace an index with an alias of the same name.

Note

Every remove_index action in the request runs first, before any add or remove actions, no matter where it sits in the actions array.

Required privileges

Index privileges manage

Query parameters

master_timeout union oneOf · 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.; Values: -1 0
timeout union oneOf · default: 30s: Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.; Values: -1 0

Request body

actions object[]: Actions to perform.

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.
action_results object[]: Results for each action in the request. Returned only when errors is true.

View as Markdown

Examples

Request Console 1 / 8 languages

If the alias does not exist, it is created.

Console Kibana Dev Tools

POST _aliases
{
  "actions": [
    {
      "add": {
        "index": "logs-nginx.access-*",
        "alias": "logs"
      }
    }
  ]
}

JavaScript Elasticsearch JavaScript Client

const response = await client.indices.updateAliases({
  actions: [
    {
      add: {
        index: "logs-nginx.access-*",
        alias: "logs",
      },
    },
  ],
});

Python Elasticsearch Python Client

resp = client.indices.update_aliases(
    actions=[
        {
            "add": {
                "index": "logs-nginx.access-*",
                "alias": "logs"
            }
        }
    ],
)

curl Shell

curl -X POST "$ELASTICSEARCH_URL/_aliases" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "actions": [
      {
        "add": {
          "index": "logs-nginx.access-*",
          "alias": "logs"
        }
      }
    ]
  }'

Java Elasticsearch Java Client

client.indices().updateAliases(u -> u
    .actions(a -> a
        .add(ad -> ad
            .alias("logs")
            .index("logs-nginx.access-prod")
        )
    )
);

C# Elasticsearch .NET Client

var response = await client.Indices
    .UpdateAliasesAsync(d1 => d1
        .Actions(d2 => d2
            .Add(d3 => d3
                .Alias("logs")
                .Index("logs-nginx.access-*")
            )
        )
    );

PHP Elasticsearch PHP Client

$resp = $client->indices()->updateAliases([
    "body" => [
        "actions" => array(
            [
                "add" => [
                    "index" => "logs-nginx.access-*",
                    "alias" => "logs",
                ],
            ],
        ),
    ],
]);

Ruby Elasticsearch Ruby Client

response = client.indices.update_aliases(
  body: {
    "actions": [
      {
        "add": {
          "index": "logs-nginx.access-*",
          "alias": "logs"
        }
      }
    ]
  }
)

Response

When using multiple actions, if some succeed and some fail, the API returns a list of per-action results. For example, if the alias logs-non-existing does not exist, the API returns a 404 error for the remove action.

{
  "acknowledged": true,
  "errors": true,
  "action_results": [
    {
      "action": {
        "type": "remove",
        "indices": [
          "logs-nginx.access-prod"
        ],
        "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": [
          "logs-nginx.access-default"
        ],
        "aliases": [
          "logs-non-existing"
        ]
      },
      "status": 200
    }
  ]
}

Request Console 1 / 7 languages

Console Kibana Dev Tools

POST _aliases
{
  "actions": [
    {
      "remove": {
        "index": "logs-nginx.access-prod",
        "alias": "logs"
      }
    }
  ]
}

JavaScript Elasticsearch JavaScript Client

const response = await client.indices.updateAliases({
  actions: [
    {
      remove: {
        index: "logs-nginx.access-prod",
        alias: "logs",
      },
    },
  ],
});

Python Elasticsearch Python Client

resp = client.indices.update_aliases(
    actions=[
        {
            "remove": {
                "index": "logs-nginx.access-prod",
                "alias": "logs"
            }
        }
    ],
)

curl Shell

curl -X POST "$ELASTICSEARCH_URL/_aliases" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "actions": [
      {
        "remove": {
          "index": "logs-nginx.access-prod",
          "alias": "logs"
        }
      }
    ]
  }'

C# Elasticsearch .NET Client

var response = await client.Indices
    .UpdateAliasesAsync(d1 => d1
        .Actions(d2 => d2
            .Remove(d3 => d3
                .Alias("logs")
                .Index("logs-nginx.access-prod")
            )
        )
    );

PHP Elasticsearch PHP Client

$resp = $client->indices()->updateAliases([
    "body" => [
        "actions" => array(
            [
                "remove" => [
                    "index" => "logs-nginx.access-prod",
                    "alias" => "logs",
                ],
            ],
        ),
    ],
]);

Ruby Elasticsearch Ruby Client

response = client.indices.update_aliases(
  body: {
    "actions": [
      {
        "remove": {
          "index": "logs-nginx.access-prod",
          "alias": "logs"
        }
      }
    ]
  }
)

Response

When using multiple actions, if some succeed and some fail, the API returns a list of per-action results. For example, if the alias logs-non-existing does not exist, the API returns a 404 error for the remove action.

{
  "acknowledged": true,
  "errors": true,
  "action_results": [
    {
      "action": {
        "type": "remove",
        "indices": [
          "logs-nginx.access-prod"
        ],
        "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": [
          "logs-nginx.access-default"
        ],
        "aliases": [
          "logs-non-existing"
        ]
      },
      "status": 200
    }
  ]
}

Request Console 1 / 7 languages

First, remove the index my-index-1 (which has the alias my-alias) and then add the index my-index-2 to the alias in a single request.

Console Kibana Dev Tools

POST _aliases
{
  "actions": [
    {
      "remove_index": {
        "index": "my-index-1"
      }
    },
    {
      "add": {
        "index": "my-index-2",
        "alias": "my-alias"
      }
    }
  ]
}

JavaScript Elasticsearch JavaScript Client

const response = await client.indices.updateAliases({
  actions: [
    {
      remove_index: {
        index: "my-index-1",
      },
    },
    {
      add: {
        index: "my-index-2",
        alias: "my-alias",
      },
    },
  ],
});

Python Elasticsearch Python Client

resp = client.indices.update_aliases(
    actions=[
        {
            "remove_index": {
                "index": "my-index-1"
            }
        },
        {
            "add": {
                "index": "my-index-2",
                "alias": "my-alias"
            }
        }
    ],
)

curl Shell

curl -X POST "$ELASTICSEARCH_URL/_aliases" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "actions": [
      {
        "remove_index": {
          "index": "my-index-1"
        }
      },
      {
        "add": {
          "index": "my-index-2",
          "alias": "my-alias"
        }
      }
    ]
  }'

C# Elasticsearch .NET Client

var response = await client.Indices
    .UpdateAliasesAsync(d1 => d1
        .Actions(d2 => d2
            .RemoveIndex(d3 => d3
                .Index("my-index-1")
            ), d2 => d2
            .Add(d3 => d3
                .Alias("my-alias")
                .Index("my-index-2")
            )
        )
    );

PHP Elasticsearch PHP Client

$resp = $client->indices()->updateAliases([
    "body" => [
        "actions" => array(
            [
                "remove_index" => [
                    "index" => "my-index-1",
                ],
            ],
            [
                "add" => [
                    "index" => "my-index-2",
                    "alias" => "my-alias",
                ],
            ],
        ),
    ],
]);

Ruby Elasticsearch Ruby Client

response = client.indices.update_aliases(
  body: {
    "actions": [
      {
        "remove_index": {
          "index": "my-index-1"
        }
      },
      {
        "add": {
          "index": "my-index-2",
          "alias": "my-alias"
        }
      }
    ]
  }
)

Response

When using multiple actions, if some succeed and some fail, the API returns a list of per-action results. For example, if the alias logs-non-existing does not exist, the API returns a 404 error for the remove action.

{
  "acknowledged": true,
  "errors": true,
  "action_results": [
    {
      "action": {
        "type": "remove",
        "indices": [
          "logs-nginx.access-prod"
        ],
        "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": [
          "logs-nginx.access-default"
        ],
        "aliases": [
          "logs-non-existing"
        ]
      },
      "status": 200
    }
  ]
}