Bulk index or delete documents | Elasticsearch API documentation (v8)

Path parameters

indexstring Required
The name of the data stream, index, or index alias to perform bulk actions on.

Query parameters

include_source_on_errorboolean
True or false if to include the document source in the error message in case of parsing errors.
list_executed_pipelinesboolean
If true, the response will include the ingest pipelines that were run for each index or create.
pipelinestring
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.
refreshstring
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 are true, false, or wait_for.
routingstring
A custom value that is used to route operations to a specific shard.
_sourceboolean | string | array[string]
Indicates whether to return the _source field (true or false) or contains a list of fields to return.
_source_excludesstring | array[string]
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.
_source_includesstring | array[string]
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.
timeoutstring
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.
Values are -1 or 0.
wait_for_active_shardsnumber | string
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 are all or index-setting.
require_aliasboolean
If true, the request's actions must target an index alias.
require_data_streamboolean
If true, the request's actions must target a data stream (existing or to be created).

application/json

Bodyobject Required

indexobject
Hide index attributes Show index attributes object
- _idstring
- _indexstring
- routingstring
- if_primary_termnumber
- if_seq_nonumber
- versionnumber
- version_typestring
  Values are internal, external, external_gte, or force.
- dynamic_templatesobject
  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.
  Hide dynamic_templates attribute Show dynamic_templates attribute object
  *string Additional properties
- pipelinestring
  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_aliasboolean
  If true, the request's actions must target an index alias.
createobject
Hide create attributes Show create attributes object
- _idstring
- _indexstring
- routingstring
- if_primary_termnumber
- if_seq_nonumber
- versionnumber
- version_typestring
  Values are internal, external, external_gte, or force.
- dynamic_templatesobject
  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.
  Hide dynamic_templates attribute Show dynamic_templates attribute object
  *string Additional properties
- pipelinestring
  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_aliasboolean
  If true, the request's actions must target an index alias.
updateobject
Hide update attributes Show update attributes object
- _idstring
- _indexstring
- routingstring
- if_primary_termnumber
- if_seq_nonumber
- versionnumber
- version_typestring
  Values are internal, external, external_gte, or force.
- require_aliasboolean
  If true, the request's actions must target an index alias.
- retry_on_conflictnumber
  The number of times an update should be retried in the case of a version conflict.
deleteobject
Hide delete attributes Show delete attributes object
- _idstring
- _indexstring
- routingstring
- if_primary_termnumber
- if_seq_nonumber
- versionnumber
- version_typestring
  Values are internal, external, external_gte, or force.

detect_noopboolean
If true, the result in the response is set to 'noop' when no changes to the document occur.
docobject
A partial update to an existing document.
doc_as_upsertboolean
Set to true to use the contents of doc as the value of upsert.
scriptobject
Hide script attributes Show script attributes object
- sourcestring
  The script source.
- idstring
- paramsobject
  Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.
  Hide params attribute Show params attribute object
  *object Additional properties
- langstring
  Any of:
  ScriptLanguagestring ScriptLanguagestring
  Values are painless, expression, mustache, or java.
- optionsobject
  Hide options attribute Show options attribute object
  *string Additional properties
scripted_upsertboolean
Set to true to run the script whether or not the document exists.
_sourceboolean | object
Defines how to fetch a source. Fetching can be disabled entirely, or the source can be filtered.
One of:
SourceConfigboolean SourceFilterobject
Hide attributes Show attributes
excludesstring | array[string]
includesstring | array[string]
upsertobject
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.

Responses

200 application/json
Hide response attributes Show response attributes object
- errorsboolean Required
  If true, one or more of the operations in the bulk request did not complete successfully.
