Batch document operation #

Provides a efficient way to perform multiple index, create, delete, and update operations in a single request.

Examples #

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

The API returns the following result:

{
  "took": 30,
  "errors": false,
  "items": [
    {
      "index": {
        "_collection": "default:test",
        "_id": "0,0",
        "result": "created",
        ...
      }
    },
    {
      "delete": {
        "_collection": "default:test",
        "_id": "0,1",
        "result": "not_found",
        ...
      }
    },
    {
      "create": {
        "_collection": "default:test",
        "_id": "0,2",
        "result": "created",
        ...
      }
    },
    {
      "update": {
        "_collection": "default:test",
        "_id": "0,0",
        "result": "updated",
        ...
      }
    }
  ]
}

Request #

POST /_bulk
POST /<target>/_bulk

Path parameters #

• <target>
  (Optional, string) Name of the collection to target. Actions that don’t explicitly specify their target in the action line use it.

Query parameters #

• realtime
  (Optional, boolean, default: true) Request-level write-mode switch that overrides schema property-level realtime settings for every document in this request: false applies the batch WAL-only (durable immediately, searchable after the offline epoch build).
• key_as_id
  (Optional, boolean, default: false) ES-compat rendering: keyed documents answer with the user key AS _id (see the index API).
• sync_replication
  (Optional, boolean) Opt back into synchronous inline replication for this request (wait for the replica RPC and count it in the response).

Request body #

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 standard API: create fails if a document with the same ID already exists in the target, index adds or replaces a document as necessary.

update expects a JSON object on the next line with the same body as the partial update API: a partial doc object to merge and/or an ordered ops operator list. Other fields (such as script or upsert) are rejected.

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

Because this format uses literal \n’s 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.

create #

Indexes the specified document if it does not already exist. The following line must contain the source data to be indexed.

• _namespace
  (Optional, string) Name of the namespace to perform the action on.
• _collection
  (Optional, string) Name of the collection to perform the action on. This parameter is required if a <target> is not specified in the request path.
• _index
  (Optional, string) A shortcut to specify the namespace and collection in [<namespace>:]<collection> syntax. This parameter conflicts with <_namespace> and <_collection>.
• _id
  (Optional, string) The document ID. If no ID is specified, a document ID is automatically generated.

delete #

Removes the specified document from the index.

• _namespace
  (Optional, string) Name of the namespace to perform the action on.
• _collection
  (Optional, string) Name of the collection to perform the action on. This parameter is required if a <target> is not specified in the request path.
• _index
  (Optional, string) A shortcut to specify the namespace and collection in [<namespace>:]<collection> syntax. This parameter conflicts with <_namespace> and <_collection>.
• _id
  (Required, string) The document ID.

index #

Indexes the specified document. If the document exists, replaces the document and increments the version. The following line must contain the source data to be indexed.

• _namespace
  (Optional, string) Name of the namespace to perform the action on.
• _collection
  (Optional, string) Name of the collection to perform the action on. This parameter is required if a <target> is not specified in the request path.
• _index
  (Optional, string) A shortcut to specify the namespace and collection in [<namespace>:]<collection> syntax. This parameter conflicts with <_namespace> and <_collection>.
• _id
  (Optional, string) The document ID. If no ID is specified, a document ID is automatically generated.

update #

Partially updates the specified document with the source on the next line.

• _namespace
  (Optional, string) Name of the namespace to perform the action on.
• _collection
  (Optional, string) Name of the collection to perform the action on. This parameter is required if a <target> is not specified in the request path.
• _index
  (Optional, string) A shortcut to specify the namespace and collection in [<namespace>:]<collection> syntax. This parameter conflicts with <_namespace> and <_collection>.
• _id
  (Required, string) The document ID.
• retry_on_conflict
  (Optional, integer, default: 3) Optimistic-concurrency retries for the read-modify-write — same semantics as the _update API’s query parameter.

doc #

The partial document to merge. Optional for update operations (an ops-only source line is also valid).

ops #

Ordered list of update operators, same as the partial update API. Optional for update operations.

<fields> #

The document source to index. Required for create and index operations.