How do you change an Elasticsearch index mapping with zero downtime while writes keep arriving?

## The precondition This whole procedure is only available if **clients address an alias**, not `products-v1`. If they do not, step zero is adding the alias to the existing index and shipping a client change — which is precisely the coordinated redeploy the alias exists to avoid, and why the convention is established on day one. ## Step 1 — build the new index Create `products-v2` explicitly with the corrected mapping and settings. `_reindex` copies **documents only**: it does not carry mappings, settings, or aliases across. Deriving the new index from a versioned index template keeps the mapping under code review. A common optimisation is to create it with `number_of_replicas: 0` and a relaxed `refresh_interval` for the bulk load, then restore both before the swap, so the copy is not paying for replication and constant refreshes while nobody is querying it. ## Step 2 — understand what reindex does and does not see `_reindex` scrolls a **point-in-time view of the source captured when the task begins**. Documents created, updated or deleted in the source afterwards are invisible to it. On a live index this is the single most important fact in the whole migration: when the reindex finishes, v2 is already stale by however long the reindex took. Run it asynchronously (`wait_for_completion=false`), sliced, and throttled — see the operational detail in its own right — and record the task id. ## Step 3 — close the gap Two strategies, often combined. **Dual write.** The application writes every change to both v1 and v2 for the duration. From the moment dual-writing starts, v2 never falls behind for new traffic; the reindex only has to carry the historical backlog. The hazard is ordering: a document dual-written at 10:00 could be overwritten at 10:05 by the reindex copying the *older* snapshot version. Guard against it with `"op_type": "create"` on the destination, which makes the reindex refuse to overwrite an existing document id, plus `conflicts: proceed` so those refusals do not abort the job. Alternatively, use external versioning so the higher version always wins. **Catch-up passes.** If dual writing is not practical, run further reindexes filtered on `updated_at >= <start of previous pass minus a safety margin>`. Each pass is smaller than the last. When the residual window is a few seconds, you can either accept it (if reads tolerate brief staleness) or flip the *write* alias first, drain, run one final catch-up, then flip the read alias. **Deletes are the hard part.** A timestamp catch-up finds creates and updates but cannot see a document that was deleted from v1 after the snapshot — it leaves a ghost in v2. Handle it with soft deletes (a `deleted` flag the catch-up query can see), by having the dual-write path replicate deletes, or by reconciling ids after the fact. Candidates who raise deletes unprompted are showing they have actually run one of these. ## Step 4 — verify before you swap - Compare `_count` on both indices, accounting for documents deliberately filtered out. - Diff a random sample of documents by id. - Run production-shaped queries **directly against `products-v2`** and compare hits and ordering with v1. A mapping change frequently changes relevance; discovering that after the swap is the classic self-inflicted incident. - Restore `number_of_replicas` and let the new replicas allocate before taking traffic, or the first minute of production load lands on unreplicated shards. ## Step 5 — the atomic swap ``` POST /_aliases { "actions": [ { "remove": { "index": "products-v1", "alias": "products" } }, { "add": { "index": "products-v2", "alias": "products" } } ] } ``` One cluster-state update, no gap. If reads and writes use separate aliases you can stage them: flip reads first to validate under real query load while writes still land in both, then flip writes. ## Step 6 — keep the exit open Do not delete v1 in the swap. Leave it for a rollback window — reverting is another single `_aliases` call, which is the cheapest incident response available. If dual writing continued through the swap, v1 stays current and rollback is lossless. Once satisfied, stop dual writes and delete v1. ## What good answers include Snapshot semantics, the `op_type: create` guard, deletes, verification against the new index before the swap, and an explicit rollback plan. What weak answers do: reindex, swap, delete the old index, and assume the counts matched.