Working with Documents using REST

Read document

reads a single document

GET /_api/document/{document-handle}

Path Parameters

  • document-handle (required): The handle of the document.

Header Parameters

  • If-None-Match (optional): If the "If-None-Match" header is given, then it must contain exactly one ETag. The document is returned, if it has a different revision than the given ETag. Otherwise an HTTP 304 is returned.
  • If-Match (optional): If the "If-Match" header is given, then it must contain exactly one ETag. The document is returned, if it has the same revision as the given ETag. Otherwise a HTTP 412 is returned.

Returns the document identified by document-handle. The returned document contains three special attributes: _id containing the document handle, _key containing key which uniquely identifies a document in a given collection and _rev containing the revision.

Example:

Use a document handle:

shell> curl --dump - http://localhost:8529/_api/document/products/9949

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
etag: "_VTxTBoC---"
x-content-type-options: nosniff

{ 
  "_key" : "9949", 
  "_id" : "products/9949", 
  "_rev" : "_VTxTBoC---", 
  "hello" : "world" 
}

Example:

Use a document handle and an etag:

shell> curl --header 'If-None-Match: "_VTxTBvu---"' --dump - http://localhost:8529/_api/document/products/9993

Example:

Unknown document handle:

shell> curl --dump - http://localhost:8529/_api/document/products/unknownhandle

HTTP/1.1 404 Not Found
content-type: application/json; charset=utf-8
x-content-type-options: nosniff

{ 
  "error" : true, 
  "errorMessage" : "collection not found: products", 
  "code" : 404, 
  "errorNum" : 1203 
}

Return Codes

  • 200: is returned if the document was found
  • 304: is returned if the "If-None-Match" header is given and the document has the same version
  • 404: is returned if the document or collection was not found
  • 412: is returned if an "If-Match" header is given and the found document has a different version. The response will also contain the found document's current revision in the _rev attribute. Additionally, the attributes _id and _key will be returned.

Examples

Use a document handle:

shell> curl --dump - http://localhost:8529/_api/document/products/9949

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
etag: "_VTxTBoC---"
x-content-type-options: nosniff
show response body

Use a document handle and an etag:

shell> curl --header 'If-None-Match: "_VTxTBvu---"' --dump - http://localhost:8529/_api/document/products/9993

Unknown document handle:

shell> curl --dump - http://localhost:8529/_api/document/products/unknownhandle

HTTP/1.1 404 Not Found
content-type: application/json; charset=utf-8
x-content-type-options: nosniff
show response body

Changes in 3.0 from 2.8:

The rev query parameter has been withdrawn. The same effect can be achieved with the If-Match HTTP header.

Read document header

reads a single document head

HEAD /_api/document/{document-handle}

Path Parameters

  • document-handle (required): The handle of the document.

Header Parameters

  • If-None-Match (optional): If the "If-None-Match" header is given, then it must contain exactly one ETag. If the current document revision is not equal to the specified ETag, an HTTP 200 response is returned. If the current document revision is identical to the specified ETag, then an HTTP 304 is returned.
  • If-Match (optional): If the "If-Match" header is given, then it must contain exactly one ETag. The document is returned, if it has the same revision as the given ETag. Otherwise a HTTP 412 is returned.

Like GET, but only returns the header fields and not the body. You can use this call to get the current revision of a document or check if the document was deleted.

Example:

shell> curl -X HEAD --dump - http://localhost:8529/_api/document/products/9985

Return Codes

  • 200: is returned if the document was found
  • 304: is returned if the "If-None-Match" header is given and the document has the same version
  • 404: is returned if the document or collection was not found
  • 412: is returned if an "If-Match" header is given and the found document has a different version. The response will also contain the found document's current revision in the ETag header.

Examples

shell> curl -X HEAD --dump - http://localhost:8529/_api/document/products/9985

Changes in 3.0 from 2.8:

The rev query parameter has been withdrawn. The same effect can be achieved with the If-Match HTTP header.

Read all documents

reads all documents from collection

PUT /_api/simple/all-keys

Query Parameters

A JSON object with these properties is required:

  • type: The type of the result. The following values are allowed:
    • id: returns an array of document ids (_id attributes)
    • key: returns an array of document keys (_key attributes)
    • path: returns an array of document URI paths. This is the default.
  • collection: The name of the collection. This is only for backward compatibility. In ArangoDB versions < 3.0, the URL path was /_api/document and this was passed in via the query parameter "collection". This combination was removed.

Returns an array of all keys, ids, or URI paths for all documents in the collection identified by collection. The type of the result array is determined by the type attribute.

Note that the results have no defined order and thus the order should not be relied on.

Example:

Return all document paths

shell> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/simple/all-keys <<EOF
{ 
  "collection" : "products" 
}
EOF

HTTP/1.1 201 Created
content-type: application/json; charset=utf-8
x-content-type-options: nosniff

{ 
  "result" : [ 
    "/_db/_system/_api/document/products/9975", 
    "/_db/_system/_api/document/products/9971", 
    "/_db/_system/_api/document/products/9978" 
  ], 
  "hasMore" : false, 
  "cached" : false, 
  "extra" : { 
    "stats" : { 
      "writesExecuted" : 0, 
      "writesIgnored" : 0, 
      "scannedFull" : 3, 
      "scannedIndex" : 0, 
      "filtered" : 0, 
      "httpRequests" : 0, 
      "executionTime" : 0.00021505355834960938 
    }, 
    "warnings" : [ ] 
  }, 
  "error" : false, 
  "code" : 201 
}

Example:

Return all document keys

shell> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/simple/all-keys <<EOF
{ 
  "collection" : "products", 
  "type" : "id" 
}
EOF

HTTP/1.1 201 Created
content-type: application/json; charset=utf-8
x-content-type-options: nosniff

