Execute a Mapping Migration with Dual Read/Write or Alias Cutover, Validation, and Rollback Evidence

Learning outcomes

AtlasMart now has every primitive needed for a safe migration: versioned mappings/templates, aliases, throttled reindex, task observation and reversible cutover. The remaining problem is coordination. A migration is correct only if the destination contains the intended historical documents and every write that occurred during the copy window.

1. Define the change and the write window before touching data

Document the maximum acceptable stale window. If the application cannot stop writes, a plain one-pass reindex is insufficient because writes after the source snapshot may never reach v2.

2. Establish baseline aliases and evidence

PUT atlasmart-products-v1
{
  "settings":{"number_of_shards":1,"number_of_replicas":0},
  "mappings":{"dynamic":"strict","properties":{
    "sku":{"type":"keyword"},
    "name":{"type":"text","fields":{"keyword":{"type":"keyword"}}},
    "category":{"type":"keyword"},
    "price":{"type":"scaled_float","scaling_factor":100},
    "available":{"type":"boolean"},
    "updated_at":{"type":"date"}
  }}
}

POST _bulk?refresh=true
{"index":{"_index":"atlasmart-products-v1","_id":"P-1001"}}
{"sku":"P-1001","name":"Wireless Noise Cancelling Headphones","category":"audio","price":199.99,"available":true,"updated_at":"2026-09-11T07:00:00Z"}
{"index":{"_index":"atlasmart-products-v1","_id":"P-1002"}}
{"sku":"P-1002","name":"USB-C Travel Charger","category":"power","price":49.95,"available":true,"updated_at":"2026-09-11T07:01:00Z"}
{"index":{"_index":"atlasmart-products-v1","_id":"P-1003"}}
{"sku":"P-1003","name":"Ergonomic Mechanical Keyboard","category":"input","price":129.00,"available":false,"updated_at":"2026-09-11T07:02:00Z"}


POST _aliases
{
  "actions":[
    {"add":{"index":"atlasmart-products-v1","alias":"atlasmart-products-read"}},
    {"add":{"index":"atlasmart-products-v1","alias":"atlasmart-products-write","is_write_index":true}}
  ]
}

GET _alias/atlasmart-products-read
GET atlasmart-products-read/_count

Record source count, representative IDs, aggregations and judged search fixtures. These become the comparison set. A screenshot alone is weak evidence; save machine-readable responses or a migration report in your change record.

3. Prepare v2 and run the historical copy

PUT atlasmart-products-v2
{
  "settings":{"number_of_shards":1,"number_of_replicas":0},
  "mappings":{"dynamic":"strict","properties":{
    "sku":{"type":"keyword"},
    "name":{"type":"text","analyzer":"standard","fields":{"keyword":{"type":"keyword"}}},
    "category":{"type":"keyword"},
    "price":{"type":"scaled_float","scaling_factor":100},
    "available":{"type":"boolean"},
    "updated_at":{"type":"date"},
    "schema_version":{"type":"keyword"}
  }}
}

POST _reindex?wait_for_completion=false&requests_per_second=25
{
  "source":{"index":"atlasmart-products-v1"},
  "dest":{"index":"atlasmart-products-v2"},
  "script":{"lang":"painless","source":"ctx._source.schema_version='v2'"}
}

GET _tasks?actions=*reindex*&detailed=true

During this phase, production writes still target v1 under the lab’s plan. In a real dual-write design, every write must be idempotently applied to both versions and error handling must detect one-sided success. In an event-replay design, persist a checkpoint that identifies exactly which changes occurred after the reindex snapshot.

4. Enter the controlled cutover window

1. Stop/queue new product writes at the application boundary.
2. Wait for the historical reindex task to complete.
3. Replay or copy any writes after the reindex snapshot if your strategy permits them.
4. Compare source/destination counts and critical IDs.
5. Run aggregation checks and judged relevance fixtures.
6. POST _aliases once to move read + write aliases to v2.
7. Resume writes.
8. Execute read and write smoke tests through the aliases.

POST _aliases
{
  "actions":[
    {"remove":{"index":"atlasmart-products-v1","alias":"atlasmart-products-read"}},
    {"remove":{"index":"atlasmart-products-v1","alias":"atlasmart-products-write"}},
    {"add":{"index":"atlasmart-products-v2","alias":"atlasmart-products-read"}},
    {"add":{"index":"atlasmart-products-v2","alias":"atlasmart-products-write","is_write_index":true}}
  ]
}

5. Validate through the same interfaces the application uses

GET _alias/atlasmart-products-read
GET atlasmart-products-read/_count
GET atlasmart-products-read/_search
{
  "query":{"match":{"name":"wireless headphones"}}
}

