How to Use Bulk API for Performance in Elasticsearch

Use the _bulk API in Elasticsearch to send multiple index, update, or delete operations in a single request, which reduces overhead and improves performance. Format the request body as newline-delimited JSON with action and data pairs for efficient processing.

Syntax

The _bulk API expects a request body with pairs of lines: the first line specifies the action (like index, update, or delete), and the second line contains the document data or update script. Each line must be a valid JSON object, and lines are separated by newline characters.

This format allows Elasticsearch to process many operations in one HTTP request, reducing network overhead and improving indexing speed.

json

{ "index" : { "_index" : "my_index", "_id" : "1" } }
{ "field1" : "value1" }
{ "delete" : { "_index" : "my_index", "_id" : "2" } }
{ "update" : { "_index" : "my_index", "_id" : "3" } }
{ "doc" : { "field2" : "value2" } }

Example

This example shows how to bulk index two documents and delete one document in a single request using the Elasticsearch Bulk API.

http

POST /_bulk
{ "index" : { "_index" : "products", "_id" : "1" } }
{ "name" : "Laptop", "price" : 1200 }
{ "index" : { "_index" : "products", "_id" : "2" } }
{ "name" : "Phone", "price" : 800 }
{ "delete" : { "_index" : "products", "_id" : "3" } }

Output

{
  "took": 30,
  "errors": false,
  "items": [
    { "index": { "_index": "products", "_id": "1", "status": 201 } },
    { "index": { "_index": "products", "_id": "2", "status": 201 } },
    { "delete": { "_index": "products", "_id": "3", "status": 200 } }
  ]
}

Common Pitfalls

• Incorrect JSON formatting: Forgetting newline characters or mixing JSON objects on the same line causes errors.
• Large bulk size: Sending too many operations in one bulk request can cause memory issues or timeouts; keep bulk sizes moderate (e.g., 5,000 to 15,000 documents).
• Ignoring errors: Always check the errors field in the response to handle failed operations properly.
• Not refreshing index: Newly indexed documents may not be immediately searchable unless you refresh the index or wait.

http

Wrong way:
POST /_bulk
{ "index" : { "_index" : "test" } } { "field": "value" }

Right way:
POST /_bulk
{ "index" : { "_index" : "test" } }
{ "field": "value" }

Quick Reference

Concept	Description
Bulk API endpoint	POST /_bulk
Request format	Newline-delimited JSON with action and data pairs
Common actions	index, update, delete
Recommended bulk size	5,000 to 15,000 operations per request
Check response	Look for 'errors' field to detect failures

Key Takeaways

Use the _bulk API to batch multiple operations in one request for better performance.

Format the bulk request as newline-delimited JSON with action and data lines.

Avoid too large bulk sizes to prevent memory and timeout issues.

Always check the response for errors to handle failed operations.

Refresh the index if you need immediate searchability after bulk operations.