{ 
  "result" : [ 
    "products/9964", 
    "products/9957", 
    "products/9961" 
  ], 
  "hasMore" : false, 
  "cached" : false, 
  "extra" : { 
    "stats" : { 
      "writesExecuted" : 0, 
      "writesIgnored" : 0, 
      "scannedFull" : 3, 
      "scannedIndex" : 0, 
      "filtered" : 0, 
      "httpRequests" : 0, 
      "executionTime" : 0.00014901161193847656 
    }, 
    "warnings" : [ ] 
  }, 
  "error" : false, 
  "code" : 201 
}

Example:

Collection does not exist

shell> curl --dump - http://localhost:8529/_api/document/doesnotexist

HTTP/1.1 404 Not Found
content-type: application/json; charset=utf-8
x-content-type-options: nosniff

{ 
  "error" : true, 
  "errorMessage" : "expecting GET /_api/document/<document-handle>", 
  "code" : 404, 
  "errorNum" : 1203 
}

Return Codes

  • 201: All went well.
  • 404: The collection does not exist.

Examples

Return all document paths

shell> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/simple/all-keys <<EOF
{ 
  "collection" : "products" 
}
EOF

HTTP/1.1 201 Created
content-type: application/json; charset=utf-8
x-content-type-options: nosniff
show response body

Return all document keys

shell> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/simple/all-keys <<EOF
{ 
  "collection" : "products", 
  "type" : "id" 
}
EOF

HTTP/1.1 201 Created
content-type: application/json; charset=utf-8
x-content-type-options: nosniff
show response body

Collection does not exist

shell> curl --dump - http://localhost:8529/_api/document/doesnotexist

HTTP/1.1 404 Not Found
content-type: application/json; charset=utf-8
x-content-type-options: nosniff
show response body

Changes in 3.0 from 2.8:

The collection name should now be specified in the URL path. The old way with the URL path /_api/document and the required query parameter collection still works.

Create document

creates documents

POST /_api/document/{collection}

Path Parameters

  • collection (required): The collection in which the collection is to be created.

Request Body (required)

A JSON representation of a single document or of an array of documents.

Query Parameters

  • collection (optional): The name of the collection. This is only for backward compatibility. In ArangoDB versions < 3.0, the URL path was /_api/document and this query parameter was required. This combination still works, but the recommended way is to specify the collection in the URL path.
  • waitForSync (optional): Wait until document has been synced to disk.
  • returnNew (optional): Additionally return the complete new document under the attribute new in the result.
  • silent (optional): If set to true, an empty object will be returned as response. No meta-data will be returned for the created document. This option can be used to save some network traffic.

Creates a new document from the document given in the body, unless there is already a document with the _key given. If no _key is given, a new unique _key is generated automatically.

The body can be an array of documents, in which case all documents in the array are inserted with the same semantics as for a single document. The result body will contain a JSON array of the same length as the input array, and each entry contains the result of the operation for the corresponding input. In case of an error the entry is a document with attributes error set to true and errorCode set to the error code that has happened.

Possibly given _id and _rev attributes in the body are always ignored, the URL part or the query parameter collection respectively counts.

If the document was created successfully, then the Location header contains the path to the newly created document. The ETag header field contains the revision of the document. Both are only set in the single document case.

If silent is not set to true, the body of the response contains a JSON object (single document case) with the following attributes:

  • _id contains the document handle of the newly created document
  • _key contains the document key
  • _rev contains the document revision

In the multi case the body is an array of such objects.

If the collection parameter waitForSync is false, then the call returns as soon as the document has been accepted. It will not wait until the documents have been synced to disk.

Optionally, the query parameter waitForSync can be used to force synchronization of the document creation operation to disk even in case that the waitForSync flag had been disabled for the entire collection. Thus, the waitForSync query parameter can be used to force synchronization of just this specific operations. To use this, set the waitForSync parameter to true. If the waitForSync parameter is not specified or set to false, then the collection's default waitForSync behavior is applied. The waitForSync query parameter cannot be used to disable synchronization for collections that have a default waitForSync value of true.

If the query parameter returnNew is true, then, for each generated document, the complete new document is returned under the new attribute in the result.

Example:

Create a document in a collection named products. Note that the revision identifier might or might not by equal to the auto-generated key.

shell> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/document/products <<EOF
{ "Hello": "World" }
EOF

HTTP/1.1 201 Created
content-type: application/json; charset=utf-8
etag: "_VTxTBfa---"
x-content-type-options: nosniff
location: /_db/_system/_api/document/products/9915

{ 
  "_id" : "products/9915", 
  "_key" : "9915", 
  "_rev" : "_VTxTBfa---" 
}

Example:

Create a document in a collection named products with a collection-level waitForSync value of false.

shell> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/document/products <<EOF
{ "Hello": "World" }
EOF

HTTP/1.1 202 Accepted
content-type: application/json; charset=utf-8
etag: "_VTxTBby---"
x-content-type-options: nosniff
location: /_db/_system/_api/document/products/9905

{ 
  "_id" : "products/9905", 
  "_key" : "9905", 
  "_rev" : "_VTxTBby---" 
}

Example:

Create a document in a collection with a collection-level waitForSync value of false, but using the waitForSync query parameter.

shell> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/document/products?waitForSync=true <<EOF
{ "Hello": "World" }
EOF

HTTP/1.1 201 Created
content-type: application/json; charset=utf-8
etag: "_VTxTBl2---"
x-content-type-options: nosniff
location: /_db/_system/_api/document/products/9942

{ 
  "_id" : "products/9942", 
  "_key" : "9942", 
  "_rev" : "_VTxTBl2---" 
}

Example:

Unknown collection name

shell> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/document/products <<EOF
{ "Hello": "World" }
EOF

HTTP/1.1 404 Not Found
content-type: application/json; charset=utf-8
x-content-type-options: nosniff

{ 
  "error" : true, 
  "errorMessage" : "collection not found: products", 
  "code" : 404, 
  "errorNum" : 1203 
}

Example:

Illegal document

shell> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/document/products <<EOF
{ 1: "World" }
EOF

HTTP/1.1 400 Bad Request
content-type: application/json; charset=utf-8
x-content-type-options: nosniff

