Spring Data Elasticsearch mapping rollout: build a new index, then move the read alias

Do not mutate a live search contract blindly

A catalog search field changes from analyzed text to an exact keyword. Existing index data and queries still use the old mapping. Create catalog-v5 with the new mapping, backfill documents from the source of record, and compare counts and representative queries before moving the catalog-read alias. The Spring entity can point at that alias while index creation is owned by a deployment step. This keeps index lifecycle out of ordinary application startup.

Account for writes during the backfill

If writes continue while catalog-v5 builds, track source versions and replay changes until the new index catches up. Switch the alias only when the index reaches a recorded checkpoint. After the switch, keep catalog-v4 long enough for rollback and old clients, then retire it under a separate change. Source-version checks prevent an old event from reversing the backfill. Contract gates are the relational equivalent.

Verify the alias, not just the new index

Query catalog-v5 directly, then query catalog-read before and after the alias switch. Exercise a rollback and confirm the application does not auto-create an empty index under the alias name. The annotation below declares an alias target; index creation, backfill and alias update are controlled operations, not performed by this Java class.

Implementation sketch

@Document(indexName = "catalog-read", createIndex = false)
class CatalogSearchDocument {
    @Id String productId;
    @Field(type = FieldType.Keyword) String sku;
    @Field(type = FieldType.Text) String description;
}

Cost and verification

Dual indices temporarily double index storage and backfill I/O. That cost buys a measured cutover and rollback path instead of an unreviewed mapping change on live traffic.

Common Mistakes

• Do not let application startup silently create an empty replacement index.
• Do not switch the read alias before the backfill catches up with live writes.
• Do not delete the old index in the same operation that changes the alias.

Read next

Spring Data Elasticsearch write versus search: refresh is the visibility boundary, Spring Data Elasticsearch sequence conflict: do not overwrite a newer projection, Spring Data MongoDB change stream: resume token and idempotent projection, Spring database contract phase: reject old writers only after backfill.