Read/Write Aliases, Filters, Routing, is_write_index, and Atomic Alias Updates

Learning outcomes

AtlasMart wants to replace the physical product index without changing the application endpoint. The application should continue reading from atlasmart-products-read and writing to atlasmart-products-write while operations can move those logical names from v1 to v2. An index alias is cluster metadata that resolves a logical name to one or more concrete indices. It is not a copied dataset, not a DNS record, and not a backup.

1. Build the physical index before introducing indirection

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"}

The concrete index remains the storage object. The alias is a pointer in cluster metadata. Keeping those concepts separate is essential because operations such as deleting a physical index or reindexing into v2 act on the concrete index even if the application normally talks only to an alias.

2. Create explicit read and write aliases

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 _alias/atlasmart-products-write

For a write alias that can eventually reference multiple indices, explicitly mark the write index. OpenSearch and Elasticsearch both reject ambiguous writes when an alias resolves to multiple indices and no write target is selected. Explicitness also makes operational intent reviewable before a migration.

3. Filters and routing change semantics, not just convenience

POST _aliases
{
  "actions":[
    {"add":{
      "index":"atlasmart-products-v1",
      "alias":"atlasmart-products-audio",
      "filter":{"term":{"category":"audio"}}
    }}
  ]
}

GET atlasmart-products-audio/_search
{
  "query":{"match_all":{}}
}

A filtered alias constrains searches through the alias, but it is not a substitute for a complete tenant-authorization design. Access to the underlying concrete index can bypass that logical filter unless security privileges prevent it. Alias routing similarly influences shard selection; it can improve locality for a known access pattern but can also create hot shards or missing results when the application supplies inconsistent routing.

POST _aliases
{
  "actions":[
    {"add":{
      "index":"atlasmart-products-v1",
      "alias":"atlasmart-products-tenant-a",
      "filter":{"term":{"tenant_id":"tenant-a"}},
      "index_routing":"tenant-a",
      "search_routing":"tenant-a"
    }}
  ]
}

Only use this form when documents were indexed with compatible routing. A filter cannot recover a document that was routed to a shard excluded by the alias search routing.

4. Prepare v2, then switch both aliases in one request

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 _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}}
  ]
}

GET _alias/atlasmart-products-read
GET _alias/atlasmart-products-write

This is safe only after v2 is complete enough for the chosen migration strategy. An atomic pointer switch cannot repair writes that landed only in v1 while the reindex was still copying. Later lessons make that change-data window explicit.

5. Deliberately wrong approach: two independent alias calls

A common runbook says “remove the old alias, verify, then add the new alias.” The verification pause creates downtime because the application name resolves to nothing. A second failure mode is adding v2 first and removing v1 later while both are write candidates without is_write_index. Repair by validating v2 first and sending all intended alias changes in one _aliases action set.

BEFORE
GET _alias/atlasmart-products-read
GET _alias/atlasmart-products-write
GET atlasmart-products-read/_count
GET atlasmart-products-read/_search?q=sku:P-1001

CUTOVER
POST _aliases  # one multi-action request

AFTER
GET _alias/atlasmart-products-read
GET _alias/atlasmart-products-write
GET atlasmart-products-read/_count
GET atlasmart-products-read/_search?q=sku:P-1001
POST atlasmart-products-write/_doc/P-1999?refresh=true
{"sku":"P-1999","name":"Cutover Smoke Product","category":"test","price":1.00,"available":true,"updated_at":"2026-09-11T08:00:00Z","schema_version":"v2"}

6. Rollback is another atomic alias change

If the application fails smoke tests and v1 still contains a compatible, sufficiently current copy, reverse the alias actions. If writes have already advanced only in v2, pointing reads back to v1 can lose those writes from the application view. This is why rollback design must be tied to write coordination, not written as a ceremonial final step.

Production judgment

Use aliases as deployment indirection, not as a substitute for data synchronization. Record the exact pre-cutover alias state, source/destination counts, high-value search fixtures, current write strategy and rollback deadline. Measure the cluster-state publication time and application p95/p99 around cutover, but do not invent a universal “safe” timeout. Access to alias-management APIs should be tightly controlled because a single metadata change can redirect tenant reads and writes.

Summary and next step

You can now separate a stable application endpoint from concrete indices and switch targets atomically. Next, rollover applies the same write-index concept repeatedly as an index grows or as a data stream creates a new backing index.

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.