Partial updates in Elasticsearch - Deep Dive

Overview - Partial updates

What is it?

Partial updates in Elasticsearch allow you to change only specific fields of a document without sending the entire document again. Instead of replacing the whole document, you send just the parts you want to change. This saves time and resources, especially when documents are large or frequently updated. Elasticsearch applies these changes efficiently and keeps the rest of the document intact.

Why it matters

Without partial updates, every time you want to change something in a document, you would have to send the whole document again. This wastes bandwidth and processing power, making updates slower and more costly. Partial updates make it easy to keep data fresh and accurate in real time, which is crucial for search engines, analytics, and apps that rely on fast data changes.

Where it fits

Before learning partial updates, you should understand how Elasticsearch stores and retrieves documents. After mastering partial updates, you can explore advanced update features like scripted updates, optimistic concurrency control, and bulk updates to handle large-scale data changes efficiently.

Mental Model

Core Idea

Partial updates let you send only the changes to a document, not the whole document, making updates faster and lighter.

Think of it like...

Imagine you have a big notebook with many pages. Instead of rewriting the entire notebook when you want to fix a typo on one page, you just correct that single page and keep the rest untouched.

┌─────────────────────────────┐
│       Elasticsearch Index    │
├─────────────┬───────────────┤
│ Document ID │ Document Data │
├─────────────┼───────────────┤
│ 1           │ {"name": "Alice", "age": 30, "city": "NY"} │
└─────────────┴───────────────┘

Update Request:
{
  "doc": {"age": 31}
}

Result:
Document 1 becomes {"name": "Alice", "age": 31, "city": "NY"}

Build-Up - 7 Steps

1

Foundation

What is a document update

Concept: Understanding how documents are stored and updated in Elasticsearch.

In Elasticsearch, data is stored as documents in an index. Each document is like a JSON object with fields and values. When you update a document, you replace the entire document by default. This means sending the whole JSON again, even if you want to change just one field.

Result

You learn that updating a document fully can be inefficient if only small changes are needed.

Knowing that full document replacement is the default helps you appreciate why partial updates are useful.

2

Foundation

Basics of partial update syntax

Concept: How to write a partial update request in Elasticsearch.

To update only some fields, you use the _update API with a 'doc' field containing just the fields to change. For example, to change the 'age' field, you send: { "doc": {"age": 31} } Elasticsearch merges this with the existing document.

Result

Only the 'age' field changes; other fields stay the same.

Partial update syntax is simple and lets you focus on just the data you want to change.

3

Intermediate

How Elasticsearch applies partial updates

🤔Before reading on: do you think Elasticsearch modifies the document directly on disk or creates a new version? Commit to your answer.

Concept: Understanding the internal process Elasticsearch uses to apply partial updates.

Elasticsearch does not change documents directly on disk. Instead, it fetches the current document, applies the partial changes in memory, and then indexes a new version of the document. The old version is marked as deleted but still kept until segment merging happens.

Result

Partial updates create a new document version behind the scenes, ensuring data consistency.

Knowing this helps explain why partial updates are fast but still safe and consistent.

4

Intermediate

Using scripts for complex partial updates

🤔Before reading on: do you think partial updates can only set values, or can they also perform calculations? Commit to your answer.

Concept: Introducing scripted updates to modify fields based on logic or calculations.

Sometimes you want to update a field based on its current value, like incrementing a counter. Elasticsearch lets you use scripts in the update request: { "script": "ctx._source.counter += params.count", "params": {"count": 1} } This runs code to change the document dynamically.

Result

Fields can be updated with calculations or conditions, not just fixed values.

Scripts make partial updates powerful and flexible for real-world needs.

5

Intermediate

Handling conflicts with optimistic concurrency

🤔Before reading on: do you think partial updates always succeed, or can they fail due to concurrent changes? Commit to your answer.

Concept: How Elasticsearch prevents lost updates when multiple clients update the same document.

