Async search for expensive queries in Elasticsearch - Deep Dive

Overview - Async search for expensive queries

What is it?

Async search in Elasticsearch lets you run heavy or slow searches without waiting for them to finish immediately. Instead of blocking your application, you start the search and check back later for the results. This helps handle big data queries that take a long time to process.

Why it matters

Without async search, expensive queries would make your app freeze or slow down, frustrating users and wasting resources. Async search solves this by letting the system work in the background, so users can do other things while waiting. This improves performance and user experience in real-world applications.

Where it fits

Before learning async search, you should understand basic Elasticsearch queries and how search works synchronously. After mastering async search, you can explore advanced topics like search optimization, scroll API, and managing search contexts for large datasets.

Mental Model

Core Idea

Async search lets you start a heavy search and come back later to get the results, avoiding waiting and blocking.

Think of it like...

It's like ordering food at a busy restaurant: you place your order and get a ticket, then wait at your table while the kitchen prepares your meal. You don't stand at the counter waiting; you relax and check back when your number is called.

┌───────────────┐       ┌───────────────┐       ┌───────────────┐
│ Client sends  │──────▶│ Elasticsearch │──────▶│ Search runs   │
│ async search  │       │ starts async  │       │ in background │
│ request       │       │ search task   │       │               │
└───────────────┘       └───────────────┘       └───────────────┘
        ▲                                               │
        │                                               ▼
┌───────────────┐       ┌───────────────┐       ┌───────────────┐
│ Client polls  │◀──────│ Elasticsearch │◀──────│ Search result │
│ for results   │       │ returns status│       │ ready to fetch│
└───────────────┘       └───────────────┘       └───────────────┘

Build-Up - 7 Steps

1

Foundation

Understanding synchronous search basics

Concept: Learn how Elasticsearch handles normal search requests that wait for results immediately.

When you send a search query to Elasticsearch, it processes the request and returns results right away. This works well for quick queries but can cause delays if the query is complex or the data is large.

Result

The client waits until Elasticsearch finishes the search and then receives the results.

Knowing synchronous search helps you see why waiting for expensive queries can block your app and why async search is needed.

2

Foundation

What makes a query expensive

Concept: Identify factors that cause searches to take a long time or use many resources.

Queries that scan large datasets, use complex filters, aggregations, or sorting can be expensive. For example, searching millions of documents with multiple conditions or calculating statistics slows down response time.

Result

Expensive queries cause longer wait times and higher load on Elasticsearch nodes.

Understanding what makes queries expensive helps you decide when to use async search.

3

Intermediate

Starting an async search request

🤔Before reading on: do you think async search returns results immediately or a search ID to check later? Commit to your answer.

Concept: Learn how to initiate an async search and receive a task ID instead of immediate results.

You send a POST request to the _async_search endpoint with your query. Elasticsearch starts processing the search in the background and immediately returns a unique search ID. This ID lets you check the status or fetch results later.

Result

You get a response with a search ID and partial info, but no full results yet.

Knowing that async search returns a search ID instead of results prevents confusion about waiting times.

4

Intermediate

Polling for async search results

🤔Before reading on: do you think polling too frequently helps or harms performance? Commit to your answer.

Concept: Understand how to check if the async search is done and retrieve results safely.

Use the search ID to send GET requests to _async_search/{id}. Elasticsearch replies with the current status and results if ready. Polling too often can overload the system, so wait a few seconds between checks.

Result

You receive partial or full results depending on search progress.

Knowing how to poll efficiently helps balance responsiveness and system load.

5

Intermediate

Cancelling and managing async searches

Concept: Learn how to stop running async searches and manage resources.

If you no longer need results, you can send a DELETE request to _async_search/{id} to cancel the search. This frees up resources. Also, Elasticsearch automatically cleans up old async searches after a timeout.

Result

The async search task stops, and resources are released.

Managing async searches prevents wasted resources and keeps the cluster healthy.

6

Advanced

Using async search with scroll and aggregations

🤔Before reading on: do you think async search supports scrolling large result sets? Commit to your answer.

Concept: Explore how async search works with scrolling and aggregation queries for big data analysis.

Async search supports scroll contexts to retrieve large result sets in chunks without timing out. It also handles complex aggregations by running them in the background, allowing you to fetch partial results progressively.

Result

You can efficiently process and retrieve large or aggregated data asynchronously.

Understanding async search with scroll and aggregations unlocks powerful data analysis without blocking.

7

Expert

Internal resource management and optimization

🤔Before reading on: do you think async search tasks consume cluster resources indefinitely? Commit to your answer.

Concept: Learn how Elasticsearch manages async search tasks internally to optimize performance and resource use.

Elasticsearch tracks async search tasks with a lifecycle, including timeouts and limits on stored results. It uses caching and partial result storage to speed up repeated polling. The system balances resource use by cleaning up old tasks automatically.

Result

