---
type: api
title: Bulk index or delete documents
description: **All methods and paths for this operation:**
url: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/operation/operation-bulk
resource: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/operation/operation-bulk
products:
  - Elasticsearch
---

# Bulk index or delete documents


Availability:

## Paths

- `POST` (also `PUT`) `/{index}/_bulk`
- `POST` (also `PUT`) `/_bulk`

- [Api key auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/authentication#apikeyauth)
- [Basic auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/authentication#basicauth)
- [Bearer auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/authentication#bearerauth)

#### Path Parameters

- `index` (string IndexName) — optional, leave it out to use `/_bulk`
  The name of the data stream, index, or index alias to perform bulk actions on.

## Description

Perform multiple `index`, `create`, `delete`, and `update` actions in a single request.
This reduces overhead and can greatly increase indexing speed.

If the Elasticsearch security features are enabled, you must have the following index privileges for the target data stream, index, or index alias:

* To use the `create` action, you must have the `create_doc`, `create`, `index`, or `write` index privilege. Data streams support only the `create` action.
* To use the `index` action, you must have the `create`, `index`, or `write` index privilege.
* To use the `delete` action, you must have the `delete` or `write` index privilege.
* To use the `update` action, you must have the `index` or `write` index privilege.
* To automatically create a data stream or index with a bulk API request, you must have the `auto_configure`, `create_index`, or `manage` index privilege.
* To make the result of a bulk operation visible to search using the `refresh` parameter, you must have the `maintenance` or `manage` index privilege.

Automatic data stream creation requires a matching index template with data stream enabled.

The actions are specified in the request body using a newline delimited JSON (NDJSON) structure:

```
action_and_meta_data\n
optional_source\n
action_and_meta_data\n
optional_source\n
....
action_and_meta_data\n
optional_source\n
```

The `index` and `create` actions expect a source on the next line and have the same semantics as the `op_type` parameter in the standard index API.
A `create` action fails if a document with the same ID already exists in the target
An `index` action adds or replaces a document as necessary.

NOTE: Data streams support only the `create` action.
To update or delete a document in a data stream, you must target the backing index containing the document.

An `update` action expects that the partial doc, upsert, and script and its options are specified on the next line.

A `delete` action does not expect a source on the next line and has the same semantics as the standard delete API.

NOTE: The final line of data must end with a newline character (`\n`).
Each newline character may be preceded by a carriage return (`\r`).
When sending NDJSON data to the `_bulk` endpoint, use a `Content-Type` header of `application/json` or `application/x-ndjson`.
Because this format uses literal newline characters (`\n`) as delimiters, make sure that the JSON actions and sources are not pretty printed.

If you provide a target in the request path, it is used for any actions that don't explicitly specify an `_index` argument.

A note on the format: the idea here is to make processing as fast as possible.
As some of the actions are redirected to other shards on other nodes, only `action_meta_data` is parsed on the receiving node side.

Client libraries using this protocol should try and strive to do something similar on the client side, and reduce buffering as much as possible.

There is no "correct" number of actions to perform in a single bulk request.
Experiment with different settings to find the optimal size for your particular workload.
Note that Elasticsearch limits the maximum size of a HTTP request to 100mb by default so clients must ensure that no request exceeds this size.
It is not possible to index a single document that exceeds the size limit, so you must pre-process any such documents into smaller pieces before sending them to Elasticsearch.
For instance, split documents into pages or chapters before indexing them, or store raw binary data in a system outside Elasticsearch and replace the raw data with a link to the external system in the documents that you send to Elasticsearch.

**Client suppport for bulk requests**

Some of the officially supported clients provide helpers to assist with bulk requests and reindexing:

* Go: Check out `esutil.BulkIndexer`
* Perl: Check out `Search::Elasticsearch::Client::5_0::Bulk` and `Search::Elasticsearch::Client::5_0::Scroll`
* Python: Check out `elasticsearch.helpers.*`
* JavaScript: Check out `client.helpers.*`
* Java: Check out `co.elastic.clients.elasticsearch._helpers.bulk.BulkIngester`
* .NET: Check out `BulkAllObservable`
* PHP: Check out bulk indexing.
* Ruby: Check out `Elasticsearch::Helpers::BulkHelper`

**Submitting bulk requests with cURL**

If you're providing text file input to `curl`, you must use the `--data-binary` flag instead of plain `-d`.
The latter doesn't preserve newlines. For example:

```
$ cat requests
{ "index" : { "_index" : "test", "_id" : "1" } }
{ "field1" : "value1" }
$ curl -s -H "Content-Type: application/x-ndjson" -XPOST localhost:9200/_bulk --data-binary "@requests"; echo
{"took":7, "errors": false, "items":[{"index":{"_index":"test","_id":"1","_version":1,"result":"created","forced_refresh":false}}]}
```

**Optimistic concurrency control**

Each `index` and `delete` action within a bulk API call may include the `if_seq_no` and `if_primary_term` parameters in their respective action and meta data lines.
The `if_seq_no` and `if_primary_term` parameters control how operations are run, based on the last modification to existing documents. See Optimistic concurrency control for more details.

**Versioning**

Each bulk item can include the version value using the `version` field.
It automatically follows the behavior of the index or delete operation based on the `_version` mapping.
It also support the `version_type`.

**Routing**

Each bulk item can include the routing value using the `routing` field.
It automatically follows the behavior of the index or delete operation based on the `_routing` mapping.

NOTE: Data streams do not support custom routing unless they were created with the `allow_custom_routing` setting enabled in the template.

**Refresh**

Control when the changes made by this request are visible to search.

NOTE: Only the shards that receive the bulk request will be affected by refresh.
Imagine a `_bulk?refresh=wait_for` request with three documents in it that happen to be routed to different shards in an index with five shards.
The request will only wait for those three shards to refresh.
The other two shards that make up the index do not participate in the `_bulk` request at all.

You might want to disable the refresh interval temporarily to improve indexing throughput for large bulk requests.
Refer to the linked documentation for step-by-step instructions using the index settings API.

[About tune for indexing speed](https://www.elastic.co/docs/deploy-manage/production-guidance/optimize-performance/indexing-speed#disable-refresh-interval)

## Query String Parameters

- `include_source_on_error` (boolean · default: true)
  True or false if to include the document source in the error message in case of parsing errors.
- `list_executed_pipelines` (boolean · default: false)
  If `true`, the response will include the ingest pipelines that were run for each index or create.
- `pipeline` (string)
  The pipeline identifier to use to preprocess incoming documents.
If the index has a default ingest pipeline specified, setting the value to `_none` turns off the default ingest pipeline for this request.
If a final pipeline is configured, it will always run regardless of the value of this parameter.
- `refresh` (enum Refresh · default: false)
  If `true`, Elasticsearch refreshes the affected shards to make this operation visible to search.
If `wait_for`, wait for a refresh to make this operation visible to search.
If `false`, do nothing with refreshes.
Valid values: `true`, `false`, `wait_for`.
  Values: `true`, `false`, `wait_for`
- `routing` (union Routing)
  A custom value that is used to route operations to a specific shard.
Not allowed when `index.slice.enabled` is `true` for the target index; use `_slice` instead.
  One of: `string` or `string[]`
- `_source` (union SourceConfigParam)
  Indicates whether to return the `_source` field (`true` or `false`) or contains a list of fields to return.
  One of: `boolean` or `Fields`
- `_source_excludes` (union Fields)
  A comma-separated list of source fields to exclude from the response.
You can also use this parameter to exclude fields from the subset specified in `_source_includes` query parameter.
If the `_source` parameter is `false`, this parameter is ignored.
  One of: `Field` or `Field[]`
- `_source_includes` (union Fields)
  A comma-separated list of source fields to include in the response.
If this parameter is specified, only these source fields are returned.
You can exclude fields from this subset using the `_source_excludes` query parameter.
If the `_source` parameter is `false`, this parameter is ignored.
  One of: `Field` or `Field[]`
- `timeout` (string Duration · default: 1m)
  The period each action waits for the following operations: automatic index creation, dynamic mapping updates, and waiting for active shards.
The default is `1m` (one minute), which guarantees Elasticsearch waits for at least the timeout before failing.
The actual wait time could be longer, particularly when multiple waits occur.
- `wait_for_active_shards` (WaitForActiveShards · default: 1)
  The number of shard copies that must be active before proceeding with the operation.
Set to `all` or any positive integer up to the total number of shards in the index (`number_of_replicas+1`).
The default is `1`, which waits for each primary shard to be active.
  Values: `all`, `index-setting`
- `require_alias` (boolean · default: false)
  If `true`, the request's actions must target an index alias.
- `require_data_stream` (boolean · default: false)
  If `true`, the request's actions must target a data stream (existing or to be created).

## Request Body

`application/json`

The request body contains a newline-delimited list of `create`, `delete`, `index`, and `update` actions and their associated source data.
Each item in the list is one of three kinds of NDJSON lines:

* An action line, which specifies the action to perform (`index`, `create`, `update`, or `delete`) and its metadata. For example: `{ "index": { "_index": "my-index", "_id": "1" } }`.
* An update source line, which must follow an `update` action line. It contains the partial document, script, or upsert options to apply.
* A document source line, which must follow an `index` or `create` action line. It contains the document to index.

A `delete` action is not followed by a source line.

An array; each item is one of:
- **OperationContainer**
  An action line, which is the first line of each operation in a bulk request.
It specifies the action to perform (`index`, `create`, `update`, or `delete`) and its metadata, such as the target index and document ID.
All actions except `delete` expect a source line to follow.
  - `index` ({} IndexOperation) — optional
    Index the specified document.
If the document exists, it replaces the document and increments the version.
The following line must contain the source data to be indexed.
    - `_id` (string Id) — optional
      The document ID.
    - `_index` (string IndexName) — optional
      The name of the index or index alias to perform the action on.
    - `routing` (string) — optional
      A custom value used to route operations to a specific shard, or multiple comma separated values.
    - `if_primary_term` (number) — optional
    - `if_seq_no` (number SequenceNumber) — optional
    - `version` (number VersionNumber) — optional
    - `version_type` (enum VersionType) — optional
      

Supported values include:
  - `internal`: Use internal versioning that starts at 1 and increments with each update or delete.
  - `external`: Only index the document if the specified version is strictly higher than the version of the stored document or if there is no existing document.
  - `external_gte`: Only index the document if the specified version is equal or higher than the version of the stored document or if there is no existing document.
NOTE: The `external_gte` version type is meant for special use cases and should be used with care.
If used incorrectly, it can result in loss of data.
      Values: `internal`, `external`, `external_gte`
    - `dynamic_templates` (map string to string) — optional
      A map from the full name of fields to the name of dynamic templates.
It defaults to an empty map.
If a name matches a dynamic template, that template will be applied regardless of other match predicates defined in the template.
If a field is already defined in the mapping, then this parameter won't be used.
    - `pipeline` (string) — optional
      The ID of the pipeline to use to preprocess incoming documents.
If the index has a default ingest pipeline specified, setting the value to `_none` turns off the default ingest pipeline for this request.
If a final pipeline is configured, it will always run regardless of the value of this parameter.
    - `require_alias` (boolean · default: false) — optional
      If `true`, the request's actions must target an index alias.
  - `create` ({} CreateOperation) — optional
    Index the specified document if it does not already exist.
The following line must contain the source data to be indexed.
    - `_id` (string Id) — optional
      The document ID.
    - `_index` (string IndexName) — optional
      The name of the index or index alias to perform the action on.
    - `routing` (string) — optional
      A custom value used to route operations to a specific shard, or multiple comma separated values.
    - `if_primary_term` (number) — optional
    - `if_seq_no` (number SequenceNumber) — optional
    - `version` (number VersionNumber) — optional
    - `version_type` (enum VersionType) — optional
      

Supported values include:
  - `internal`: Use internal versioning that starts at 1 and increments with each update or delete.
  - `external`: Only index the document if the specified version is strictly higher than the version of the stored document or if there is no existing document.
  - `external_gte`: Only index the document if the specified version is equal or higher than the version of the stored document or if there is no existing document.
NOTE: The `external_gte` version type is meant for special use cases and should be used with care.
If used incorrectly, it can result in loss of data.
      Values: `internal`, `external`, `external_gte`
    - `dynamic_templates` (map string to string) — optional
      A map from the full name of fields to the name of dynamic templates.
It defaults to an empty map.
If a name matches a dynamic template, that template will be applied regardless of other match predicates defined in the template.
If a field is already defined in the mapping, then this parameter won't be used.
    - `pipeline` (string) — optional
      The ID of the pipeline to use to preprocess incoming documents.
If the index has a default ingest pipeline specified, setting the value to `_none` turns off the default ingest pipeline for this request.
If a final pipeline is configured, it will always run regardless of the value of this parameter.
    - `require_alias` (boolean · default: false) — optional
      If `true`, the request's actions must target an index alias.
  - `update` ({} UpdateOperation) — optional
    Perform a partial document update.
The following line must contain the partial document and update options.
    - `_id` (string Id) — optional
      The document ID.
    - `_index` (string IndexName) — optional
      The name of the index or index alias to perform the action on.
    - `routing` (string) — optional
      A custom value used to route operations to a specific shard, or multiple comma separated values.
    - `if_primary_term` (number) — optional
    - `if_seq_no` (number SequenceNumber) — optional
    - `version` (number VersionNumber) — optional
    - `version_type` (enum VersionType) — optional
      

Supported values include:
  - `internal`: Use internal versioning that starts at 1 and increments with each update or delete.
  - `external`: Only index the document if the specified version is strictly higher than the version of the stored document or if there is no existing document.
  - `external_gte`: Only index the document if the specified version is equal or higher than the version of the stored document or if there is no existing document.
NOTE: The `external_gte` version type is meant for special use cases and should be used with care.
If used incorrectly, it can result in loss of data.
      Values: `internal`, `external`, `external_gte`
    - `require_alias` (boolean · default: false) — optional
      If `true`, the request's actions must target an index alias.
    - `retry_on_conflict` (number) — optional
      The number of times an update should be retried in the case of a version conflict.
  - `delete` ({} DeleteOperation) — optional
    Remove the specified document from the index.
    - `_id` (string Id) — optional
      The document ID.
    - `_index` (string IndexName) — optional
      The name of the index or index alias to perform the action on.
    - `routing` (string) — optional
      A custom value used to route operations to a specific shard, or multiple comma separated values.
    - `if_primary_term` (number) — optional
    - `if_seq_no` (number SequenceNumber) — optional
    - `version` (number VersionNumber) — optional
    - `version_type` (enum VersionType) — optional
      

Supported values include:
  - `internal`: Use internal versioning that starts at 1 and increments with each update or delete.
  - `external`: Only index the document if the specified version is strictly higher than the version of the stored document or if there is no existing document.
  - `external_gte`: Only index the document if the specified version is equal or higher than the version of the stored document or if there is no existing document.
NOTE: The `external_gte` version type is meant for special use cases and should be used with care.
If used incorrectly, it can result in loss of data.
      Values: `internal`, `external`, `external_gte`
- **UpdateAction**
  The source line that must follow an `update` action line.
It specifies the partial document, script, or upsert options to apply, plus optional update settings.
  - `detect_noop` (boolean · default: true) — optional
    If true, the `result` in the response is set to 'noop' when no changes to the document occur.
  - `doc` (object) — optional
    A partial update to an existing document.
  - `doc_as_upsert` (boolean · default: false) — optional
    Set to `true` to use the contents of `doc` as the value of `upsert`.
  - `script` (string Script) — optional
    The script to run to update the document.
  - `scripted_upsert` (boolean · default: false) — optional
    Set to `true` to run the script whether or not the document exists.
  - `_source` (SourceConfig · default: true) — optional
    If `false`, source retrieval is turned off.
You can also specify a comma-separated list of the fields you want to retrieve.
  - `upsert` (object) — optional
    If the document does not already exist, the contents of `upsert` are inserted as a new document.
If the document exists, the `script` is run.
- **Document source**
  The document to index. A document source line must follow an `index` or `create` action line.

## Response

`application/json`

- `errors` (boolean)
  If `true`, one or more of the operations in the bulk request did not complete successfully.
- `items` ([] string to ResponseItem)
  The result of each operation in the bulk request, in the order they were submitted.
- `took` (number)
  The length of time, in milliseconds, it took to process the bulk request.
- `ingest_took` (number)
## Code Examples

#### Console

```console
POST _bulk
{ "index" : { "_index" : "test", "_id" : "1" } }
{ "field1" : "value1" }
{ "delete" : { "_index" : "test", "_id" : "2" } }
{ "create" : { "_index" : "test", "_id" : "3" } }
{ "field1" : "value3" }
{ "update" : {"_id" : "1", "_index" : "test"} }
{ "doc" : {"field2" : "value2"} }
```

#### JavaScript

```javascript
const response = await client.bulk({
  operations: [
    {
      index: {
        _index: "test",
        _id: "1",
      },
    },
    {
      field1: "value1",
    },
    {
      delete: {
        _index: "test",
        _id: "2",
      },
    },
    {
      create: {
        _index: "test",
        _id: "3",
      },
    },
    {
      field1: "value3",
    },
    {
      update: {
        _id: "1",
        _index: "test",
      },
    },
    {
      doc: {
        field2: "value2",
      },
    },
  ],
});
```

#### Python

```python
resp = client.bulk(
    operations=[
        {
            "index": {
                "_index": "test",
                "_id": "1"
            }
        },
        {
            "field1": "value1"
        },
        {
            "delete": {
                "_index": "test",
                "_id": "2"
            }
        },
        {
            "create": {
                "_index": "test",
                "_id": "3"
            }
        },
        {
            "field1": "value3"
        },
        {
            "update": {
                "_id": "1",
                "_index": "test"
            }
        },
        {
            "doc": {
                "field2": "value2"
            }
        }
    ],
)
```

#### curl

```curl
curl -X POST "$ELASTICSEARCH_URL/_bulk" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/x-ndjson" \
  -d $'{"index":{"_index":"test","_id":"1"}}\n{"field1":"value1"}\n{"delete":{"_index":"test","_id":"2"}}\n{"create":{"_index":"test","_id":"3"}}\n{"field1":"value3"}\n{"update":{"_id":"1","_index":"test"}}\n{"doc":{"field2":"value2"}}\n'
```

#### C#

```c#
var response = await client
    .BulkAsync(new BulkRequest()
    {
        Operations = new global::Elastic.Clients.Elasticsearch.Core.Bulk.BulkOperationsCollection
        {
            new global::Elastic.Clients.Elasticsearch.Core.Bulk.BulkIndexOperation<object>(JsonSerializer.Deserialize<JsonElement>("""
            {
              "field1": "value1"
            }
            """))
            {
                Id = "1",
                Index = "test"
            },
            new global::Elastic.Clients.Elasticsearch.Core.Bulk.BulkDeleteOperation("2")
            {
                Index = "test"
            },
            new global::Elastic.Clients.Elasticsearch.Core.Bulk.BulkCreateOperation<object>(JsonSerializer.Deserialize<JsonElement>("""
            {
              "field1": "value3"
            }
            """))
            {
                Id = "3",
                Index = "test"
            },
            new global::Elastic.Clients.Elasticsearch.Core.Bulk.BulkUpdateOperation<object, object>("1")
            {
                Index = "test",
                Doc = JsonSerializer.Deserialize<JsonElement>("""
                {
                  "field2": "value2"
                }
                """)
            }
        }
    });
```

#### PHP

```php
$resp = $client->bulk([
    "body" => array(
        [
            "index" => [
                "_index" => "test",
                "_id" => "1",
            ],
        ],
        [
            "field1" => "value1",
        ],
        [
            "delete" => [
                "_index" => "test",
                "_id" => "2",
            ],
        ],
        [
            "create" => [
                "_index" => "test",
                "_id" => "3",
            ],
        ],
        [
            "field1" => "value3",
        ],
        [
            "update" => [
                "_id" => "1",
                "_index" => "test",
            ],
        ],
        [
            "doc" => [
                "field2" => "value2",
            ],
        ],
    ),
]);
```

#### Ruby

```ruby
response = client.bulk(
  body: [
    {
      "index": {
        "_index": "test",
        "_id": "1"
      }
    },
    {
      "field1": "value1"
    },
    {
      "delete": {
        "_index": "test",
        "_id": "2"
      }
    },
    {
      "create": {
        "_index": "test",
        "_id": "3"
      }
    },
    {
      "field1": "value3"
    },
    {
      "update": {
        "_id": "1",
        "_index": "test"
      }
    },
    {
      "doc": {
        "field2": "value2"
      }
    }
  ]
)
```

## Response Examples

#### Multiple successful operations

```json
{
   "took": 30,
   "errors": false,
   "items": [
      {
         "index": {
            "_index": "test",
            "_id": "1",
            "_version": 1,
            "result": "created",
            "_shards": {
               "total": 2,
               "successful": 1,
               "failed": 0
            },
            "status": 201,
            "_seq_no" : 0,
            "_primary_term": 1
         }
      },
      {
         "delete": {
            "_index": "test",
            "_id": "2",
            "_version": 1,
            "result": "not_found",
            "_shards": {
               "total": 2,
               "successful": 1,
               "failed": 0
            },
            "status": 404,
            "_seq_no" : 1,
            "_primary_term" : 2
         }
      },
      {
         "create": {
            "_index": "test",
            "_id": "3",
            "_version": 1,
            "result": "created",
            "_shards": {
               "total": 2,
               "successful": 1,
               "failed": 0
            },
            "status": 201,
            "_seq_no" : 2,
            "_primary_term" : 3
         }
      },
      {
         "update": {
            "_index": "test",
            "_id": "1",
            "_version": 2,
            "result": "updated",
            "_shards": {
                "total": 2,
                "successful": 1,
                "failed": 0
            },
            "status": 200,
            "_seq_no" : 3,
            "_primary_term" : 4
         }
      }
   ]
}
```

#### Failed actions

If you run `POST /_bulk` with operations that update non-existent documents, the operations cannot complete successfully. The API returns a response with an `errors` property value `true`. The response also includes an error object for any failed operations. The error object contains additional information about the failure, such as the error type and reason.

```json
{
  "took": 486,
  "errors": true,
  "items": [
    {
      "update": {
        "_index": "index1",
        "_id": "5",
        "status": 404,
        "error": {
          "type": "document_missing_exception",
          "reason": "[5]: document missing",
          "index_uuid": "aAsFqTI0Tc2W0LCWgPNrOA",
          "shard": "0",
          "index": "index1"
        }
      }
    },
    {
      "update": {
        "_index": "index1",
        "_id": "6",
        "status": 404,
        "error": {
          "type": "document_missing_exception",
          "reason": "[6]: document missing",
          "index_uuid": "aAsFqTI0Tc2W0LCWgPNrOA",
          "shard": "0",
          "index": "index1"
        }
      }
    },
    {
      "create": {
        "_index": "index1",
        "_id": "7",
        "_version": 1,
        "result": "created",
        "_shards": {
          "total": 2,
          "successful": 1,
          "failed": 0
        },
        "_seq_no": 0,
        "_primary_term": 1,
        "status": 201
      }
    }
  ]
}
```

#### Filter for failed operations

An example response from `POST /_bulk?filter_path=items.*.error`, which returns only information about failed operations.

```json
{
  "items": [
    {
      "update": {
        "error": {
          "type": "document_missing_exception",
          "reason": "[5]: document missing",
          "index_uuid": "aAsFqTI0Tc2W0LCWgPNrOA",
          "shard": "0",
          "index": "index1"
        }
      }
    },
    {
      "update": {
        "error": {
          "type": "document_missing_exception",
          "reason": "[6]: document missing",
          "index_uuid": "aAsFqTI0Tc2W0LCWgPNrOA",
          "shard": "0",
          "index": "index1"
        }
      }
    }
  ]
}
```