{ 
  "error" : true, 
  "errorMessage" : "VPackError error: Expecting '\"' or '}'", 
  "code" : 400, 
  "errorNum" : 600 
}

Example:

Insert multiple documents:

shell> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/document/products <<EOF
[{"Hello":"Earth"}, {"Hello":"Venus"}, {"Hello":"Mars"}]
EOF

HTTP/1.1 202 Accepted
content-type: application/json; charset=utf-8
x-content-type-options: nosniff

[ 
  { 
    "_id" : "products/9922", 
    "_key" : "9922", 
    "_rev" : "_VTxTBiC---" 
  }, 
  { 
    "_id" : "products/9926", 
    "_key" : "9926", 
    "_rev" : "_VTxTBiG---" 
  }, 
  { 
    "_id" : "products/9928", 
    "_key" : "9928", 
    "_rev" : "_VTxTBiG--_" 
  } 
]

Example:

Use of returnNew:

shell> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/document/products?returnNew=true <<EOF
{"Hello":"World"}
EOF

HTTP/1.1 202 Accepted
content-type: application/json; charset=utf-8
etag: "_VTxTBj6---"
x-content-type-options: nosniff
location: /_db/_system/_api/document/products/9935

{ 
  "_id" : "products/9935", 
  "_key" : "9935", 
  "_rev" : "_VTxTBj6---", 
  "new" : { 
    "_key" : "9935", 
    "_id" : "products/9935", 
    "_rev" : "_VTxTBj6---", 
    "Hello" : "World" 
  } 
}

Return Codes

  • 201: is returned if the documents were created successfully and waitForSync was true.
  • 202: is returned if the documents were created successfully and waitForSync was false.
  • 400: is returned if the body does not contain a valid JSON representation of one document or an array of documents. The response body contains an error document in this case.
  • 404: is returned if the collection specified by collection is unknown. The response body contains an error document in this case.
  • 409: is returned in the single document case if a document with the same qualifiers in an indexed attribute conflicts with an already existing document and thus violates that unique constraint. The response body contains an error document in this case. In the array case only 201 or 202 is returned, but if an error occurred, the additional HTTP header X-Arango-Error-Codes is set, which contains a map of the error codes that occurred together with their multiplicities, as in: 1205:10,1210:17 which means that in 10 cases the error 1205 "illegal document handle" and in 17 cases the error 1210 "unique constraint violated" has happened.

Examples

Create a document in a collection named products. Note that the revision identifier might or might not by equal to the auto-generated key.

shell> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/document/products <<EOF
{ "Hello": "World" }
EOF

HTTP/1.1 201 Created
content-type: application/json; charset=utf-8
etag: "_VTxTBfa---"
x-content-type-options: nosniff
location: /_db/_system/_api/document/products/9915
show response body

Create a document in a collection named products with a collection-level waitForSync value of false.

shell> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/document/products <<EOF
{ "Hello": "World" }
EOF

HTTP/1.1 202 Accepted
content-type: application/json; charset=utf-8
etag: "_VTxTBby---"
x-content-type-options: nosniff
location: /_db/_system/_api/document/products/9905
show response body

Create a document in a collection with a collection-level waitForSync value of false, but using the waitForSync query parameter.

shell> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/document/products?waitForSync=true <<EOF
{ "Hello": "World" }
EOF

HTTP/1.1 201 Created
content-type: application/json; charset=utf-8
etag: "_VTxTBl2---"
x-content-type-options: nosniff
location: /_db/_system/_api/document/products/9942
show response body

Unknown collection name

shell> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/document/products <<EOF
{ "Hello": "World" }
EOF

HTTP/1.1 404 Not Found
content-type: application/json; charset=utf-8
x-content-type-options: nosniff
show response body

Illegal document

shell> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/document/products <<EOF
{ 1: "World" }
EOF

HTTP/1.1 400 Bad Request
content-type: application/json; charset=utf-8
x-content-type-options: nosniff
show response body

Insert multiple documents:

shell> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/document/products <<EOF
[{"Hello":"Earth"}, {"Hello":"Venus"}, {"Hello":"Mars"}]
EOF

HTTP/1.1 202 Accepted
content-type: application/json; charset=utf-8
x-content-type-options: nosniff

[ 
  { 
    "_id" : "products/9922", 
    "_key" : "9922", 
    "_rev" : "_VTxTBiC---" 
  }, 
  { 
    "_id" : "products/9926", 
    "_key" : "9926", 
    "_rev" : "_VTxTBiG---" 
  }, 
  { 
    "_id" : "products/9928", 
    "_key" : "9928", 
    "_rev" : "_VTxTBiG--_" 
  } 
]

Use of returnNew:

shell> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/document/products?returnNew=true <<EOF
{"Hello":"World"}
EOF

HTTP/1.1 202 Accepted
content-type: application/json; charset=utf-8
etag: "_VTxTBj6---"
x-content-type-options: nosniff
location: /_db/_system/_api/document/products/9935
show response body

Changes in 3.0 from 2.8:

The collection name should now be specified in the URL path. The old way with the URL path /_api/document and the required query parameter collection still works. The possibility to insert multiple documents with one operation is new and the query parameter returnNew has been added.

Replace document

replaces a document

PUT /_api/document/{document-handle}

Request Body (required)

A JSON representation of a single document.

Path Parameters

  • document-handle (required): This URL parameter must be a document handle.

Query Parameters

  • waitForSync (optional): Wait until document has been synced to disk.
  • ignoreRevs (optional): By default, or if this is set to true, the _rev attributes in the given document is ignored. If this is set to false, then the _rev attribute given in the body document is taken as a precondition. The document is only replaced if the current revision is the one specified.
  • returnOld (optional): Return additionally the complete previous revision of the changed document under the attribute old in the result.
  • returnNew (optional): Return additionally the complete new document under the attribute new in the result.
  • silent (optional): If set to true, an empty object will be returned as response. No meta-data will be returned for the replaced document. This option can be used to save some network traffic.

