Document versioning in Elasticsearch

Introduction

Document versioning helps keep track of changes to data in Elasticsearch. It prevents conflicts when multiple users update the same document.

When multiple users or systems update the same document at the same time.

To avoid overwriting changes accidentally in a shared database.

When you want to ensure updates happen only if the document is at a specific version.

To keep a simple history of document changes for consistency.

When building applications that require safe concurrent updates.

Syntax

Elasticsearch

PUT /index/_doc/document_id?version=version_number
{
  "field": "value"
}

The version parameter specifies the expected version of the document.

If the version does not match the current document version, Elasticsearch rejects the update to avoid conflicts.

Examples

This updates the document with ID 1 in the products index only if its current version is 3.

Elasticsearch

PUT /products/_doc/1?version=3
{
  "name": "Coffee Mug",
  "price": 12.99
}

You can check the current version of a document before updating it.

Elasticsearch

GET /products/_doc/1

# Response includes "_version" field showing current version

Another way to control updates is using sequence number and primary term for optimistic concurrency control.

Elasticsearch

POST /products/_update/1
{
  "doc": {"price": 14.99},
  "if_seq_no": 5,
  "if_primary_term": 1
}

Sample Program

This example shows creating a document, checking its version, updating it with the correct version, and then trying to update again with an old version which fails to prevent conflicts.

Elasticsearch

PUT /library/_doc/42
{
  "title": "Learn Elasticsearch",
  "author": "Jane Doe"
}

# Get the document to see its version
GET /library/_doc/42

# Update the document only if version is 1
PUT /library/_doc/42?version=1
{
  "title": "Learn Elasticsearch - Updated",
  "author": "Jane Doe"
}

# Try to update again with old version (1) - this will fail
PUT /library/_doc/42?version=1
{
  "title": "Another Update",
  "author": "Jane Doe"
}

Important Notes

Always check the current document version before updating to avoid conflicts.

Versioning is useful for optimistic concurrency control in distributed systems.

Using if_seq_no and if_primary_term is a more advanced and recommended way for concurrency control in Elasticsearch.

Summary

Document versioning helps avoid update conflicts in Elasticsearch.

Use the version parameter to update only if the document is at a specific version.

Check the document's current version before updating to keep data safe.