Elasticsearch Aliases and Zero-Downtime Reindexing
On this page
Why you can't change a field's mapping
sku was mapped as text by mistake. Exact lookups fail:
GET /catalog/_search
{ "query": { "term": { "sku": "AB-1234" } } }total 0The standard analyzer split AB-1234 into ab and 1234. Changing a field's type requires a new index. If clients query an index by name, that means a coordinated change everywhere. With an alias, it doesn't.
Index aliases
An alias is a name that points to one or more indices. Clients use the alias; you move it.
POST /_aliases
{ "actions": [ { "add": { "index": "catalog_v1", "alias": "catalog" } } ] }Zero-downtime reindexing: reindex and swap the alias
1. Create the corrected index:
PUT /catalog_v2
{ "mappings": { "properties": {
"sku": { "type": "keyword" },
"name": { "type": "text", "analyzer": "english" } } } }2. Copy the documents:
POST /_reindex?wait_for_completion=true
{ "source": { "index": "catalog_v1" }, "dest": { "index": "catalog_v2" } }reindexed 1 created 1 failures []For large indices, run it asynchronously (wait_for_completion=false, then follow the task), use slices: "auto" for parallelism, and set refresh_interval: -1 and zero replicas on the target during the copy.
3. Swap the alias atomically, removing and adding in one request so there's no moment without an index:
POST /_aliases
{ "actions": [
{ "remove": { "index": "catalog_v1", "alias": "catalog" } },
{ "add": { "index": "catalog_v2", "alias": "catalog" } } ] }The same query through the alias now works, with no client change:
total 1
1 0.288 AB-1234Keep catalog_v1 briefly for rollback (swap back), then delete it.
Writes during the reindex: documents changed after the copy started are missing from v2. Either pause writes, have the application write to both indices during the switch, or re-run the copy for documents updated since the start (filter on an updated_at field).
Index templates and component templates
Indices created over time (logs, daily events, data streams) get settings and mappings from index templates, matched by name pattern:
PUT /_index_template/logs-app
{
"index_patterns": ["logs-app-*"],
"priority": 200,
"data_stream": {},
"template": {
"settings": { "index.lifecycle.name": "logs-policy" },
"mappings": { "properties": {
"@timestamp": { "type": "date" }, "message": { "type": "text" }, "level": { "type": "keyword" } } }
}
}A trap found in testing: without the priority line, writing to logs-app-checkout created a data stream governed by Elasticsearch's built-in logs lifecycle policy, not this template's. The built-in logs template matches logs-*-* with priority 100, beating the custom template's default priority of 0. With "priority": 200, the right policy applied:
.ds-logs-app-checkout-2026.10.11-000001 policy= logs-policy phase= hotCheck GET /_index_template/logs before naming indices logs-*-*, metrics-*-* or traces-*-*. Share common settings across templates with component templates.
Check yourself
The alias can be moved to a new index atomically, so reindexing for a mapping change needs no client changes.
Actions in one _aliases request are applied atomically, so the alias always points to exactly one index. Two separate requests leave a moment with no index or two indices behind the alias, and queries during it fail or return duplicates.
A built-in template matching logs-*-* had a higher priority than the custom template's default of 0, and only the highest-priority matching template applies. Raising the custom template's priority, such as to 200, fixed it.
Reusable building blocks of settings and mappings, like a common timestamp mapping or shard settings, that several index templates compose. A change made once applies to every template using it, avoiding copy-paste drift.
Write to both the old and new indices while the reindex runs, or record changes made since it started and replay them, then swap the alias. Reads continue against the old index the whole time.