Deleting documents in Elasticsearch - Deep Dive

Overview - Deleting documents

What is it?

Deleting documents in Elasticsearch means removing specific pieces of data from an index. Each document is like a record or entry stored in Elasticsearch. When you delete a document, it no longer appears in search results or queries. This helps keep your data up-to-date and relevant.

Why it matters

Without the ability to delete documents, your Elasticsearch index would keep growing with outdated or incorrect data. This would make searches slower and less accurate, causing confusion and wasted resources. Deleting documents ensures your data stays clean and your searches return the right information quickly.

Where it fits

Before learning to delete documents, you should understand how Elasticsearch stores and indexes documents. After mastering deletion, you can learn about updating documents and managing index lifecycle for efficient data handling.

Mental Model

Core Idea

Deleting a document in Elasticsearch marks it as removed so it no longer appears in searches, but the actual removal happens later during index cleanup.

Think of it like...

Imagine a library where you cross out a book's entry in the catalog to show it's no longer available, but the book stays on the shelf until the librarian removes it during cleaning.

┌─────────────┐       ┌───────────────┐       ┌───────────────┐
│ Document in │──────▶│ Marked as     │──────▶│ Physically     │
│ Elasticsearch│       │ Deleted (flag)│       │ Removed later │
└─────────────┘       └───────────────┘       └───────────────┘

Build-Up - 7 Steps

1

Foundation

What is a document in Elasticsearch

Concept: Understanding the basic unit of data storage in Elasticsearch.

A document is a JSON object that holds data in Elasticsearch. It is stored inside an index and has a unique ID. For example, a document could represent a user profile or a product listing.

Result

You know that documents are the pieces of data you can add, search, update, or delete in Elasticsearch.

Knowing what a document is helps you understand what you are deleting when you remove data.

2

Foundation

How deletion works conceptually

Concept: Deletion in Elasticsearch does not immediately remove data but marks it for removal.

When you delete a document, Elasticsearch marks it as deleted internally. The document still exists physically until a process called segment merging cleans it up. This means deletion is fast and does not block other operations.

Result

You understand that deletion is a two-step process: marking and later physical removal.

Understanding this prevents confusion about why deleted documents might still appear briefly or why disk space is not freed immediately.

3

Intermediate

Deleting a document by ID

🤔Before reading on: do you think deleting a document requires searching for it first or can you delete directly by ID? Commit to your answer.

Concept: You can delete a document directly if you know its unique ID.

Elasticsearch provides a Delete API where you specify the index and the document's ID to remove it. For example, a DELETE request to /index/_doc/document_id removes that document.

Result

The document with the given ID is marked as deleted and will no longer appear in search results.

Knowing you can delete by ID makes deletion efficient and precise without extra searching.

4

Intermediate

Deleting documents by query

🤔Before reading on: do you think deleting by query removes documents immediately or marks them first? Commit to your answer.

Concept: You can delete multiple documents matching a search query at once.

Elasticsearch's Delete By Query API lets you specify a query to find documents to delete. All matching documents are marked as deleted. For example, deleting all documents where status is 'inactive'.

Result

All documents matching the query are marked deleted and excluded from future searches.

Deleting by query allows bulk removal based on conditions, saving time over deleting individually.

5

Intermediate

Handling version conflicts during deletion

🤔Before reading on: do you think deleting a document can fail if the document changed since you last saw it? Commit to your answer.

Concept: Elasticsearch uses versioning to prevent deleting a document that has changed unexpectedly.

When deleting, you can specify a version number. If the document's current version doesn't match, the delete fails to avoid removing updated data by mistake.

Result

You avoid accidental deletion of documents that have been updated concurrently.

Understanding version conflicts helps maintain data integrity in concurrent environments.

6

Advanced

Impact of deletion on index performance

🤔Before reading on: do you think frequent deletions improve or degrade Elasticsearch performance? Commit to your answer.

Concept: Frequent deletions can cause index fragmentation and affect performance until cleanup happens.

Deleted documents remain in segments until merged. Many deletions increase segment count and slow searches. Elasticsearch periodically merges segments to reclaim space and optimize performance.

Result

You see that deletion affects index health and that maintenance is needed for optimal speed.

Knowing this helps you plan deletion frequency and index maintenance to keep Elasticsearch fast.

7

Expert

Internals of segment merging after deletion

🤔Before reading on: do you think segment merging happens immediately after deletion or is scheduled? Commit to your answer.

Concept: Segment merging is a background process that physically removes deleted documents from storage.

Elasticsearch stores data in immutable segments. When documents are deleted, they are flagged but not removed. The merge process combines segments, skipping deleted documents, freeing disk space and improving search speed.

Result

Deleted documents are fully removed only after merges, which happen asynchronously.

Understanding segment merging explains why deletions don't free space instantly and why index tuning matters.

Under the Hood