If two clients update the same document at once, one update might overwrite the other. Elasticsearch uses optimistic concurrency control with version numbers or sequence numbers. You can specify a version or use 'if_seq_no' and 'if_primary_term' to ensure your update applies only if the document hasn't changed since you read it.

Result

Partial updates can safely handle concurrent changes without data loss.

Understanding concurrency control prevents subtle bugs in multi-user environments.

6

Advanced

Performance impact of partial updates

🤔Before reading on: do you think partial updates are always faster than full updates? Commit to your answer.

Concept: Exploring when partial updates improve performance and when they might not.

Partial updates reduce network load by sending less data. However, because Elasticsearch creates a new document version internally, the disk and CPU cost is similar to full updates. For very small changes, partial updates are efficient, but for large frequent updates, bulk operations or reindexing might be better.

Result

Partial updates optimize network usage but have similar storage costs as full updates.

Knowing the tradeoffs helps choose the right update strategy for your workload.

7

Expert

Internal versioning and update retries

🤔Before reading on: do you think Elasticsearch retries partial updates automatically on version conflicts? Commit to your answer.

Concept: Deep dive into how Elasticsearch manages versions and retries updates internally.

When a partial update hits a version conflict, Elasticsearch can retry the update automatically a few times. It fetches the latest document version, reapplies the update, and tries again. This retry mechanism is transparent but can cause delays if conflicts are frequent. Understanding this helps tune retry settings and avoid performance issues.

Result

Partial updates are resilient to conflicts but may slow down under heavy contention.

Knowing the retry mechanism helps diagnose update failures and optimize concurrency.

Under the Hood

Elasticsearch stores documents in immutable segments. When a partial update is requested, it retrieves the current document, applies the changes in memory, and indexes a new document version into a new segment. The old version is marked as deleted but remains until segment merging. This approach ensures fast reads and safe writes without locking the entire index.

Why designed this way?

Immutable segments simplify concurrency and improve search speed by avoiding in-place changes. This design trades off some write overhead for faster, more reliable reads and easier crash recovery. Alternatives like in-place updates would require complex locking and could slow down searches.

┌───────────────┐       ┌───────────────┐       ┌───────────────┐
│ Existing Doc  │  -->  │ Apply Partial │  -->  │ New Doc Version│
│ (Segment A)   │       │ Update in Mem │       │ (Segment B)   │
└───────────────┘       └───────────────┘       └───────────────┘
         │                                         ↑
         └───────────── Mark old as deleted ──────┘

Myth Busters - 4 Common Misconceptions

Quick: Does a partial update send only the changed fields to Elasticsearch or the whole document? Commit to your answer.

Common Belief: Partial updates send the entire document but only change some fields internally.

Reality: Partial updates send only the fields you want to change, not the whole document.

Why it matters: Sending the whole document wastes bandwidth and slows down updates, defeating the purpose of partial updates.

Quick: Do partial updates modify documents directly on disk? Commit to your answer.

Common Belief: Partial updates change the document directly on disk to save time.

Reality: Partial updates create a new document version and mark the old one as deleted; they never modify documents in place.

Why it matters: Assuming in-place modification can lead to misunderstandings about update speed and data consistency.

Quick: Can partial updates always avoid version conflicts? Commit to your answer.

Common Belief: Partial updates never cause version conflicts because they only change parts of a document.

Reality: Partial updates can cause version conflicts if multiple updates happen simultaneously on the same document.

Why it matters: Ignoring conflicts can cause lost updates or errors in multi-user systems.

Quick: Are partial updates always faster than full document replacements? Commit to your answer.

Common Belief: Partial updates are always faster and cheaper than full updates.

Reality: Partial updates reduce network load but internally cost similar resources as full updates because a new document version is created.

Why it matters: Overestimating performance gains can lead to poor design choices in high-load systems.

Expert Zone

1

Partial updates can trigger reindexing of nested or parent-child documents, which may impact performance unexpectedly.