Async search tasks run efficiently without overloading the cluster or wasting memory.

Knowing internal management helps design better async search usage and avoid common pitfalls.

Under the Hood

When you start an async search, Elasticsearch creates a search context that runs independently of the client connection. This context holds the query state and partial results. The client receives a search ID to query this context later. Elasticsearch stores partial results and progress in memory or disk, allowing incremental fetching. It also manages timeouts and resource cleanup to avoid leaks.

Why designed this way?

Async search was designed to handle long-running queries without blocking client connections or overwhelming cluster resources. Traditional synchronous searches would cause timeouts or poor user experience for heavy queries. By decoupling query execution from client wait time, Elasticsearch improves scalability and responsiveness.

┌───────────────┐       ┌───────────────┐       ┌───────────────┐
│ Client sends  │──────▶│ Async search  │──────▶│ Search context│
│ async request │       │ task created  │       │ runs query    │
└───────────────┘       └───────────────┘       └───────────────┘
        │                       │                       │
        │                       │                       ▼
        │                       │             ┌─────────────────┐
        │                       │             │ Partial results  │
        │                       │             │ stored in memory │
        │                       │             └─────────────────┘
        │                       │                       │
        │                       │                       ▼
        │                       │             ┌─────────────────┐
        │                       │             │ Client polls    │
        │                       │             │ with search ID  │
        │                       │             └─────────────────┘
        │                       │                       │
        │                       │                       ▼
        │                       │             ┌─────────────────┐
        │                       │             │ Results returned │
        │                       │             └─────────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does async search return full results immediately? Commit yes or no.

Common Belief: Async search returns all results right away like normal search.

Reality: Async search returns a search ID immediately, but results come later after processing.

Why it matters: Expecting immediate results leads to confusion and misuse of the API.

Quick: Can you poll async search as fast as you want without issues? Commit yes or no.

Common Belief: Polling async search frequently has no downside.

Reality: Polling too often can overload Elasticsearch and degrade cluster performance.

Why it matters: Excessive polling can cause slowdowns and resource exhaustion.

Quick: Does async search run forever until manually stopped? Commit yes or no.

Common Belief: Async search tasks keep running indefinitely unless cancelled.

Reality: Elasticsearch automatically cleans up async search tasks after a timeout to free resources.

Why it matters: Assuming tasks run forever can cause resource leaks and cluster instability.

Quick: Is async search suitable for all query types? Commit yes or no.

Common Belief: Async search works perfectly for every Elasticsearch query.

Reality: Some queries, like very simple or real-time ones, may not benefit from async search and are better run synchronously.

Why it matters: Using async search unnecessarily adds complexity and overhead.

Expert Zone

1

Async search results can be partial and progressively updated, allowing early insights before full completion.

2

The search context uses a combination of in-memory and disk storage to balance speed and resource use.

3

Timeouts and retention periods for async searches can be tuned per use case to optimize cluster health.

When NOT to use

Avoid async search for very fast or simple queries where synchronous search is more efficient. For real-time data needs, use regular search or point-in-time queries. Also, avoid async search if your application cannot handle polling or managing search IDs.

Production Patterns

In production, async search is used for dashboards with heavy aggregations, large log analytics, and user-driven complex queries. Systems often implement exponential backoff polling and cache results client-side. Cleanup policies and monitoring of async search tasks are standard to maintain cluster stability.

Connections

Event-driven programming

Async search uses a similar pattern of starting a task and handling results later.

Understanding async search deepens your grasp of asynchronous workflows common in programming and system design.

Message queues

Both async search and message queues decouple request submission from processing and response.

Knowing how async search parallels message queues helps in designing scalable, non-blocking systems.

Project management task tracking

Async search’s search ID is like a task ticket you check to see progress and completion.

Relating async search to task tracking clarifies how to manage long-running operations in software.

Common Pitfalls

#1 Polling async search too frequently causing cluster overload

Wrong approach:

while(true) { GET /_async_search/{id} }

Correct approach:

Use delays between polls, e.g., poll every 3-5 seconds: setTimeout(() => GET /_async_search/{id}, 3000)

Root cause:

Misunderstanding that polling is free and ignoring resource limits.

#2 Expecting immediate results from async search

Wrong approach:

POST /_async_search with query and immediately using results from response

Correct approach:

POST /_async_search to get search ID, then GET /_async_search/{id} to fetch results when ready

Root cause:

Confusing async search with synchronous search behavior.

#3 Not cancelling unused async searches leading to resource leaks

Wrong approach:

Starting async searches and never deleting or cancelling them

Correct approach:

DELETE /_async_search/{id} when results are no longer needed

Root cause:

Ignoring lifecycle management of async search tasks.

Key Takeaways

Async search lets you run heavy Elasticsearch queries without waiting for immediate results, improving user experience.

It works by returning a search ID to check back later, avoiding blocking client connections.

Polling too often or not managing async searches properly can harm cluster performance.