Elasticsearch stores documents in immutable segments on disk. When a document is deleted, it is not immediately removed but marked with a tombstone flag. This marking is fast and does not rewrite segments. Later, a background process called segment merging combines smaller segments into larger ones, skipping deleted documents. This process physically removes deleted data and reclaims disk space. Until merging, deleted documents still occupy space but are invisible to searches.

Why designed this way?

This design balances speed and consistency. Immediate physical deletion would require rewriting large files, slowing down operations. Marking deletions allows fast writes and searches without blocking. Segment merging runs in the background to optimize storage and performance. Alternatives like immediate deletion were rejected because they hurt responsiveness and scalability.

┌───────────────┐       ┌───────────────┐       ┌───────────────┐
│ Immutable     │       │ Document      │       │ Segment       │
│ Segments on   │──────▶│ Marked as     │──────▶│ Merging       │
│ Disk          │       │ Deleted       │       │ Process       │
└───────────────┘       └───────────────┘       └───────────────┘
        │                      │                       │
        ▼                      ▼                       ▼
  Search reads          Deleted docs hidden       Deleted docs
  skip deleted docs     but still occupy space   physically removed
                        until merge completes

Myth Busters - 4 Common Misconceptions

Quick: Does deleting a document immediately free disk space? Commit yes or no.

Common Belief: Deleting a document instantly removes it and frees disk space.

Reality: Deletion only marks the document as deleted; disk space is freed later during segment merging.

Why it matters: Expecting immediate space recovery can lead to confusion and mismanagement of storage resources.

Quick: Can you delete documents without knowing their IDs? Commit yes or no.

Common Belief: You must know the exact document ID to delete it.

Reality: You can delete documents by query, removing all that match certain conditions without knowing IDs.

Why it matters: Believing you need IDs limits your ability to efficiently clean up data in bulk.

Quick: Does deleting a document guarantee it won't appear in search results immediately? Commit yes or no.

Common Belief: Deleted documents disappear from search results instantly.

Reality: Deleted documents are excluded from searches immediately, but due to eventual consistency and refresh intervals, they might briefly appear.

Why it matters: Misunderstanding this can cause confusion when deleted data still shows up shortly after deletion.

Quick: Is it safe to delete documents without considering version conflicts? Commit yes or no.

Common Belief: You can delete any document anytime without checking if it changed.

Reality: Deleting without handling version conflicts risks removing updated data accidentally.

Why it matters: Ignoring version conflicts can cause data loss in concurrent environments.

Expert Zone

1

Deleted documents still consume disk space until segment merges, so frequent deletions can degrade performance if merges lag.

2

Delete By Query operations are internally implemented as a combination of search and bulk delete, which can be costly on large datasets.

3

Versioning during deletion is crucial in distributed clusters to avoid race conditions and ensure data consistency.

When NOT to use

Avoid frequent individual document deletions in high-throughput systems; instead, consider using time-based indices and deleting entire indices or using index lifecycle management. For real-time deletion needs, consider external data stores optimized for fast deletes.

Production Patterns

In production, deletions are often batched or done via Delete By Query during off-peak hours. Time-series data is managed by deleting whole indices by date. Version conflicts are handled carefully to prevent data loss. Monitoring segment merges and disk usage is standard practice.

Connections

Garbage Collection in Programming

Both mark unused data first and clean it up later.

Understanding how Elasticsearch delays physical deletion like garbage collection helps grasp why deletions are fast but space is reclaimed asynchronously.

Database Transactions

Deletion operations must consider consistency and concurrency like transactions.

Knowing about version conflicts in deletion connects to transaction isolation concepts ensuring data integrity.

Library Catalog Management

Deleting documents is like marking books as removed in a catalog before physically removing them.

This connection shows how real-world inventory systems handle removal in stages, similar to Elasticsearch.

Common Pitfalls

#1 Trying to delete a document without specifying the correct index or ID.

Wrong approach:

DELETE /_doc/12345

Correct approach:

DELETE /my_index/_doc/12345

Root cause:

Not understanding that Elasticsearch requires both index and document ID to locate the document.

#2 Assuming Delete By Query deletes documents instantly and frees disk space immediately.

Wrong approach:

POST /my_index/_delete_by_query { "query": { "match_all": {} } }

Correct approach:

Use Delete By Query as above but monitor segment merges and disk usage to confirm cleanup.

Root cause:

Misunderstanding that deletion marks documents and that physical removal is asynchronous.

#3 Ignoring version conflicts and deleting documents blindly in concurrent environments.

Wrong approach:

DELETE /my_index/_doc/12345 without version parameter

Correct approach:

DELETE /my_index/_doc/12345?version=5

Root cause:

Not handling concurrent updates leads to accidental deletion of newer data.

Key Takeaways

Deleting documents in Elasticsearch marks them as removed but does not immediately erase them from disk.

You can delete documents by their unique ID or by matching queries to remove many at once.

Deleted documents remain invisible to searches but still occupy space until segment merging cleans them up.

