Bulk Indexing and the Bulk API
Index thousands of documents efficiently using the Bulk API and learn to handle partial failures.
Bulk Indexing and the Bulk API is a free Elasticsearch & Full Text Search Systems lesson on CoddyKit — lesson 4 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Elasticsearch & Full Text Search Systems learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.
Why Bulk
Indexing documents one HTTP request at a time is slow. The Bulk API packs many operations into a single request, dramatically improving throughput.
The NDJSON Format
Bulk requests use newline-delimited JSON: each action line is followed by its source line (for index/create/update). Every line ends with a newline, including the last.
A Basic Bulk Request
Here two documents are indexed in one call.
POST /products/_bulk
{ "index": { "_id": "1" } }
{ "name": "Keyboard", "price": 40 }
{ "index": { "_id": "2" } }
{ "name": "Mouse", "price": 20 }Supported Actions
Bulk supports four actions:
index— create or replacecreate— fail if the id existsupdate— partial updatedelete— no source line needed
Mixing Actions
A single bulk body can mix actions and even target different indices via the action metadata.
POST /_bulk
{ "delete": { "_index": "products", "_id": "3" } }
{ "update": { "_index": "products", "_id": "1" } }
{ "doc": { "price": 45 } }Partial Failures
Crucially, the bulk request itself returns 200 OK even if some items fail. You must inspect the errors flag and per-item status.
// response
{ "errors": true, "items": [ { "index": { "status": 201 } },
{ "index": { "status": 409 } } ] }Choosing a Batch Size
There is no perfect number, but 1,000 to 5,000 documents (or a few megabytes) per bulk request is a good starting range. Measure and adjust for your data.
Tuning for Heavy Loads
For huge initial loads, temporarily disable the refresh interval and reduce replicas, then restore them afterward.
PUT /products/_settings
{ "index": { "refresh_interval": "-1",
"number_of_replicas": 0 } }Restore After Load
Once the bulk load finishes, re-enable refresh and replicas so the data becomes searchable and durable.
PUT /products/_settings
{ "index": { "refresh_interval": "1s",
"number_of_replicas": 1 } }Retrying Failures
A status of 429 (too many requests) means the cluster is overloaded. Retry only the failed items with exponential backoff, not the whole batch.
Client Helpers
Official clients provide bulk helpers that chunk, send, and retry automatically, so you rarely build NDJSON by hand in production.
Quick Check
A bulk request returns HTTP 200. Is everything fine?
Recap
You learned the Bulk API: the NDJSON format, the four actions, why partial failures need per-item inspection, sensible batch sizes, load-time tuning of refresh and replicas, and retrying 429s with backoff.
Frequently asked questions
Is the “Bulk Indexing and the Bulk API” lesson free?
Yes — the full text of “Bulk Indexing and the Bulk API” is free to read here on the web, and the Elasticsearch & Full Text Search Systems course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Elasticsearch & Full Text Search Systems course, upgrade to CoddyKit PRO.
What will I learn in “Bulk Indexing and the Bulk API”?
Index thousands of documents efficiently using the Bulk API and learn to handle partial failures. You practise Elasticsearch & Full Text Search Systems with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.
Do I need any experience to start Elasticsearch & Full Text Search Systems?
No prior experience is required. Elasticsearch & Full Text Search Systems on CoddyKit is structured for beginners through advanced learners; this is — lesson 4 of 4, so you can start here or from the beginning and move at your own pace.
How long does the “Bulk Indexing and the Bulk API” lesson take?
Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.
Can I write and run code in this Elasticsearch & Full Text Search Systems lesson?
Yes. Every Elasticsearch & Full Text Search Systems lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.
All lessons in this course
- Indexing Documents into Elasticsearch
- CRUD Operations with Documents
- Basic Mapping and Data Types
- Bulk Indexing and the Bulk API