Catalog My learning Blog
Elasticsearch Tutorial: How Full-Text Search Works · Phase 3 · Lesson 19 · 3 min read

Elasticsearch Aliases and Zero-Downtime Reindexing

On this page
  1. Why you can't change a field's mapping
  2. Index aliases
  3. Zero-downtime reindexing: reindex and swap the alias
  4. Index templates and component templates
  5. Check yourself

Why you can't change a field's mapping

sku was mapped as text by mistake. Exact lookups fail:

HTTP
GET /catalog/_search
{ "query": { "term": { "sku": "AB-1234" } } }
Code
total 0

The 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.

HTTP
POST /_aliases
{ "actions": [ { "add": { "index": "catalog_v1", "alias": "catalog" } } ] }

Zero-downtime reindexing: reindex and swap the alias

1. Create the corrected index:

HTTP
PUT /catalog_v2
{ "mappings": { "properties": {
    "sku":  { "type": "keyword" },
    "name": { "type": "text", "analyzer": "english" } } } }

2. Copy the documents:

HTTP
POST /_reindex?wait_for_completion=true
{ "source": { "index": "catalog_v1" }, "dest": { "index": "catalog_v2" } }
Code
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:

HTTP
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:

Code
total 1
  1    0.288   AB-1234

Keep catalog_v1 briefly for rollback (swap back), then delete it.

Clients query an alias; a corrected index is built and filled by reindexing, then the alias moves to it in one atomic action, and the old index is kept briefly for rollback.
Clients query an alias; a corrected index is built and filled by reindexing, then the alias moves to it in one atomic action, and the old index is kept briefly for rollback.

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:

HTTP
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:

Code
.ds-logs-app-checkout-2026.10.11-000001 policy= logs-policy phase= hot

Check 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.