Document versioning in Elasticsearch - Step-by-Step Execution

Concept Flow - Document versioning

Start: Document Indexed

↓

Assign Version = 1

↓

Update Request Received

↓

Check Version in Request

↓

Update

↓

Increment Version

↓

Save Document

↓

End

When a document is first indexed, it gets version 1. On updates, Elasticsearch checks the version to avoid conflicts. If versions match, it updates and increments the version. If not, it rejects the update.

Execution Sample

Elasticsearch

PUT /my_index/_doc/1
{
  "name": "Alice"
}

PUT /my_index/_doc/1?if_seq_no=0&if_primary_term=1
{
  "name": "Alice Updated"
}

This code indexes a document with id 1, then updates it only if the version matches to avoid conflicts.

Execution Table

Step	Action	Version Before	Version Check	Result	Version After
1	Index new document id=1	N/A	N/A	Document created	1
2	Update document id=1 with if_seq_no=0 & if_primary_term=1	1	Matches current version	Update accepted	2
3	Update document id=1 with if_seq_no=0 & if_primary_term=1 again	2	Does not match current version	Update rejected	2

💡 Update rejected at step 3 because version check failed (conflict detected).

Variable Tracker

Variable	Start	After Step 1	After Step 2	After Step 3
Document Version	N/A	1	2	2

Key Moments - 2 Insights

Why does the update get rejected at step 3 even though the same version check is used?

Because after step 2, the document version incremented to 2. The update at step 3 still uses the old version (seq_no=0, primary_term=1), so the version check fails, causing rejection as shown in execution_table row 3.

What happens to the version number when a document is first indexed?

At step 1, the document is created with version 1, as shown in execution_table row 1 and variable_tracker.

Visual Quiz - 3 Questions

Look at the execution_table, what is the document version after step 2?

A 1

B 2

C 3

D 0

💡 Hint

Check the 'Version After' column in execution_table row 2.

At which step does the update get rejected due to version conflict?

A Step 1

B Step 2

C Step 3

D No rejection occurs

💡 Hint

Look at the 'Result' column in execution_table row 3.

If the update at step 3 used the correct current version, what would happen?

A Update would be accepted and version incremented

B Update would still be rejected

C Document would be deleted

D No change in version

💡 Hint

Refer to the behavior shown in execution_table row 2 where version matched and update succeeded.

Concept Snapshot

Document versioning in Elasticsearch:
- New documents start at version 1
- Updates require matching version (seq_no & primary_term)
- If versions match, update succeeds and version increments
- If versions mismatch, update is rejected to avoid conflicts
- Helps keep data consistent in concurrent environments

Full Transcript

Document versioning in Elasticsearch helps keep data consistent. When you add a new document, it starts with version 1. When you update it, Elasticsearch checks if your update matches the current version. If it does, the update happens and the version number goes up by one. If it doesn't match, the update is rejected to avoid overwriting changes made by others. This way, Elasticsearch prevents conflicts and keeps your data safe.

Practice

1. What is the main purpose of document versioning in Elasticsearch?

easy

A. To compress documents for storage efficiency

B. To prevent update conflicts by ensuring updates apply only to the expected document version

C. To increase the speed of document retrieval

D. To create backups of documents automatically

Solution

1. Step 1: Understand document versioning concept

   Document versioning is used to avoid conflicts when multiple updates happen simultaneously.

2. Step 2: Identify the main purpose

   It ensures updates only apply if the document is at the expected version, preventing overwriting newer changes.

3. Final Answer:

   To prevent update conflicts by ensuring updates apply only to the expected document version -> Option B

4. Quick Check:

   Versioning prevents conflicts = C [OK]

Hint: Versioning avoids conflicting updates by checking document version [OK]

Common Mistakes:

• Thinking versioning speeds up retrieval
• Confusing versioning with backup creation
• Assuming versioning compresses data

2. Which of the following is the correct way to specify a version when updating a document in Elasticsearch?

easy

A. POST /index/_update/1?version=3 { "doc": {"field": "value"} }

B. POST /index/_update/1 { "doc": {"field": "value"}, "version_number": 3 }

C. POST /index/_update/1 { "doc": {"field": "value"}, "ver": 3 }

D. POST /index/_update/1 { "doc": {"field": "value"}, "version": 3 }

Solution

1. Step 1: Recall Elasticsearch update syntax with version

   The version parameter is passed as a query parameter, not inside the JSON body.

2. Step 2: Identify correct syntax

   POST /index/_update/1?version=3 { "doc": {"field": "value"} } uses ?version=3 in the URL, which is the correct way to specify version for update.

3. Final Answer:

   POST /index/_update/1?version=3 { "doc": {"field": "value"} } -> Option A

4. Quick Check:

   Version is a query parameter, not in body [OK]

Hint: Use ?version=number in URL, not inside JSON body [OK]

Common Mistakes:

• Putting version inside JSON body
• Using wrong parameter names like ver or version_number
• Omitting the version parameter

3. Given the following update request, what will happen if the current document version is 5?

POST /myindex/_update/42?version=4
{
  "doc": {"status": "active"}
}

medium

A. The update will succeed and document version will become 5

B. The update will succeed but version will remain 4

C. The update will fail due to version conflict

D. The update will create a new document with version 4

Solution

1. Step 1: Check the version parameter against current document version

   The update request specifies version=4 but current version is 5.

2. Step 2: Understand version conflict behavior

   Elasticsearch rejects updates if the version does not match the current document version to avoid conflicts.

3. Final Answer:

   The update will fail due to version conflict -> Option C

4. Quick Check:

   Version mismatch causes update failure [OK]

Hint: Update only succeeds if version matches current document version [OK]

Common Mistakes:

• Assuming update succeeds despite version mismatch
• Thinking version resets after update
• Confusing version with document ID

4. You wrote this update request but it always fails with a version conflict error:

POST /products/_update/10?version=2
{
  "doc": {"price": 19.99}
}

What is the most likely cause?

medium

A. The update syntax is incorrect

B. The document with ID 10 does not exist

C. The field name 'price' is invalid

D. The current document version is not 2

Solution

1. Step 1: Understand version conflict error meaning

   Version conflict means the version specified does not match the document's current version.

2. Step 2: Check other options

   Document existence or field name errors cause different errors; syntax is correct here.

3. Final Answer:

   The current document version is not 2 -> Option D

4. Quick Check:

   Version conflict means version mismatch [OK]

Hint: Version conflict means your version number is outdated [OK]

Common Mistakes:

• Assuming document absence causes version conflict
• Blaming field names for version errors
• Ignoring correct syntax

5. You want to update a document only if it has not been changed since you last read it. Which approach correctly uses document versioning to achieve this?

hard

A. Fetch the document, note its version, then update using that version parameter

B. Update the document without specifying any version parameter

C. Use the document ID as the version parameter in the update request

D. Delete the document first, then create a new one with the updated data

Solution

1. Step 1: Understand optimistic concurrency control

   You must check the document's current version before updating to avoid overwriting changes.

2. Step 2: Apply versioning correctly

   Fetch the document, get its version, then update specifying that version to ensure no changes happened in between.

3. Final Answer:

   Fetch the document, note its version, then update using that version parameter -> Option A

4. Quick Check:

   Use version to update only if unchanged [OK]

Hint: Always update with the version you last read to avoid conflicts [OK]

Common Mistakes:

• Updating without version check causes silent overwrites
• Using document ID as version parameter
• Deleting instead of updating