Async search supports large data retrieval and complex aggregations by running queries in the background.

Understanding async search internals helps optimize resource use and build scalable search applications.

Practice

1. What is the main benefit of using async search in Elasticsearch for expensive queries?

easy

A. It caches all query results permanently.

B. It automatically speeds up the query execution time.

C. It disables query logging to improve performance.

D. It allows running slow queries without blocking the application.

Solution

1. Step 1: Understand async search purpose

   Async search lets you run slow or heavy queries without making your app wait or freeze.

2. Step 2: Identify the main benefit

   This means your app can continue working while the query runs in the background.

3. Final Answer:

   It allows running slow queries without blocking the application. -> Option D

4. Quick Check:

   Async search = non-blocking query execution [OK]

Hint: Async search runs queries in background, so app doesn't wait [OK]

Common Mistakes:

• Thinking async search speeds up queries automatically
• Assuming async search caches results permanently
• Believing async search disables logging

2. Which of the following is the correct way to start an async search request in Elasticsearch using the REST API?

easy

A. POST /_async_search
{
"query": { "match_all": {} }
}

B. GET /_async_search
{
"query": { "match_all": {} }
}

C. POST /_search/async
{
"query": { "match_all": {} }
}

D. PUT /_async_search
{
"query": { "match_all": {} }
}

Solution

1. Step 1: Recall async search API endpoint

   The correct endpoint to start an async search is POST /_async_search with the query in the body.

2. Step 2: Check HTTP method and path

   GET is not used to start async search, and /_search/async or PUT are incorrect paths or methods.

3. Final Answer:

   POST /_async_search with query body -> Option A

4. Quick Check:

   Start async search = POST /_async_search [OK]

Hint: Use POST method on /_async_search to start async search [OK]

Common Mistakes:

• Using GET instead of POST to start async search
• Using wrong endpoint like /_search/async
• Using PUT method which is invalid here

3. Given this async search response snippet, what does the id field represent?

{
  "id": "r1A2B3C4D5E6F7G8H9I",
  "is_running": true,
  "response": null
}

medium

A. The timeout duration for the async search.

B. The total number of documents matched by the query.

C. The unique identifier to check status or fetch results later.

D. The Elasticsearch node handling the query.

Solution

1. Step 1: Understand the async search response fields

   The id is a unique string to identify this async search request.

2. Step 2: Purpose of the id

   You use this id to check if the search is done or to get the results later.

3. Final Answer:

   The unique identifier to check status or fetch results later. -> Option C

4. Quick Check:

   Async search id = unique query handle [OK]

Hint: Async search id tracks query status and results [OK]

Common Mistakes:

• Confusing id with document count
• Thinking id is timeout or node info
• Assuming id changes during query

4. You wrote this code to start an async search but get an error:

POST /_async_search
{
  "query": {
    "match": {
      "title": "Elasticsearch"
    }
  },
  "wait_for_completion_timeout": "1s"
}

What is the error in this request?

medium

A. Missing comma between query and wait_for_completion_timeout fields.

B. Using POST instead of GET method.

C. wait_for_completion_timeout cannot be set in the request body.

D. The field name "title" is invalid in match query.

Solution

1. Step 1: Check JSON syntax

   The JSON body is missing a comma after the closing brace of the "query" object.

2. Step 2: Validate method and fields

   POST is correct method, wait_for_completion_timeout is valid in body, and "title" is a valid field name.

3. Final Answer:

   Missing comma between query and wait_for_completion_timeout fields. -> Option A

4. Quick Check:

   JSON syntax error = missing comma [OK]

Hint: Check commas between JSON fields carefully [OK]

Common Mistakes:

• Forgetting commas between JSON objects
• Confusing HTTP methods for async search
• Misplacing wait_for_completion_timeout outside body

5. You want to run a very expensive aggregation query on a large dataset without timing out. Which approach using async search is best to get the final results efficiently?

hard

A. Run a normal search with a very high timeout value to wait for results.

B. Start async search with a long wait_for_completion_timeout and poll using the returned id until results are ready.

C. Start async search and immediately request results without waiting for completion.

D. Run the query multiple times with smaller timeouts and merge results manually.

Solution

1. Step 1: Understand async search timeout and polling

   Setting a reasonable wait_for_completion_timeout lets the server try to finish quickly but returns control if it takes longer.

2. Step 2: Use the returned id to poll for completion

   You can check the status later using the id until the results are ready, avoiding timeouts and blocking.

3. Final Answer:

   Start async search with a long wait_for_completion_timeout and poll using the returned id until results are ready. -> Option B

4. Quick Check:

   Async search + polling = efficient for expensive queries [OK]

Hint: Use wait_for_completion_timeout + poll with id for big queries [OK]

Common Mistakes:

• Using normal search with high timeout risking app freeze
• Requesting results immediately before completion
• Manually merging partial results instead of async search