POST atlasmart-products-write/_doc/P-1999?refresh=true
{
  "sku":"P-1999",
  "name":"Migration Smoke Product",
  "category":"test",
  "price":1.00,
  "available":true,
  "updated_at":"2026-09-11T09:00:00Z",
  "schema_version":"v2"
}

GET atlasmart-products-read/_doc/P-1999

Also compare business aggregates and authorization paths. If the mapping/analyzer changed, run the Chapter 07 relevance regression set rather than assuming equal _score values. Record application p95/p99 during the cutover period and the cluster’s CPU/JVM/disk/search rejection behavior.

6. Exercise rollback, do not merely document it

POST _aliases
{
  "actions":[
    {"remove":{"index":"atlasmart-products-v2","alias":"atlasmart-products-read"}},
    {"remove":{"index":"atlasmart-products-v2","alias":"atlasmart-products-write"}},
    {"add":{"index":"atlasmart-products-v1","alias":"atlasmart-products-read"}},
    {"add":{"index":"atlasmart-products-v1","alias":"atlasmart-products-write","is_write_index":true}}
  ]
}

This rollback is only data-safe if v1 contains every write that must remain visible. The smoke product written after cutover exists only in v2 in this simple lab, so blindly rolling back would hide it. That concrete edge case is the reason a production rollback plan needs reverse replay, dual writing, or a rule that writes remain frozen until the acceptance window closes.

7. Deliberately wrong approach: delete v1 immediately after green smoke tests

A five-minute smoke test cannot prove long-tail queries, tenant permissions, delayed consumers, snapshots or operational behavior. Deleting v1 also removes the simplest rollback target. Repair by retaining v1 for a defined window, making it read-only if appropriate, taking/validating independent snapshots, monitoring v2, and retiring v1 only through a separate approved step.

8. Migration evidence manifest

baseline versions: Elasticsearch 9.5.3 / OpenSearch 3.8.0
source mapping/settings captured: PASS
destination mapping/settings reviewed: PASS
write-coordination strategy: DOCUMENTED
source count / destination count: RECORDED
stable-ID sample comparison: PASS
critical aggregation comparison: PASS
relevance regression set: PASS
reindex task failures/conflicts: RECORDED
requests_per_second + slices: RECORDED
p95/p99 search/index latency during migration: MEASURED
CPU/JVM/disk/merge headroom: MEASURED
alias state before/after: CAPTURED
read smoke test: PASS
write smoke test: PASS
rollback drill: PASS
post-cutover write reconciliation: PASS
snapshot/restore evidence: PASS
source retirement date/owner: APPROVED

Replace every placeholder such as MEASURED or RECORDED with actual evidence before production approval. A migration report is part of the system’s operational correctness, not optional paperwork.

Production judgment

Zero downtime is not just “no HTTP 503 during alias switch.” It means the application remains available while data correctness, tenant isolation, acceptable freshness and recoverability are preserved. Choose the simplest write-coordination mechanism that meets those guarantees. For small systems that may be a short freeze; for high-throughput systems it can require durable event replay or dual-write infrastructure. Validate both Elasticsearch and OpenSearch behavior on the exact target version and managed-service environment before executing the runbook.

Chapter 12 summary and bridge to Chapter 13

You can now change physical indices without tying application endpoints to those indices, control copy/mutation tasks, and prove cutover/rollback with evidence. Chapter 13 turns to the topology beneath those operations: shard count, routing, allocation, awareness, recovery and the capacity headroom required for migrations and failures.

Authoritative references

• Elastic aliases — Alias filters, routing, write-index behavior and alias management.
• Elastic update aliases API — Multi-action alias changes through POST /_aliases.
• Elastic rollover API — Manual rollover for data streams and index aliases; conditions and write-index semantics.
• Elastic reindex API — Reindex requirements, throttling, slicing, remote sources and destination preparation.
• Elastic update by query — Snapshot semantics, conflicts, slicing, throttling and task monitoring.
• Elastic task API — Task progress and status for long-running operations.
• OpenSearch aliases API — Atomic alias action sets, filters, routing and write-index behavior.
• OpenSearch rollover API — Rollover for aliases/data streams with age, docs and size conditions.
• OpenSearch reindex API — Local/remote reindex, slicing, throttling, background tasks and validation fields.
• OpenSearch update by query — Snapshot-based update-by-query, conflicts and partial completion semantics.
• OpenSearch delete by query — Snapshot-based deletion, conflicts and non-rollback behavior.
• OpenSearch cancel tasks — Cancellation behavior and cancellable task checks.