Handling version conflicts during deletion prevents accidental data loss in concurrent environments.

Understanding the delayed physical removal and its impact on performance helps maintain healthy Elasticsearch clusters.

Practice

1.

Which Elasticsearch API method is used to delete a single document by its ID?

easy

A. GET method with document ID

B. DELETE method with document ID

C. POST method with document ID

D. PUT method with document ID

Solution

1. Step 1: Understand document deletion in Elasticsearch

   Deleting a single document requires specifying its ID and using the DELETE HTTP method.

2. Step 2: Identify the correct API method

   The DELETE method with the document ID is the standard way to remove one document.

3. Final Answer:

   DELETE method with document ID -> Option B

4. Quick Check:

   Delete single document = DELETE with ID [OK]

Hint: Use DELETE with document ID to remove one document fast [OK]

Common Mistakes:

• Using GET or POST instead of DELETE
• Trying to delete without specifying document ID
• Confusing _delete_by_query with single document deletion

2.

Which of the following is the correct syntax to delete a document with ID 123 from index products using Elasticsearch REST API?

?

easy

A. GET /products/_delete/123

B. POST /products/_doc/123/_delete

C. DELETE /products/_doc/123

D. PUT /products/_doc/123

Solution

1. Step 1: Recall the REST API syntax for deleting a document

   The correct syntax uses DELETE method on the path /index/_doc/document_id.

2. Step 2: Match the syntax with the options

   DELETE /products/_doc/123 matches DELETE /products/_doc/123 which is correct.

3. Final Answer:

   DELETE /products/_doc/123 -> Option C

4. Quick Check:

   Delete syntax = DELETE /index/_doc/id [OK]

Hint: DELETE + /index/_doc/document_id is the right syntax [OK]

Common Mistakes:

• Using POST or GET instead of DELETE
• Wrong URL path like _delete or missing _doc
• Using PUT which is for creating/updating

3.

Given this Elasticsearch _delete_by_query request to delete documents where status is "inactive":

{
  "query": {
    "term": { "status": "inactive" }
  }
}

What will be the result if there are 3 documents matching this query?

medium

A. Deletes 3 documents and returns success count 3

B. Deletes 0 documents because term query is incorrect

C. Deletes all documents in the index

D. Returns an error due to missing document ID

Solution

1. Step 1: Understand _delete_by_query behavior

   It deletes all documents matching the query, here documents with status "inactive".

2. Step 2: Apply to given query and data

   Since 3 documents match, all 3 will be deleted and success count will be 3.

3. Final Answer:

   Deletes 3 documents and returns success count 3 -> Option A

4. Quick Check:

   _delete_by_query deletes matching docs = 3 [OK]

Hint: Delete by query removes all matching docs, not just one [OK]

Common Mistakes:

• Thinking _delete_by_query needs document ID
• Assuming it deletes all documents regardless of query
• Confusing term query syntax

4.

What is wrong with this Elasticsearch delete request?

DELETE /users/_doc

It aims to delete a document but fails. Why?

medium

A. Missing document ID in the URL

B. Using DELETE instead of POST

C. Index name is incorrect

D. Missing request body with query

Solution

1. Step 1: Check the delete request URL format

   Deleting a document requires the document ID after _doc in the URL.

2. Step 2: Identify the missing part

   The request lacks the document ID, so Elasticsearch cannot identify which document to delete.

3. Final Answer:

   Missing document ID in the URL -> Option A

4. Quick Check:

   Delete URL needs document ID [OK]

Hint: Always include document ID after _doc in DELETE URL [OK]

Common Mistakes:

• Omitting document ID in delete URL
• Confusing DELETE with POST for deletion
• Thinking request body is needed for single delete

5.

You want to delete all documents from the orders index where the amount field is less than 100. Which Elasticsearch request correctly achieves this?

hard

A. DELETE /orders/_delete_by_query { "query": { "term": { "amount": 100 } } }

B. DELETE /orders/_doc { "query": { "range": { "amount": { "lt": 100 } } } }

C. POST /orders/_doc/amount_lt_100/_delete

D. POST /orders/_delete_by_query { "query": { "range": { "amount": { "lt": 100 } } } }

Solution

1. Step 1: Identify the correct API for deleting multiple documents by condition

   _delete_by_query is used with POST to delete documents matching a query.

2. Step 2: Check the query for amount less than 100

   The range query with "lt": 100 correctly matches documents with amount less than 100.

3. Step 3: Verify the request method and path

   POST /orders/_delete_by_query with the correct JSON body is the proper syntax.

4. Final Answer:

   POST /orders/_delete_by_query { "query": { "range": { "amount": { "lt": 100 } } } } -> Option D

5. Quick Check:

   Delete by query with range and POST = correct [OK]

Hint: Use POST _delete_by_query with range query for conditional deletes [OK]

Common Mistakes:

• Using DELETE method with request body (not supported)
• Using _doc endpoint instead of _delete_by_query
• Using term query instead of range for less than condition