Header Parameters

  • If-Match (optional): You can conditionally replace a document based on a target revision id by using the if-match HTTP header.

Replaces the document with handle with the one in the body, provided there is such a document and no precondition is violated.

If the If-Match header is specified and the revision of the document in the database is unequal to the given revision, the precondition is violated.

If If-Match is not given and ignoreRevs is false and there is a _rev attribute in the body and its value does not match the revision of the document in the database, the precondition is violated.

If a precondition is violated, an HTTP 412 is returned.

If the document exists and can be updated, then an HTTP 201 or an HTTP 202 is returned (depending on waitForSync, see below), the ETag header field contains the new revision of the document and the Location header contains a complete URL under which the document can be queried.

Optionally, the query parameter waitForSync can be used to force synchronization of the document replacement operation to disk even in case that the waitForSync flag had been disabled for the entire collection. Thus, the waitForSync query parameter can be used to force synchronization of just specific operations. To use this, set the waitForSync parameter to true. If the waitForSync parameter is not specified or set to false, then the collection's default waitForSync behavior is applied. The waitForSync query parameter cannot be used to disable synchronization for collections that have a default waitForSync value of true.

If silent is not set to true, the body of the response contains a JSON object with the information about the handle and the revision. The attribute _id contains the known document-handle of the updated document, _key contains the key which uniquely identifies a document in a given collection, and the attribute _rev contains the new document revision.

If the query parameter returnOld is true, then the complete previous revision of the document is returned under the old attribute in the result.

If the query parameter returnNew is true, then the complete new document is returned under the new attribute in the result.

If the document does not exist, then a HTTP 404 is returned and the body of the response contains an error document.

Example:

Using a document handle

shell> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/document/products/10001 <<EOF
{"Hello": "you"}
EOF

HTTP/1.1 202 Accepted
content-type: application/json; charset=utf-8
etag: "_VTxTBxq--_"
x-content-type-options: nosniff
location: /_db/_system/_api/document/products/10001

{ 
  "_id" : "products/10001", 
  "_key" : "10001", 
  "_rev" : "_VTxTBxq--_", 
  "_oldRev" : "_VTxTBxq---" 
}

Example:

Unknown document handle

shell> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/document/products/10021 <<EOF
{}
EOF

HTTP/1.1 404 Not Found
content-type: application/json; charset=utf-8
x-content-type-options: nosniff

{ 
  "error" : true, 
  "errorMessage" : "document not found", 
  "code" : 404, 
  "errorNum" : 1202 
}

Example:

Produce a revision conflict

shell> curl -X PUT --header 'If-Match: "_VTxTBza---"' --data-binary @- --dump - http://localhost:8529/_api/document/products/10010 <<EOF
{"other":"content"}
EOF

HTTP/1.1 412 Precondition Failed
content-type: application/json; charset=utf-8
etag: "_VTxTBzW---"
x-content-type-options: nosniff

{ 
  "error" : true, 
  "code" : 412, 
  "errorNum" : 1200, 
  "errorMessage" : "precondition failed", 
  "_id" : "products/10010", 
  "_key" : "10010", 
  "_rev" : "_VTxTBzW---" 
}

Return Codes

  • 201: is returned if the document was replaced successfully and waitForSync was true.
  • 202: is returned if the document was replaced successfully and waitForSync was false.
  • 400: is returned if the body does not contain a valid JSON representation of a document. The response body contains an error document in this case.
  • 404: is returned if the collection or the document was not found.
  • 412: is returned if the precondition was violated. The response will also contain the found documents' current revisions in the _rev attributes. Additionally, the attributes _id and _key will be returned.

Examples

Using a document handle

shell> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/document/products/10001 <<EOF
{"Hello": "you"}
EOF

HTTP/1.1 202 Accepted
content-type: application/json; charset=utf-8
etag: "_VTxTBxq--_"
x-content-type-options: nosniff
location: /_db/_system/_api/document/products/10001
show response body

Unknown document handle

shell> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/document/products/10021 <<EOF
{}
EOF

HTTP/1.1 404 Not Found
content-type: application/json; charset=utf-8
x-content-type-options: nosniff
show response body

Produce a revision conflict

shell> curl -X PUT --header 'If-Match: "_VTxTBza---"' --data-binary @- --dump - http://localhost:8529/_api/document/products/10010 <<EOF
{"other":"content"}
EOF

HTTP/1.1 412 Precondition Failed
content-type: application/json; charset=utf-8
etag: "_VTxTBzW---"
x-content-type-options: nosniff
show response body

Changes in 3.0 from 2.8:

There are quite some changes in this in comparison to Version 2.8, but few break existing usage:

  • the rev query parameter is gone (was duplication of If-Match)
  • the policy query parameter is gone (was non-sensical)
  • the ignoreRevs query parameter is new, the default true gives the traditional behavior as in 2.8
  • the returnNew and returnOld query parameters are new

There should be very few changes to behavior happening in real-world situations or drivers. Essentially, one has to replace usage of the rev query parameter by usage of the If-Match header. The non-sensical combination of If-Match given and policy=last no longer works, but can easily be achieved by leaving out the If-Match header.

The collection name should now be specified in the URL path. The old way with the URL path /_api/document and the required query parameter collection still works.

Replace documents

replaces multiple documents

PUT /_api/document/{collection}

Request Body (required)

A JSON representation of an array of documents.

Path Parameters

  • collection (required): This URL parameter is the name of the collection in which the documents are replaced.

Query Parameters

  • waitForSync (optional): Wait until the new documents have been synced to disk.
  • ignoreRevs (optional): By default, or if this is set to true, the _rev attributes in the given documents are ignored. If this is set to false, then any _rev attribute given in a body document is taken as a precondition. The document is only replaced if the current revision is the one specified.
  • returnOld (optional): Return additionally the complete previous revision of the changed documents under the attribute old in the result.
  • returnNew (optional): Return additionally the complete new documents under the attribute new in the result.

