Batch Commands

This is a cURL request to a database named "Example" on our playground server.
It batches two commands:

1. Upload a new document called "person/1".
2. Execute a patch on that same document.

curl -X POST "http://live-test.ravendb.net/databases/Example/bulk_docs"
-H "Content-Type: application/json"
-d "{
    \"Commands\": [
        {
            \"Id\": \"person/1\",
            \"ChangeVector\": null,
            \"Document\": {
                \"Name\": \"John Smith\"
            },
            \"Type\": \"PUT\"
        },
        {
            \"Id\": \"person/1\",
            \"ChangeVector\": null,
            \"Patch\": {
                \"Script\": \"this.Name = 'Jane Doe';\",
                \"Values\": {}
            },
            \"Type\": \"PATCH\"
        }
    ]
}"

Response:

HTTP/1.1 201 Created
Server: nginx
Date: Sun, 15 Sep 2019 14:12:30 GMT
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Content-Encoding: gzip
Vary: Accept-Encoding
Raven-Server-Version: 4.2.4.42

{
    "Results": [
        {
            "Type": "PUT",
            "@id": "person/1",
            "@collection": "@empty",
            "@change-vector": "A:1-urx5nDNUT06FCpCon1wCyA",
            "@last-modified": "2019-09-15T14:12:30.0425811"
        },
        {
            "Id": "person/1",
            "ChangeVector": "A:2-urx5nDNUT06FCpCon1wCyA",
            "LastModified": "2019-09-15T14:12:30.0495095",
            "Type": "PATCH",
            "PatchStatus": "Patched",
            "Debug": null
        }
    ]
}

This is the general format of a cURL request with a batch of commands that does not include a Put Attachment Command (see the format for batching a Put Attachment Command below):

curl -X POST "<server URL>/databases/<database name>/bulk_docs?<batch options>"
-H "Content-Type: application/json"
-d "{
    \"Commands\": [
        { <command> },
        ...
    ]
}"

Query String

The query string takes batch options, which can make the server wait for indexing and replication to finish before responding.

Header

The header Content-Type is required and takes one of two values:

• application/json - if the batch does not include a Put Attachment Command.
• multipart/mixed; boundary=<separator> - if the batch does include a Put Attachment Command. The "separator" is an arbitrary string used to demarcate the attachment streams and commands array.
  
  

Body

The body contains a JSON array of commands.

-d "{
    \"Commands\": [
        { 
            \"Id\": \"<document ID>\",
            ...
            \"Type\": \"<command type>\"
        },
        { <command> },
        ...
    ]
}"

The following commands can be sent using the batch command:

• Put Document Command
• Patch Document Command
• Delete Document Command
• Delete by Prefix Command
• Put Attachment Command
• Delete Attachment Command

Batch Options

These options, configured in the query string, make the server wait until indexing or replication have completed before responding. If these have not completed before a specified amount of time has passed, the server can either respond as normal or throw an exception.

This is the general format of a cURL request that includes batch options in the query string:

curl -X POST "<server_URL>/databases/<database_name>/bulk_docs?<batch option>=<value>
             &<batch option>=<value>
             &<batch option>=<value>
             ..."
-H "Content-Type: <content_type>"
-d "{ }"

Indexing Options

Replication Options

Commands

Put Document Command

Upload a new document or update an existing document.

Format within the Commands array in the request body:

{
    \"Id\": \"<document ID>\",
    \"ChangeVector\": \"<expected change vector>\",
    \"Document\": {
        <document content>
    },
    \"Type\": \"PUT\",
    \"ForceRevisionCreationStrategy\": \"Before\"
}

Patch Document Command

Update a document. A patch is executed on the server side and does not involve loading the document, avoiding the cost of sending the entire document in a round trip over the network.

Format within the Commands array in the request body:

{
    \"Id\": \"<document ID>\",
    \"ChangeVector\": \"<expected change vector>\",
    \"Patch\": {
        \"Script\": \"<javascript code using $<argument name> >\",
        \"Values\": {
            \"<argument name>\": \"<value>\",
            ...
        }
    },
    \"PatchIfMissing\": {
        \"Script\": \"<javascript code>\",
        \"Values\": {
            <arguments>
        }
    },
    \"Type\": \"PATCH\"
}

Patch Request

Using scripts with arguments allows RavenDB to cache scripts and boost performance. For cURL, use single quotes ' to wrap strings.

Delete Document Command

Delete a document by its ID.

Format within the Commands array in the request body:

{
    \"Id\": \"<document ID>\",
    \"ChangeVector\": \"<expected change vector>\",
    \"Type\": \"DELETE\"
}

Delete by Prefix Command

Delete all documents whose IDs begin with a certain prefix.

Format within the Commands array in the request body:

{
    \"Id\": \"<document ID prefix>\",
    \"IdPrefixed\": true,
    \"Type\": \"DELETE\"
}

Put Attachment Command

Add an attachment to a document, or update an existing attachment.