- itemsarray[object] Required
  The result of each operation in the bulk request, in the order they were submitted.
  Hide items attribute Show items attribute object
  *object Additional properties
  Hide * attributes Show * attributes object
  _idstring | null
  The document ID associated with the operation.
  One of:
  string-1string string-2string | null
  _indexstring Required
  The name of the index associated with the operation. If the operation targeted a data stream, this is the backing index into which the document was written.
  statusnumber Required
  The HTTP status code returned for the operation.
  failure_storestring
  Values are not_applicable_or_unknown, used, not_enabled, or failed.
  errorobject
  Hide error attributes Show error attributes object
  typestring Required
  The type of error
  reasonstring
  A human-readable explanation of the error, in English.
  stack_tracestring
  The server stack trace. Present only if the error_trace=true parameter was sent with the request.
  caused_byobject
  root_causearray[object]
  suppressedarray[object]
  _primary_termnumber
  The primary term assigned to the document for the operation. This property is returned only for successful operations.
  resultstring
  The result of the operation. Successful values are created, deleted, and updated.
  _seq_nonumber
  _shardsobject
  Hide _shards attributes Show _shards attributes object
  failednumber Required
  successfulnumber Required
  totalnumber Required
  failuresarray[object]
  skippednumber
  _versionnumber
  forced_refreshboolean
  getobject
  Hide get attributes Show get attributes object
  fieldsobject
  Hide fields attribute Show fields attribute object
  *object Additional properties
  foundboolean Required
  _seq_nonumber
  _primary_termnumber
  _routingstring
  _sourceobject
  Hide _source attribute Show _source attribute object
  *object Additional properties
- tooknumber Required
  The length of time, in milliseconds, it took to process the bulk request.
- ingest_tooknumber

POST /{index}/_bulk

curl \
 --request POST 'http://api.example.com/{index}/_bulk' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{ \"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\"} }"'

Request examples

Run `POST _bulk` to perform multiple 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"} }

When you run `POST _bulk` and use the `update` action, you can use `retry_on_conflict` as a field in the action itself (not in the extra payload line) to specify how many times an update should be retried in the case of a version conflict.

{ "update" : {"_id" : "1", "_index" : "index1", "retry_on_conflict" : 3} }
{ "doc" : {"field" : "value"} }
{ "update" : { "_id" : "0", "_index" : "index1", "retry_on_conflict" : 3} }
{ "script" : { "source": "ctx._source.counter += params.param1", "lang" : "painless", "params" : {"param1" : 1}}, "upsert" : {"counter" : 1}}
{ "update" : {"_id" : "2", "_index" : "index1", "retry_on_conflict" : 3} }
{ "doc" : {"field" : "value"}, "doc_as_upsert" : true }
{ "update" : {"_id" : "3", "_index" : "index1", "_source" : true} }
{ "doc" : {"field" : "value"} }
{ "update" : {"_id" : "4", "_index" : "index1"} }
{ "doc" : {"field" : "value"}, "_source": true}

To return only information about failed operations, run `POST /_bulk?filter_path=items.*.error`.

{ "update": {"_id": "5", "_index": "index1"} }
{ "doc": {"my_field": "foo"} }
{ "update": {"_id": "6", "_index": "index1"} }
{ "doc": {"my_field": "foo"} }
{ "create": {"_id": "7", "_index": "index1"} }
{ "my_field": "foo" }

Run `POST /_bulk` to perform a bulk request that consists of index and create actions with the `dynamic_templates` parameter. The bulk request creates two new fields `work_location` and `home_location` with type `geo_point` according to the `dynamic_templates` parameter. However, the `raw_location` field is created using default dynamic mapping rules, as a text field in that case since it is supplied as a string in the JSON document.

{ "index" : { "_index" : "my_index", "_id" : "1", "dynamic_templates": {"work_location": "geo_point"}} }
{ "field" : "value1", "work_location": "41.12,-71.34", "raw_location": "41.12,-71.34"}
{ "create" : { "_index" : "my_index", "_id" : "2", "dynamic_templates": {"home_location": "geo_point"}} }
{ "field" : "value2", "home_location": "41.12,-71.34"}

Response examples (200)

{
   "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
         }
      }
   ]
}

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.

{
  "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
      }
    }
  ]
}

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

{
  "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"
        }
      }
    }
  ]
}

Path parameters

Query parameters

Bodyobject Required

Responses

_idstring | null