Replaces multiple documents in the specified collection with the ones in the body, the replaced documents are specified by the _key attributes in the body documents.

If ignoreRevs is false and there is a _rev attribute in a document in the body and its value does not match the revision of the corresponding document in the database, the precondition is violated.

If the document exists and can be updated, then an HTTP 201 or an HTTP 202 is returned (depending on waitForSync, see below).

Optionally, the query parameter waitForSync can be used to force synchronization of the document replacement operation to disk even in case that the waitForSync flag had been disabled for the entire collection. Thus, the waitForSync query parameter can be used to force synchronization of just specific operations. To use this, set the waitForSync parameter to true. If the waitForSync parameter is not specified or set to false, then the collection's default waitForSync behavior is applied. The waitForSync query parameter cannot be used to disable synchronization for collections that have a default waitForSync value of true.

The body of the response contains a JSON array of the same length as the input array with the information about the handle and the revision of the replaced documents. In each entry, the attribute _id contains the known document-handle of each updated document, _key contains the key which uniquely identifies a document in a given collection, and the attribute _rev contains the new document revision. In case of an error or violated precondition, an error object with the attribute error set to true and the attribute errorCode set to the error code is built.

If the query parameter returnOld is true, then, for each generated document, the complete previous revision of the document is returned under the old attribute in the result.

If the query parameter returnNew is true, then, for each generated document, the complete new document is returned under the new attribute in the result.

Note that if any precondition is violated or an error occurred with some of the documents, the return code is still 201 or 202, but the additional HTTP header X-Arango-Error-Codes is set, which contains a map of the error codes that occurred together with their multiplicities, as in: 1200:17,1205:10 which means that in 17 cases the error 1200 "revision conflict" and in 10 cases the error 1205 "illegal document handle" has happened.

Return Codes

  • 201: is returned if the documents were replaced successfully and waitForSync was true.
  • 202: is returned if the documents were replaced successfully and waitForSync was false.
  • 400: is returned if the body does not contain a valid JSON representation of an array of documents. The response body contains an error document in this case.
  • 404: is returned if the collection was not found.

    Changes in 3.0 from 2.8:

The multi document version is new in 3.0.

Update document

updates a document

PATCH /_api/document/{document-handle}

Request Body (required)

A JSON representation of a document update as an object.

Path Parameters

  • document-handle (required): This URL parameter must be a document handle.

Query Parameters

  • keepNull (optional): If the intention is to delete existing attributes with the patch command, the URL query parameter keepNull can be used with a value of false. This will modify the behavior of the patch command to remove any attributes from the existing document that are contained in the patch document with an attribute value of null.
  • mergeObjects (optional): Controls whether objects (not arrays) will be merged if present in both the existing and the patch document. If set to false, the value in the patch document will overwrite the existing document's value. If set to true, objects will be merged. The default is true.
  • waitForSync (optional): Wait until document has been synced to disk.
  • ignoreRevs (optional): By default, or if this is set to true, the _rev attributes in the given document is ignored. If this is set to false, then the _rev attribute given in the body document is taken as a precondition. The document is only updated if the current revision is the one specified.
  • returnOld (optional): Return additionally the complete previous revision of the changed document under the attribute old in the result.
  • returnNew (optional): Return additionally the complete new document under the attribute new in the result.
  • silent (optional): If set to true, an empty object will be returned as response. No meta-data will be returned for the updated document. This option can be used to save some network traffic.

Header Parameters

  • If-Match (optional): You can conditionally update a document based on a target revision id by using the if-match HTTP header.

Partially updates the document identified by document-handle. The body of the request must contain a JSON document with the attributes to patch (the patch document). All attributes from the patch document will be added to the existing document if they do not yet exist, and overwritten in the existing document if they do exist there.

Setting an attribute value to null in the patch document will cause a value of null to be saved for the attribute by default.

If the If-Match header is specified and the revision of the document in the database is unequal to the given revision, the precondition is violated.

If If-Match is not given and ignoreRevs is false and there is a _rev attribute in the body and its value does not match the revision of the document in the database, the precondition is violated.

If a precondition is violated, an HTTP 412 is returned.

If the document exists and can be updated, then an HTTP 201 or an HTTP 202 is returned (depending on waitForSync, see below), the ETag header field contains the new revision of the document and the Location header contains a complete URL under which the document can be queried.

Optionally, the query parameter waitForSync can be used to force synchronization of the updated document operation to disk even in case that the waitForSync flag had been disabled for the entire collection. Thus, the waitForSync query parameter can be used to force synchronization of just specific operations. To use this, set the waitForSync parameter to true. If the waitForSync parameter is not specified or set to false, then the collection's default waitForSync behavior is applied. The waitForSync query parameter cannot be used to disable synchronization for collections that have a default waitForSync value of true.

If silent is not set to true, the body of the response contains a JSON object with the information about the handle and the revision. The attribute _id contains the known document-handle of the updated document, _key contains the key which uniquely identifies a document in a given collection, and the attribute _rev contains the new document revision.

If the query parameter returnOld is true, then the complete previous revision of the document is returned under the old attribute in the result.

If the query parameter returnNew is true, then the complete new document is returned under the new attribute in the result.

If the document does not exist, then a HTTP 404 is returned and the body of the response contains an error document.

Example:

Patches an existing document with new content.

shell> curl -X PATCH --data-binary @- --dump - http://localhost:8529/_api/document/products/9876 <<EOF
{ 
  "hello" : "world" 
}
EOF

HTTP/1.1 202 Accepted
content-type: application/json; charset=utf-8
etag: "_VTxTBX2--_"
x-content-type-options: nosniff
location: /_db/_system/_api/document/products/9876

{ 
  "_id" : "products/9876", 
  "_key" : "9876", 
  "_rev" : "_VTxTBX2--_", 
  "_oldRev" : "_VTxTBX2---" 
}
shell> curl -X PATCH --data-binary @- --dump - http://localhost:8529/_api/document/products/9876 <<EOF
{ 
  "numbers" : { 
    "one" : 1, 
    "two" : 2, 
    "three" : 3, 
    "empty" : null 
  } 
}
EOF

