How to manage index aliases in Elasticsearch

Index aliases provide a stable, application-facing name that can point to one or more indices, allowing zero-downtime switches during rollovers, reindexing, and index migrations without changing client configuration.

Aliases live in the Elasticsearch cluster state and are updated with the _aliases API. A single request can include multiple add and remove actions that are applied atomically, making alias swaps safe even under concurrent traffic.

Alias changes influence both reads and writes, so write routing must be handled carefully when an alias can match more than one index. Indexing through an alias requires either a single backing index or exactly one index marked as the write target with is_write_index, otherwise write requests can be rejected or routed incorrectly.

1. List existing aliases and their backing indices.

   $ curl -s "http://localhost:9200/_cat/aliases?v"
   alias        index        filter routing.index routing.search is_write_index
   logs-current logs-2024.12 -      -             -              true

   The _cat APIs are human-readable; add ?format=json for machine-readable output.

2. Add a temporary alias to the new index for validation and testing.

   $ curl -s -H "Content-Type: application/json" -X POST "http://localhost:9200/_aliases?pretty" -d '{
     "actions": [
       { "add": { "index": "logs-2025.01", "alias": "logs-next" } }
     ]
   }'
   {
     "acknowledged" : true
   }

   Using a separate alias keeps production traffic on logs-current while queries are tested against logs-next.

3. Switch the logs-current write alias from the old index to the new index.

   $ curl -s -H "Content-Type: application/json" -X POST "http://localhost:9200/_aliases?pretty" -d '{
     "actions": [
       { "remove": { "index": "logs-2024.12", "alias": "logs-current" } },
       { "add": { "index": "logs-2025.01", "alias": "logs-current", "is_write_index": true } }
     ]
   }'
   {
     "acknowledged" : true
   }

   Removing the wrong alias target can drop search coverage or route new writes into the wrong index; confirm the destination index is fully populated and mapped before the swap.

   Related: How to reindex data in Elasticsearch

4. Fetch the alias definition to confirm the final target and is_write_index flag.

   $ curl -s "http://localhost:9200/_alias/logs-current?pretty"
   {
     "logs-2025.01" : {
       "aliases" : {
         "logs-current" : {
           "is_write_index" : true
         }
       }
     }
   }

   When security is enabled, replace http://localhost:9200 with the correct endpoint and add authentication options (for example, -u user:pass and --cacert ca.crt).

5. Remove the temporary alias after validation is complete.

   $ curl -s -H "Content-Type: application/json" -X POST "http://localhost:9200/_aliases?pretty" -d '{
     "actions": [
       { "remove": { "index": "logs-2025.01", "alias": "logs-next" } }
     ]
   }'
   {
     "acknowledged" : true
   }