If a batch contains a Put Attachment Command, the cURL format of the request is slightly different from a batch that doesn't.
The Content-Type header takes multipart/mixed; boundary="<separator>" instead of the default application/json.
The body contains the Commands array followed by each of the attachments, passed in the form of binary streams. The attachment streams come in the same order as their respective Put Attachment Commands within the Commands array. The separator demarcates these sections.

The general form of a cURL request:

curl -X POST "<server URL>/databases/<database name>/bulk_docs"
-H "Content-Type: multipart/mixed; boundary=<separator>"
-d "
--<separator>
{
    \"Commands\":[ 
        {
            \"Id\": \"<document ID>\",
            \"Name\": \"<attachment name>\",
            \"ContentType\": \"<attachment MIME type>\"
            \"ChangeVector\": \"<expected change vector>\",
            \"Type\": \"AttachmentPUT\"
        },
        ...
    ]
}
--<separator>
Command-Type: AttachmentStream

<binary stream>
--<separator>
...
--<separator>--"

Delete Attachment Command

Delete an attachment in a certain document.

Format within the Commands array in the request body:

{
    \"Id\": \"<document ID>\",
    \"Name\": \"<attachment name>\",
    \"ChangeVector\": \"<expected change vector>\",
    \"Type\": \"AttachmentDELETE\"
}

Http Status Codes

Response Body

Results appear in the same order as the commands in the request body.

{
    "Results":[
        { },
        ...
    ]
}

• Format within the Results array in the response body:
  • Put Document Command
  • Patch Document Command
  • Delete Document Command
  • Delete by Prefix Command
  • Put Attachment Command
  • Delete Attachment Command

Put Document Command

{
    "Type": "PUT",
    "@id": "<document ID>",
    "@collection": "<collection name>",
    "@change-vector": "<current change vector>",
    "@last-modified": "<date and time UTC>"
}

Patch Document Command

{
    "@id": "<document ID>",
    "@change-vector": "<current change vector>",
    "@last-modified": "<date and time UTC>",
    "Type": "PATCH",
    "PatchStatus": "<patch status>",
    "Debug": null
}

PatchStatus

Delete Document Command

{
    "Id": "<document ID>",
    "Type": "DELETE",
    "Deleted": <boolean>
}

Delete by Prefix Command

{
    "Id": "<prefix>",
    "Type": "DELETE",
    "Deleted": <boolean>
}

Put Attachment Command

{
    "Id": "<document ID>",
    "Type": "AttachmentPUT",
    "Name": "<attachment name>",
    "ChangeVector": "<attachment change vector>",
    "Hash": "<Hash>",
    "ContentType": "<MIME type>",
    "Size": <attachment size in bytes>,
    "DocumentChangeVector": "<current change vector>"
}

Delete Attachment Command

{
    "Type": "AttachmentDELETE",
    "@id": "<document ID>",
    "Name": "<attachment name",
    "DocumentChangeVector": "<current change vector>"
}

About Northwind, the database used in our examples.

• In this section:
  • Put Document Command
  • Patch Document Command
  • Delete Document Command
  • Delete by Prefix Command
  • Put Attachment Command
  • Delete Attachment Command

Put Document Command

Request:

curl -X POST "http://live-test.ravendb.net/databases/Example/bulk_docs"
-H "Content-Type: application/json"
-d "{
    \"Commands\": [
        {
            \"Id\": \"person/1\",
            \"ChangeVector\": null,
            \"Document\": {
                \"Name\": \"John Smith\"
            },
            \"Type\": \"PUT\"
        }
    ]
}"

Response:

HTTP/1.1 201 Created
Server:"nginx"
Date:"Wed, 18 Sep 2019 16:14:20 GMT"
Content-Type:"application/json; charset=utf-8"
Transfer-Encoding:"chunked"
Connection:"keep-alive"
Content-Encoding:"gzip"
Vary:"Accept-Encoding"
Raven-Server-Version:"4.2.4.42"

{
    "Results": [
        {
            "Type": "PUT",
            "@id": "person/1",
            "@collection": "@empty",
            "@change-vector": "A:5951-pITDlhlRaEeJh16dDBREzg, A:1887-0N64iiIdYUKcO+yq1V0cPA, A:6214-xwmnvG1KBkSNXfl7/0yJ1A",
            "@last-modified": "2019-09-18T16:14:20.5759532"
        }
    ]
}

Patch Document Command

Request:

curl -X POST "http://live-test.ravendb.net/databases/Example/bulk_docs"
-H "Content-Type: application/json"
-d "{
    \"Commands\": [
        {
            \"Id\": \"person/1\",
            \"ChangeVector\": null,
            \"Patch\": {
                \"Script\": \"this.Name = 'Jane Doe';\",
                \"Values\": {}
            },
            \"Type\": \"PATCH\"
        }
    ]
}"

Response:

HTTP/1.1 201 Created
Server:"nginx"
Date:"Wed, 18 Sep 2019 16:18:13 GMT"
Content-Type:"application/json; charset=utf-8"
Transfer-Encoding:"chunked"
Connection:"keep-alive"
Content-Encoding:"gzip"
Vary:"Accept-Encoding"
Raven-Server-Version:"4.2.4.42"