HTTP/1.1 202 Accepted
content-type: application/json; charset=utf-8
etag: "_VTxTBY----"
x-content-type-options: nosniff
location: /_db/_system/_api/document/products/9876

{ 
  "_id" : "products/9876", 
  "_key" : "9876", 
  "_rev" : "_VTxTBY----", 
  "_oldRev" : "_VTxTBX2--_" 
}
shell> curl --dump - http://localhost:8529/_api/document/products/9876

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
etag: "_VTxTBY----"
x-content-type-options: nosniff

{ 
  "_key" : "9876", 
  "_id" : "products/9876", 
  "_rev" : "_VTxTBY----", 
  "one" : "world", 
  "hello" : "world", 
  "numbers" : { 
    "one" : 1, 
    "two" : 2, 
    "three" : 3, 
    "empty" : null 
  } 
}
shell> curl -X PATCH --data-binary @- --dump - http://localhost:8529/_api/document/products/9876?keepNull=false <<EOF
{ 
  "hello" : null, 
  "numbers" : { 
    "four" : 4 
  } 
}
EOF

HTTP/1.1 202 Accepted
content-type: application/json; charset=utf-8
etag: "_VTxTBYC---"
x-content-type-options: nosniff
location: /_db/_system/_api/document/products/9876

{ 
  "_id" : "products/9876", 
  "_key" : "9876", 
  "_rev" : "_VTxTBYC---", 
  "_oldRev" : "_VTxTBY----" 
}
shell> curl --dump - http://localhost:8529/_api/document/products/9876

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
etag: "_VTxTBYC---"
x-content-type-options: nosniff

{ 
  "_key" : "9876", 
  "_id" : "products/9876", 
  "_rev" : "_VTxTBYC---", 
  "one" : "world", 
  "numbers" : { 
    "empty" : null, 
    "one" : 1, 
    "three" : 3, 
    "two" : 2, 
    "four" : 4 
  } 
}

Example:

Merging attributes of an object using mergeObjects:

shell> curl --dump - http://localhost:8529/_api/document/products/9891

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
etag: "_VTxTBZS---"
x-content-type-options: nosniff

{ 
  "_key" : "9891", 
  "_id" : "products/9891", 
  "_rev" : "_VTxTBZS---", 
  "inhabitants" : { 
    "china" : 1366980000, 
    "india" : 1263590000, 
    "usa" : 319220000 
  } 
}
shell> curl -X PATCH --data-binary @- --dump - http://localhost:8529/_api/document/products/9891?mergeObjects=true <<EOF
{ 
  "inhabitants" : { 
    "indonesia" : 252164800, 
    "brazil" : 203553000 
  } 
}
EOF

shell> curl --dump - http://localhost:8529/_api/document/products/9891

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
etag: "_VTxTBZW---"
x-content-type-options: nosniff

{ 
  "_key" : "9891", 
  "_id" : "products/9891", 
  "_rev" : "_VTxTBZW---", 
  "inhabitants" : { 
    "china" : 1366980000, 
    "india" : 1263590000, 
    "usa" : 319220000, 
    "indonesia" : 252164800, 
    "brazil" : 203553000 
  } 
}
shell> curl -X PATCH --data-binary @- --dump - http://localhost:8529/_api/document/products/9891?mergeObjects=false <<EOF
{ 
  "inhabitants" : { 
    "pakistan" : 188346000 
  } 
}
EOF

HTTP/1.1 202 Accepted
content-type: application/json; charset=utf-8
etag: "_VTxTBZi---"
x-content-type-options: nosniff
location: /_db/_system/_api/document/products/9891

{ 
  "_id" : "products/9891", 
  "_key" : "9891", 
  "_rev" : "_VTxTBZi---", 
  "_oldRev" : "_VTxTBZW---" 
}
shell> curl --dump - http://localhost:8529/_api/document/products/9891

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
etag: "_VTxTBZi---"
x-content-type-options: nosniff

{ 
  "_key" : "9891", 
  "_id" : "products/9891", 
  "_rev" : "_VTxTBZi---", 
  "inhabitants" : { 
    "pakistan" : 188346000 
  } 
}

Return Codes

  • 201: is returned if the document was updated successfully and waitForSync was true.
  • 202: is returned if the document was updated successfully and waitForSync was false.
  • 400: is returned if the body does not contain a valid JSON representation of a document. The response body contains an error document in this case.
  • 404: is returned if the collection or the document was not found.
  • 412: is returned if the precondition was violated. The response will also contain the found documents' current revisions in the _rev attributes. Additionally, the attributes _id and _key will be returned.

Examples

Patches an existing document with new content.

shell> curl -X PATCH --data-binary @- --dump - http://localhost:8529/_api/document/products/9876 <<EOF
{ 
  "hello" : "world" 
}
EOF

HTTP/1.1 202 Accepted
content-type: application/json; charset=utf-8
etag: "_VTxTBX2--_"
x-content-type-options: nosniff
location: /_db/_system/_api/document/products/9876
show response body

Merging attributes of an object using mergeObjects:

shell> curl --dump - http://localhost:8529/_api/document/products/9891

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
etag: "_VTxTBZS---"
x-content-type-options: nosniff
show response body

Changes in 3.0 from 2.8:

There are quite some changes in this in comparison to Version 2.8, but few break existing usage:

  • the rev query parameter is gone (was duplication of If-Match)
  • the policy query parameter is gone (was non-sensical)
  • the ignoreRevs query parameter is new, the default true gives the traditional behavior as in 2.8
  • the returnNew and returnOld query parameters are new

There should be very few changes to behavior happening in real-world situations or drivers. Essentially, one has to replace usage of the rev query parameter by usage of the If-Match header. The non-sensical combination of If-Match given and policy=last no longer works, but can easily be achieved by leaving out the If-Match header.