2

Using scripts in partial updates can introduce security risks if not properly sandboxed or validated.

3

Frequent partial updates can increase segment merges and disk I/O, affecting cluster health over time.

When NOT to use

Avoid partial updates when you need to change many fields at once or restructure documents significantly; in such cases, reindexing or full document replacement is better. Also, for bulk updates of many documents, use the bulk API for efficiency.

Production Patterns

In production, partial updates are often combined with optimistic concurrency control to prevent lost updates. They are used for counters, status flags, or small metadata changes. Scripts enable complex logic like conditional increments or timestamp updates. Monitoring update conflicts and retry rates is common to maintain cluster health.

Connections

Optimistic concurrency control

Partial updates rely on optimistic concurrency control to handle simultaneous changes safely.

Understanding concurrency control helps prevent data loss and ensures updates apply only when the document is unchanged.

Immutable data structures

Elasticsearch's partial updates use immutable segments, similar to immutable data structures in programming.

Knowing immutable data concepts clarifies why Elasticsearch creates new document versions instead of modifying in place.

Version control systems

Partial updates and version control both manage changes by creating new versions rather than overwriting.

Seeing partial updates like commits in version control helps understand how changes are tracked and conflicts resolved.

Common Pitfalls

#1 Trying to update a document field by sending the whole document with partial changes but missing unchanged fields.

Wrong approach:

POST /index/_update/1
{
"doc": {"age": 31}
}
// But the original document had 'name' and 'city' fields missing here, so they get removed.

Correct approach:

Use partial update with only the fields to change, ensuring other fields remain untouched:
POST /index/_update/1
{
"doc": {"age": 31}
}

Root cause:

Misunderstanding that partial updates merge fields rather than replace the entire document.

#2 Ignoring version conflicts and assuming partial updates always succeed.

Wrong approach:

POST /index/_update/1
{
"doc": {"counter": 5}
}
// No version control or retry logic used.

Correct approach:

Use optimistic concurrency control parameters:
POST /index/_update/1?if_seq_no=10&if_primary_term=1
{
"doc": {"counter": 5}
}

Root cause:

Not handling concurrent updates leads to lost or failed updates.

#3 Using partial updates with heavy scripts without sandboxing or validation.

Wrong approach:

POST /index/_update/1
{
"script": "ctx._source.field = params.value",
"params": {"value": "user input"}
}
// No validation of 'value'.

Correct approach:

Validate or sanitize script parameters before use, or use painless scripts with strict controls.

Root cause:

Security risks arise from executing untrusted code or data in scripts.

Key Takeaways

Partial updates let you change only parts of a document, saving bandwidth and simplifying updates.

Elasticsearch applies partial updates by creating new document versions, not by modifying documents in place.

Scripts in partial updates enable dynamic and conditional changes beyond simple field replacements.

Optimistic concurrency control is essential to avoid conflicts and lost updates in multi-user environments.

Partial updates improve network efficiency but have similar storage costs as full updates due to Elasticsearch's immutable segment design.

Practice

1. What is the main purpose of using partial updates in Elasticsearch?

easy

A. To delete a document completely from the index

B. To create a new document with all fields specified

C. To update only specific fields of a document without replacing the whole document

D. To retrieve documents matching a query

Solution

1. Step 1: Understand partial update concept

   Partial updates allow changing only some fields of a document instead of replacing the entire document.

2. Step 2: Identify the main purpose

   This saves bandwidth and time by sending only the changed fields, not the whole document.

3. Final Answer:

   To update only specific fields of a document without replacing the whole document -> Option C

4. Quick Check:

   Partial update = update some fields only [OK]

Hint: Partial updates change only some fields, not whole document [OK]

Common Mistakes:

• Confusing partial update with document deletion
• Thinking partial update creates new documents
• Believing partial update retrieves documents

2. Which of the following is the correct syntax to perform a partial update on a document with ID '1' in index 'products'?