{
    "Results": [
        {
            "Id": "person/1",
            "ChangeVector": "A:5952-pITDlhlRaEeJh16dDBREzg, A:1887-0N64iiIdYUKcO+yq1V0cPA, A:6214-xwmnvG1KBkSNXfl7/0yJ1A",
            "LastModified": "2019-09-18T16:18:13.5745560",
            "Type": "PATCH",
            "PatchStatus": "Patched",
            "Debug": null
        }
    ]
}

Delete Document Command

Request:

curl -X POST "http://live-test.ravendb.net/databases/Example/bulk_docs"
-H "Content-Type: application/json"
-d "{
    \"Commands\": [
        {
            \"Id\": \"employees/1-A\",
            \"ChangeVector\": null,
            \"Type\": \"DELETE\"
        }
	]
}"

Response:

HTTP/1.1 201 Created
Server:"nginx"
Date:"Wed, 18 Sep 2019 16:30:15 GMT"
Content-Type:"application/json; charset=utf-8"
Transfer-Encoding:"chunked"
Connection:"keep-alive"
Content-Encoding:"gzip"
Vary:"Accept-Encoding"
Raven-Server-Version:"4.2.4.42"

{
    "Results": [
        {
            "Id": "employees/1-A",
            "Type": "DELETE",
            "Deleted": true,
            "ChangeVector": null
        }
    ]
}

Delete by Prefix Command

Request:

curl -X POST "http://live-test.ravendb.net/databases/Example/bulk_docs"
-H "Content-Type: application/json"
-d "{
    \"Commands\": [
        {
            \"Id\": \"employ\",
            \"ChangeVector\": null,
            \"IdPrefixed\": true,
            \"Type\": \"DELETE\"
        }
	]
}"

Response:

HTTP/1.1 201 Created
Server:"nginx"
Date:"Wed, 18 Sep 2019 16:32:16 GMT"
Content-Type:"application/json; charset=utf-8"
Transfer-Encoding:"chunked"
Connection:"keep-alive"
Content-Encoding:"gzip"
Vary:"Accept-Encoding"
Raven-Server-Version:"4.2.4.42"

{
    "Results": [
        {
            "Id": "employ",
            "Type": "DELETE",
            "Deleted": true
        }
    ]
}

Put Attachment Command

Request:

curl -X POST "http://live-test.ravendb.net/databases/Example/bulk_docs"
-H "Content-Type: multipart/mixed; boundary=some_boundary"
-d "
--some_boundary
{
	\"Commands\": [
		{
			\"Id\":\"shippers/1-A\",
			\"Name\":\"some_file\",
			\"ContentType\":\"text\"
			\"Type\":\"AttachmentPUT\",
		}
	]
}
--some_boundary
Command-Type: AttachmentStream

12345
--some_boundary--"

Response:

HTTP/1.1 201 Created
Server:"nginx"
Date:"Wed, 18 Sep 2019 16:40:43 GMT"
Content-Type:"application/json; charset=utf-8"
Transfer-Encoding:"chunked"
Connection:"keep-alive"
Content-Encoding:"gzip"
Vary:"Accept-Encoding"
Raven-Server-Version:"4.2.4.42"

{
    "Results": [
        {
            "Id": "shippers/1-A",
            "Type": "AttachmentPUT",
            "Name": "some_file",
            "ChangeVector": "A:5973-pITDlhlRaEeJh16dDBREzg, A:1887-0N64iiIdYUKcO+yq1V0cPA, A:6214-xwmnvG1KBkSNXfl7/0yJ1A",
            "Hash": "DHnN2gtPymAUoaFxtgjxfU83O8fxGHw8+H/P+kkPxjg=",
            "ContentType": "text",
            "Size": 5,
            "DocumentChangeVector": "A:5974-pITDlhlRaEeJh16dDBREzg, A:1887-0N64iiIdYUKcO+yq1V0cPA, A:6214-xwmnvG1KBkSNXfl7/0yJ1A"
        }
    ]
}

Delete Attachment Command

Request:

curl -X POST "http://live-test.ravendb.net/databases/Example/bulk_docs"
-H "Content-Type: application/json"
-d "{
    \"Commands\": [
        {
            \"Id\": \"categories/2-A\",
            \"Name\": \"image.jpg\",
            \"ChangeVector\": null,
            \"Type\": \"AttachmentDELETE\"
        }
	]
}"

Response:

HTTP/1.1 201 Created
Server:"nginx"
Date:"Wed, 18 Sep 2019 16:44:40 GMT"
Content-Type:"application/json; charset=utf-8"
Transfer-Encoding:"chunked"
Connection:"keep-alive"
Content-Encoding:"gzip"
Vary:"Accept-Encoding"
Raven-Server-Version:"4.2.4.42"

{
    "Results": [
        {
            "Type": "AttachmentDELETE",
            "@id": "categories/2-A",
            "Name": "image.jpg",
            "DocumentChangeVector": "A:5979-pITDlhlRaEeJh16dDBREzg, A:1887-0N64iiIdYUKcO+yq1V0cPA, A:6214-xwmnvG1KBkSNXfl7/0yJ1A"
        }
    ]
}