The collection name should now be specified in the URL path. The old way with the URL path /_api/document and the required query parameter collection still works.

Update documents

updates multiple documents

PATCH /_api/document/{collection}

Request Body (required)

A JSON representation of an array of document updates as objects.

Path Parameters

  • collection (required): This URL parameter is the name of the collection in which the documents are updated.

Query Parameters

  • keepNull (optional): If the intention is to delete existing attributes with the patch command, the URL query parameter keepNull can be used with a value of false. This will modify the behavior of the patch command to remove any attributes from the existing document that are contained in the patch document with an attribute value of null.
  • mergeObjects (optional): Controls whether objects (not arrays) will be merged if present in both the existing and the patch document. If set to false, the value in the patch document will overwrite the existing document's value. If set to true, objects will be merged. The default is true.
  • waitForSync (optional): Wait until the new documents have been synced to disk.
  • ignoreRevs (optional): By default, or if this is set to true, the _rev attributes in the given documents are ignored. If this is set to false, then any _rev attribute given in a body document is taken as a precondition. The document is only updated if the current revision is the one specified.
  • returnOld (optional): Return additionally the complete previous revision of the changed documents under the attribute old in the result.
  • returnNew (optional): Return additionally the complete new documents under the attribute new in the result.

Partially updates documents, the documents to update are specified by the _key attributes in the body objects. The body of the request must contain a JSON array of document updates with the attributes to patch (the patch documents). All attributes from the patch documents will be added to the existing documents if they do not yet exist, and overwritten in the existing documents if they do exist there.

Setting an attribute value to null in the patch documents will cause a value of null to be saved for the attribute by default.

If ignoreRevs is false and there is a _rev attribute in a document in the body and its value does not match the revision of the corresponding document in the database, the precondition is violated.

If the document exists and can be updated, then an HTTP 201 or an HTTP 202 is returned (depending on waitForSync, see below).

Optionally, the query parameter waitForSync can be used to force synchronization of the document replacement operation to disk even in case that the waitForSync flag had been disabled for the entire collection. Thus, the waitForSync query parameter can be used to force synchronization of just specific operations. To use this, set the waitForSync parameter to true. If the waitForSync parameter is not specified or set to false, then the collection's default waitForSync behavior is applied. The waitForSync query parameter cannot be used to disable synchronization for collections that have a default waitForSync value of true.

The body of the response contains a JSON array of the same length as the input array with the information about the handle and the revision of the updated documents. In each entry, the attribute _id contains the known document-handle of each updated document, _key contains the key which uniquely identifies a document in a given collection, and the attribute _rev contains the new document revision. In case of an error or violated precondition, an error object with the attribute error set to true and the attribute errorCode set to the error code is built.

If the query parameter returnOld is true, then, for each generated document, the complete previous revision of the document is returned under the old attribute in the result.

If the query parameter returnNew is true, then, for each generated document, the complete new document is returned under the new attribute in the result.

Note that if any precondition is violated or an error occurred with some of the documents, the return code is still 201 or 202, but the additional HTTP header X-Arango-Error-Codes is set, which contains a map of the error codes that occurred together with their multiplicities, as in: 1200:17,1205:10 which means that in 17 cases the error 1200 "revision conflict" and in 10 cases the error 1205 "illegal document handle" has happened.

Return Codes

  • 201: is returned if the documents were updated successfully and waitForSync was true.
  • 202: is returned if the documents were updated successfully and waitForSync was false.
  • 400: is returned if the body does not contain a valid JSON representation of an array of documents. The response body contains an error document in this case.
  • 404: is returned if the collection was not found.

    Changes in 3.0 from 2.8:

The multi document version is new in 3.0.

Removes a document

removes a document

DELETE /_api/document/{document-handle}

Path Parameters

  • document-handle (required): Removes the document identified by document-handle.

Query Parameters

  • waitForSync (optional): Wait until deletion operation has been synced to disk.
  • returnOld (optional): Return additionally the complete previous revision of the changed document under the attribute old in the result.
  • silent (optional): If set to true, an empty object will be returned as response. No meta-data will be returned for the removed document. This option can be used to save some network traffic.

Header Parameters

  • If-Match (optional): You can conditionally remove a document based on a target revision id by using the if-match HTTP header.

If silent is not set to true, the body of the response contains a JSON object with the information about the handle and the revision. The attribute _id contains the known document-handle of the removed document, _key contains the key which uniquely identifies a document in a given collection, and the attribute _rev contains the document revision.

If the waitForSync parameter is not specified or set to false, then the collection's default waitForSync behavior is applied. The waitForSync query parameter cannot be used to disable synchronization for collections that have a default waitForSync value of true.

If the query parameter returnOld is true, then the complete previous revision of the document is returned under the old attribute in the result.

Example:

Using document handle:

shell> curl -X DELETE --dump - http://localhost:8529/_api/document/products/9816

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
etag: "_VTxTBDW---"
x-content-type-options: nosniff
location: /_db/_system/_api/document/products/9816

{ 
  "_id" : "products/9816", 
  "_key" : "9816", 
  "_rev" : "_VTxTBDW---" 
}

Example:

Unknown document handle:

shell> curl -X DELETE --dump - http://localhost:8529/_api/document/products/9856

HTTP/1.1 404 Not Found
content-type: application/json; charset=utf-8
x-content-type-options: nosniff

{ 
  "error" : true, 
  "errorMessage" : "document not found", 
  "code" : 404, 
  "errorNum" : 1202 
}

Example:

Revision conflict:

shell> curl -X DELETE --header 'If-Match: "_VTxTBHK--_"' --dump - http://localhost:8529/_api/document/products/9825

HTTP/1.1 412 Precondition Failed
content-type: application/json; charset=utf-8
etag: "_VTxTBHK---"
x-content-type-options: nosniff

{ 
  "error" : true, 
  "code" : 412, 
  "errorNum" : 1200, 
  "errorMessage" : "precondition failed", 
  "_id" : "products/9825", 
  "_key" : "9825", 
  "_rev" : "_VTxTBHK---" 
}

