Elasticsearch / Intermediate: models, pipelines and relevance evidence / Lesson 11
Optimistic writes, aliases and reindex
Prevent lost edits and migrate a derived search index without confusing alias atomicity with complete data synchronization.
On this page
Lesson goals
- Explain sequence-number and primary-term preconditions.
- Plan a reconciled index replacement and alias switch.
A read-modify-write can overwrite another editor
Two curators read the same artifact, edit different fields locally and each submit a replacement document. Without concurrency control, the later replacement can erase the earlier edit. Elasticsearch exposes _seq_no and _primary_term so a write can require the version state observed by the reader. The application must retain both preconditions and define conflict behavior. A conflict is useful evidence that the edit is stale, not a reason to resend the same replacement indefinitely. Decide whether the user reloads, merges reviewed fields or abandons the operation. The search projection may also be read-only if the system of record owns edits.
Apply the observed state to the exact target
The body below is an artifact replacement for a hypothetical request with if_seq_no=12 and if_primary_term=3 in the query parameters. Those values are synthetic observations, not a universal correct pair. The server should accept only if the target document still satisfies the preconditions; otherwise it reports a version conflict. A partial update does not automatically solve every lost-business-intent problem, especially when scripts increment counters or depend on stale application decisions. Keep the exact target index and identifier with the observation so a migration cannot silently redirect a state token to another document history.
{"artifact_id":"art-101","title":"Restored bronze compass","status":"displayed"}Replacement body only. Preconditions belong to the request parameters and must come from the actual authorized read response.
Reindex is one phase of a migration
A corrected analyzer or field type often needs a new index with reviewed settings and mappings. Reindex copies source documents but is not an automatic continuous change stream, and it does not magically carry every desired destination setting. Create the destination contract deliberately and account for source changes during copying. Options include replay from a durable source, a controlled writer pause or a reviewed dual-write protocol with reconciliation. Each has consistency and failure consequences. Count equality alone is insufficient if identifiers or field values disagree; compare representative keys, failed items and query behavior as well.
An atomic alias update does not prove data parity
The alias action body removes museum-search from v1 and adds it to v2 in one aliases request. The metadata switch is atomic, but readers can still encounter semantically incomplete data if v2 was not reconciled. A write alias needs an explicit unambiguous write target, and filters or routing on aliases require their own reviewed semantics. Keep a compatible rollback plan, including what happens to writes accepted after the switch. Pointing back to an old index can lose those changes even though the alias command itself succeeds.
{"actions":[{"remove":{"index":"museum-artifacts-v1","alias":"museum-search"}},{"add":{"index":"museum-artifacts-v2","alias":"museum-search"}}]}Illustrative body for POST /_aliases after independent reconciliation. It is not executed and does not create or populate v2.
Verify writers and readers across the boundary
A rehearsal should include a stale edit conflict, a document updated during copying, a rejected destination item and a client using the old concrete index name. Verify that application configuration resolves the intended alias rather than bypassing it. Keep source checkpoints and migration phase records durable so interruption is recoverable. Security privileges also need to cover only the intended aliases and destinations; a broad wildcard introduced for migration should not become permanent runtime access. No reindex task, alias mutation or concurrent edit is run in this course, and no engine migration timing is claimed.
Common errors and fixes
version_conflict_engine_exception
- Why it happens
- The write preconditions no longer match the document state.
- How to fix it
- Reload and resolve the business edit instead of blindly replacing again.
- Prevent it next time
- Carry sequence number and primary term through editable workflows.
A new index misses edits made during copying
- Why it happens
- A one-time copy was treated as continuous synchronization.
- How to fix it
- Replay or reconcile source changes through the reviewed migration protocol.
- Prevent it next time
- Define a source checkpoint and writer handoff before copying.
Alias rollback loses recent updates
- Why it happens
- Writes accepted after the switch were absent from the old index.
- How to fix it
- Reconcile those writes before choosing a rollback target.
- Prevent it next time
- Review rollback data flow alongside the forward alias action.
Check your understanding
1. Why must if_seq_no and if_primary_term come from the actual read rather than a copied example?
Show worked solution
They identify the observed document history and leadership term. Arbitrary values cannot protect the userβs edit correctly. Keep them with index and identifier, handle a conflict as a stale-decision outcome, and avoid reusing them after rebuilding the document into a different index.
2. Does an atomic alias switch guarantee the new index contains every accepted source update?
Show worked solution
No. Atomicity concerns the alias metadata change. Data completeness depends on the copy, concurrent-change protocol and reconciliation. Verify keys, payloads, rejected items and writer routing before switching, then preserve a rollback plan that accounts for subsequent writes.
Key takeaways
- Optimistic conditions protect observed state, not arbitrary retries.
- A migration needs data synchronization as well as an atomic routing change.