easy

A. POST /products/_doc/1 { "price": 20 }

B. POST /products/_update/1 { "doc": { "price": 20 } }

C. PUT /products/_update/1 { "price": 20 }

D. GET /products/_update/1 { "doc": { "price": 20 } }

Solution

1. Step 1: Identify correct HTTP method and endpoint

   Partial updates use POST method on the _update API with the document ID.

2. Step 2: Check request body format

   The update body must include a "doc" key with the fields to update.

3. Final Answer:

   POST /products/_update/1 { "doc": { "price": 20 } } -> Option B

4. Quick Check:

   Use POST + _update + doc key [OK]

Hint: Use POST with _update and doc key for partial updates [OK]

Common Mistakes:

• Using GET instead of POST for update
• Omitting the 'doc' key in request body
• Using PUT on _update endpoint incorrectly
• Updating with _doc endpoint instead of _update

3. Given this partial update request on document ID '2' in index 'users':

POST /users/_update/2
{
  "doc": {
    "age": 30
  }
}

If the original document was {"name": "Alice", "age": 25}, what will be the document after the update?

medium

A. {"name": "Alice", "age": 30}

B. {"age": 30}

C. {"name": "Alice"}

D. {"name": "Alice", "age": 25, "updated": true}

Solution

1. Step 1: Understand partial update effect

   The partial update changes only the "age" field to 30, keeping other fields unchanged.

2. Step 2: Apply update to original document

   Original document {"name": "Alice", "age": 25} becomes {"name": "Alice", "age": 30} after update.

3. Final Answer:

   {"name": "Alice", "age": 30} -> Option A

4. Quick Check:

   Partial update changes only specified fields [OK]

Hint: Partial update changes only given fields, others stay same [OK]

Common Mistakes:

• Thinking update replaces whole document
• Assuming fields not in doc are removed
• Adding extra fields not in update request

4. You try this partial update:

POST /orders/_update/5
{
  "doc": {
    "status": "shipped"
  }
}

But you get an error. Which is the most likely cause?

medium

A. The document with ID '5' does not exist in 'orders' index

B. You used GET instead of POST

C. You forgot to include the 'doc' key in the body

D. The 'status' field cannot be updated

Solution

1. Step 1: Check common update errors

   Partial update errors often happen if the document ID does not exist.

2. Step 2: Analyze given request and error cause

   The syntax is correct, so the likely cause is missing document with ID '5'.

3. Final Answer:

   The document with ID '5' does not exist in 'orders' index -> Option A

4. Quick Check:

   Missing document ID causes update error [OK]

Hint: Check if document ID exists before updating [OK]

Common Mistakes:

• Confusing HTTP method errors with missing document
• Assuming all fields are immutable
• Omitting 'doc' key causing syntax errors

5. You want to increase the 'stock' field by 10 in a product document with ID '10' using a partial update. Which request body correctly achieves this?

hard

A. { "update": { "stock": 10 } }

B. { "doc": { "stock": 10 } }

C. { "doc": { "stock": "stock + 10" } }

D. { "script": { "source": "ctx._source.stock += params.count", "params": { "count": 10 } } }

Solution

1. Step 1: Understand increment operation in partial update

   To increase a numeric field, use a script that adds the value to the existing field.

2. Step 2: Identify correct syntax for scripted update

   { "script": { "source": "ctx._source.stock += params.count", "params": { "count": 10 } } } uses the 'script' key with source code to add 10 to 'stock'.

3. Final Answer:

   { "script": { "source": "ctx._source.stock += params.count", "params": { "count": 10 } } } -> Option D

4. Quick Check:

   Use script to increment numeric fields [OK]

Hint: Use script with ctx._source to increment fields [OK]

Common Mistakes:

• Trying to update with doc key using expression string
• Using 'update' key instead of 'doc' or 'script'
• Assigning value directly instead of incrementing