Return Codes

  • 200: is returned if the document was removed successfully and waitForSync was true.
  • 202: is returned if the document was removed successfully and waitForSync was false.
  • 404: is returned if the collection or the document was not found. The response body contains an error document in this case.
  • 412: is returned if a "If-Match" header or rev is given and the found document has a different version. The response will also contain the found document's current revision in the _rev attribute. Additionally, the attributes _id and _key will be returned.

Examples

Using document handle:

shell> curl -X DELETE --dump - http://localhost:8529/_api/document/products/9816

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
etag: "_VTxTBDW---"
x-content-type-options: nosniff
location: /_db/_system/_api/document/products/9816
show response body

Unknown document handle:

shell> curl -X DELETE --dump - http://localhost:8529/_api/document/products/9856

HTTP/1.1 404 Not Found
content-type: application/json; charset=utf-8
x-content-type-options: nosniff
show response body

Revision conflict:

shell> curl -X DELETE --header 'If-Match: "_VTxTBHK--_"' --dump - http://localhost:8529/_api/document/products/9825

HTTP/1.1 412 Precondition Failed
content-type: application/json; charset=utf-8
etag: "_VTxTBHK---"
x-content-type-options: nosniff
show response body

Changes in 3.0 from 2.8:

There are only very few changes in this in comparison to Version 2.8:

  • the rev query parameter is gone (was duplication of If-Match)
  • the policy query parameter is gone (was non-sensical)
  • the returnOld query parameter is new

There should be very few changes to behavior happening in real-world situations or drivers. Essentially, one has to replace usage of the rev query parameter by usage of the If-Match header. The non-sensical combination of If-Match given and policy=last no longer works, but can easily be achieved by leaving out the If-Match header.

Removes multiple documents

removes multiple document

DELETE /_api/document/{collection}

Request Body (required)

A JSON array of strings or documents.

Path Parameters

  • collection (required): Collection from which documents are removed.

Query Parameters

  • waitForSync (optional): Wait until deletion operation has been synced to disk.
  • returnOld (optional): Return additionally the complete previous revision of the changed document under the attribute old in the result.
  • ignoreRevs (optional): If set to true, ignore any _rev attribute in the selectors. No revision check is performed.

The body of the request is an array consisting of selectors for documents. A selector can either be a string with a key or a string with a document handle or an object with a _key attribute. This API call removes all specified documents from collection. If the selector is an object and has a _rev attribute, it is a precondition that the actual revision of the removed document in the collection is the specified one.

The body of the response is an array of the same length as the input array. For each input selector, the output contains a JSON object with the information about the outcome of the operation. If no error occurred, an object is built in which the attribute _id contains the known document-handle of the removed document, _key contains the key which uniquely identifies a document in a given collection, and the attribute _rev contains the document revision. In case of an error, an object with the attribute error set to true and errorCode set to the error code is built.

If the waitForSync parameter is not specified or set to false, then the collection's default waitForSync behavior is applied. The waitForSync query parameter cannot be used to disable synchronization for collections that have a default waitForSync value of true.

If the query parameter returnOld is true, then the complete previous revision of the document is returned under the old attribute in the result.

Note that if any precondition is violated or an error occurred with some of the documents, the return code is still 200 or 202, but the additional HTTP header X-Arango-Error-Codes is set, which contains a map of the error codes that occurred together with their multiplicities, as in: 1200:17,1205:10 which means that in 17 cases the error 1200 "revision conflict" and in 10 cases the error 1205 "illegal document handle" has happened.

Example:

Using document handle:

shell> curl -X DELETE --dump - http://localhost:8529/_api/document/products/9847

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
etag: "_VTxTBMG---"
x-content-type-options: nosniff
location: /_db/_system/_api/document/products/9847

{ 
  "_id" : "products/9847", 
  "_key" : "9847", 
  "_rev" : "_VTxTBMG---" 
}

Example:

Unknown document handle:

shell> curl -X DELETE --dump - http://localhost:8529/_api/document/products/9866

HTTP/1.1 404 Not Found
content-type: application/json; charset=utf-8
x-content-type-options: nosniff

{ 
  "error" : true, 
  "errorMessage" : "document not found", 
  "code" : 404, 
  "errorNum" : 1202 
}

Example:

Revision conflict:

shell> curl -X DELETE --header 'If-Match: "_VTxTBKG--_"' --dump - http://localhost:8529/_api/document/products/9836

HTTP/1.1 412 Precondition Failed
content-type: application/json; charset=utf-8
etag: "_VTxTBKG---"
x-content-type-options: nosniff

{ 
  "error" : true, 
  "code" : 412, 
  "errorNum" : 1200, 
  "errorMessage" : "precondition failed", 
  "_id" : "products/9836", 
  "_key" : "9836", 
  "_rev" : "_VTxTBKG---" 
}

Return Codes

  • 200: is returned if waitForSync was true.
  • 202: is returned if waitForSync was false.
  • 404: is returned if the collection was not found. The response body contains an error document in this case.

Examples

Using document handle:

shell> curl -X DELETE --dump - http://localhost:8529/_api/document/products/9847

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
etag: "_VTxTBMG---"
x-content-type-options: nosniff
location: /_db/_system/_api/document/products/9847
show response body

Unknown document handle:

shell> curl -X DELETE --dump - http://localhost:8529/_api/document/products/9866

HTTP/1.1 404 Not Found
content-type: application/json; charset=utf-8
x-content-type-options: nosniff
show response body

Revision conflict:

shell> curl -X DELETE --header 'If-Match: "_VTxTBKG--_"' --dump - http://localhost:8529/_api/document/products/9836

HTTP/1.1 412 Precondition Failed
content-type: application/json; charset=utf-8
etag: "_VTxTBKG---"
x-content-type-options: nosniff
show response body

Changes in 3.0 from 2.8:

This variant is new in 3.0. Note that it requires a body in the DELETE request.

© ArangoDB - the native multi-model NoSQL database