Bulk API Tuning for High Indexing Throughput

1. The bulk API in its basic form

The bulk API combines multiple index, update, or delete operations into a single HTTP request, encoded as NDJSON with alternating action and source lines. Instead of sending a separate request for every single product document, an application transfers several hundred or thousand documents in one go, which drastically cuts the per-document overhead for HTTP headers, TCP handshakes, and connection setup.

Elasticsearch processes a bulk request internally through a dedicated write thread pool, sized in relation to the number of available CPU cores. When more work arrives at once than that pool can handle, further requests first land in a bounded queue before being rejected once that queue fills up as well.

POST _bulk
{ "index": { "_index": "products", "_id": "4711" } }
{ "sku": "abc-123", "price": 19.90 }
{ "index": { "_index": "products", "_id": "4712" } }
{ "sku": "abc-124", "price": 24.50 }

2. Systematically finding the optimal batch size

There is no universally correct batch size, since it depends on document size, network latency, and cluster hardware. A batch size that is too small, for example only a few dozen documents per request, generates unnecessarily many round trips and lets the relative overhead per request dominate. A batch size that is too large, on the other hand, stresses the coordinating node's heap, raises the risk of tripping the indexing circuit breaker, and can unpredictably increase individual request latency through longer garbage collection pauses.

A proven starting point is a batch size between five and fifteen megabytes of payload or a few thousand documents, whichever limit is hit first, followed by systematic load tests with increasing batch size under realistic network conditions. Throughput typically improves as batch size grows, reaches a plateau, and drops again for oversized batches due to memory pressure, so the optimum is best found empirically rather than theoretically.

3. The trade-off between round trips and memory usage

Every additional round trip costs network latency and processing overhead on both sides of the connection, regardless of the actual document size. With a thousand small batches of ten documents each, this overhead quickly adds up to substantial total runtime, even if the actual indexing work on the cluster would be minimal.

Larger batches reduce the number of round trips, but require the entire batch content to sit in memory simultaneously, both on the sending process and on the receiving coordinating node, before the individual operations can be distributed and processed. This memory demand scales linearly with batch size, which is why unbounded batch size increases eventually turn into memory pressure rather than more throughput.

4. Disabling the refresh interval during a bulk load

By default, Elasticsearch makes newly written documents searchable roughly every second through a refresh operation that creates a new, small Lucene segment. During a bulk load with a high write rate, these frequent refreshes add up to substantial overhead, since every new segment later needs merging with other segments, and visibility of individual documents during the initial load phase usually is not needed anyway.

For the duration of an initial catalog load, it therefore helps to set index.refresh_interval to -1, which fully disables automatic refreshes, and reset it to the desired production value, usually one second, once the bulk load is complete. A manual refresh at the end then makes the data searchable all at once in a controlled way, instead of continuously producing small segments.

PUT products/_settings
{ "index": { "refresh_interval": "-1", "number_of_replicas": 0 } }

// reset once the bulk load finishes
PUT products/_settings
{ "index": { "refresh_interval": "1s", "number_of_replicas": 1 } }
POST products/_refresh

5. Temporarily reducing the replica count to zero

With replicas enabled, every write operation must run not only on the primary shard but also on every replica shard before the bulk request counts as complete. During an initial bulk load, that doubles or multiplies the actual write effort across the cluster, without the replicas yet providing any practical benefit for resilience or read capacity during this phase.

A common practice is therefore to set number_of_replicas to zero for the duration of the initial load and only raise it again step by step afterward. Elasticsearch then creates the replica shards by copying the already fully populated primary shards, which is often faster overall than applying every single write operation to multiple shards at once throughout the entire load phase.

6. Keeping an eye on the thread pool and bulk queue

Every node's write thread pool has a fixed size, usually tied to the number of available processor cores, plus a bounded queue for requests that cannot be processed immediately. If an application sends more parallel bulk requests than the pool, together with its queue, can absorb, Elasticsearch returns an EsRejectedExecutionException error for the excess requests instead of buffering them indefinitely.

Through GET _nodes/stats/thread_pool, the current load, including rejected requests, can be observed per node. Instead of blindly raising the queue size, which only delays rejections rather than solving them, it is usually more effective to size the number of parallel client connections and their batch size so they match the cluster's actual processing capacity.

7. Handling partial bulk failures

A bulk request rarely fails entirely, far more often individual operations fail within an otherwise successful batch, for example due to a version conflict, a mapping error on a single document, or a triggered circuit breaker. The bulk API response carries an errors field that signals, when true, that at least one sub-operation failed, while the rest of the batch was still processed.

A robust client implementation must therefore check every element in the items array individually for an error code, rather than relying solely on the overall response's HTTP status code. Failed individual operations can then be retried in a targeted way, ideally with exponential backoff for errors caused by temporary overload, such as circuit breaker trips.

8. A practical tuning checklist for the initial catalog load

Before starting a large initial load, a fixed checklist is worth following: set refresh interval to minus one, reduce replica count to zero, set translog durability to async if the risk is acceptable, use a batch size determined through load tests, and size the number of parallel bulk clients to the available thread pool resources instead of blindly opening as many parallel connections as possible.

Once the bulk load finishes, the checklist also includes resetting all temporary settings back to production values, triggering a final manual refresh, and optionally kicking off a force merge that consolidates the many small segments produced during the load phase into fewer, more efficient segments before the index is released for production reads.

# 1. Before the bulk load
curl -X PUT "es:9200/products/_settings" -d '{"index":{"refresh_interval":"-1","number_of_replicas":0}}'

# 2. During the load phase: send bulk requests with the tested batch size

# 3. After completion
curl -X PUT "es:9200/products/_settings" -d '{"index":{"refresh_interval":"1s","number_of_replicas":1}}'
curl -X POST "es:9200/products/_refresh"
curl -X POST "es:9200/products/_forcemerge?max_num_segments=1"

9. Monitoring indexing throughput during the load phase

Without monitoring, tuning is just guessing. GET _nodes/stats/indices/indexing shows the current indexing rate per node, while GET _cat/thread_pool/write?v gives a quick overview of active and rejected requests in the write pool. Together, these two values show whether a bottleneck sits more in the cluster's processing capacity or in the client application's send rate.

A sudden drop in indexing rate with a steady bulk request rate usually points to memory pressure, frequent garbage collection pauses, or a triggered circuit breaker, visible in the corresponding counters under GET _nodes/stats/breaker. Watching these metrics regularly throughout the load phase makes it possible to adjust batch size or the number of parallel clients while the import is still running, instead of only reacting after a failed run.

10. Summary

11. FAQ: Bulk API Tuning: The Essentials at a Glance