ArangoDB v2.8 reached End of Life (EOL) and is no longer supported.

This documentation is outdated. Please see the most recent version here: Try latest

Working with Documents using REST

Read document

reads a single document

GET /_api/document/{collection-name}/{document-key}

Path Parameters

  • collection-name (required): The name of the collection.

  • document-key (required): The key 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. As an alternative you can supply the etag in an attribute rev in the URL.

    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.

    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 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
Use a document handle: 

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

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


Use a document handle and an etag: 

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


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
show response body

Create document

creates a document

POST /_api/document

Query Parameters

  • collection (required): The collection name.
  • createCollection (optional): If this parameter has a value of true or yes, then the collection is created if it does not yet exist. Other values will be ignored so the collection must be present for the operation to succeed.
    Note: this flag is not supported in a cluster. Using it will result in an error.
  • waitForSync (optional): Wait until document has been synced to disk.
    Request Body (json)

A JSON representation of the document.


Creates a new document in the collection named collection. A JSON representation of the document must be passed as the body of the POST request.
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.
The body of the response contains a JSON object with the following attributes:

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

  • _rev contains the document revision
    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 document has 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.

    Return codes

    • 201: is returned if the document was created successfully and waitForSync was true.

    • 202: is returned if the document was created 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 specified by collection is unknown. The response body contains an error document in this case.

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?collection=products <<EOF
{ "Hello": "World" }
EOF

HTTP/1.1 201 Created
content-type: application/json; charset=utf-8
etag: "727861377"
location: /_db/_system/_api/document/products/727861377
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?collection=products <<EOF
{ "Hello": "World" }
EOF

HTTP/1.1 202 Accepted
content-type: application/json; charset=utf-8
etag: "727337089"
location: /_db/_system/_api/document/products/727337089
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?collection=products&waitForSync=true <<EOF
{ "Hello": "World" }
EOF

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


Create a document in a new, named collection 

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

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


Unknown collection name 

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

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


Illegal document 

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

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

Replace document

replaces a document

PUT /_api/document/{collection-name}/{document-key}

Path Parameters

  • collection-name (required): The name of the collection.

  • document-key (required): The key of the document.
    Query Parameters

  • waitForSync (optional): Wait until document has been synced to disk.
  • rev (optional): You can conditionally replace a document based on a target revision id by using the rev query parameter.

  • policy (optional): To control the update behavior in case there is a revision mismatch, you can use the policy parameter (see below).
    Header Parameters

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

A JSON representation of the new document.




Completely updates (i.e. replaces) the document identified by document-handle. If the document exists and can be updated, then a HTTP 201 is returned and the “ETag” header field contains the new revision of the document.
If the new document passed in the body of the request contains the document-handle in the attribute _id and the revision in _rev, these attributes will be ignored. Only the URI and the “ETag” header are relevant in order to avoid confusion when using proxies.

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 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 document does not exist, then a HTTP 404 is returned and the body of the response contains an error document.
There are two ways for specifying the targeted document revision id for conditional replacements (i.e. replacements that will only be executed if the revision id found in the database matches the document revision id specified in the request):

  • specifying the target revision in the rev URL query parameter

  • specifying the target revision in the if-match HTTP header

    Specifying a target revision is optional, however, if done, only one of the described mechanisms must be used (either the rev query parameter or the if-match HTTP header). Regardless which mechanism is used, the parameter needs to contain the target document revision id as returned in the _rev attribute of a document or by an HTTP etag header.
    For example, to conditionally replace a document based on a specific revision id, you can use the following request:

    PUT /_api/document/collection-name/document-key?rev=etag

    If a target revision id is provided in the request (e.g. via the etag value in the rev URL query parameter above), ArangoDB will check that the revision id of the document found in the database is equal to the target revision id provided in the request. If there is a mismatch between the revision id, then by default a HTTP 412 conflict is returned and no replacement is performed.

    The conditional update behavior can be overridden with the policy URL query parameter:

    PUT /_api/document/collection-name/document-key?policy=policy

    If policy is set to error, then the behavior is as before: replacements will fail if the revision id found in the database does not match the target revision id specified in the request.
    If policy is set to last, then the replacement will succeed, even if the revision id found in the database does not match the target revision id specified in the request. You can use the last policy to force replacements.

    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 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 a document handle 

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

HTTP/1.1 202 Accepted
content-type: application/json; charset=utf-8
etag: "734021761"
location: /_db/_system/_api/document/products/733694081
show response body


Unknown document handle 

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

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


Produce a revision conflict 

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

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


Last write wins 

shell> curl -X PUT --header 'If-Match: "735987841"' --data-binary @- --dump - http://localhost:8529/_api/document/products/735660161?policy=last <<EOF
{}
EOF

HTTP/1.1 202 Accepted
content-type: application/json; charset=utf-8
etag: "736249985"
location: /_db/_system/_api/document/products/735660161
show response body


Alternative to header fields 

shell> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/document/products/736774273?rev=737101953 <<EOF
{"other":"content"}
EOF

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

Patch document

updates a document

PATCH /_api/document/{collection-name}/{document-key}

Path Parameters

  • collection-name (required): The name of the collection.

  • document-key (required): The key of the document.
    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.
  • rev (optional): You can conditionally patch a document based on a target revision id by using the rev query parameter.

  • policy (optional): To control the update behavior in case there is a revision mismatch, you can use the policy parameter.
    Header Parameters

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

A JSON representation of the document update.




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 be saved for the attribute by default.
Optionally, the query parameter waitForSync can be used to force synchronization of the document update 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 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 document does not exist, then a HTTP 404 is returned and the body of the response contains an error document.
You can conditionally update a document based on a target revision id by using either the rev query parameter or the if-match HTTP header. To control the update behavior in case there is a revision mismatch, you can use the policy parameter. This is the same as when replacing documents (see replacing documents for details).

Return codes

  • 201: is returned if the document was created successfully and waitForSync was true.

  • 202: is returned if the document was created 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 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
patches an existing document with new content. 

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

HTTP/1.1 202 Accepted
content-type: application/json; charset=utf-8
etag: "723863681"
location: /_db/_system/_api/document/products/723536001
show response body


Merging attributes of an object using mergeObjects: 

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

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

Removes a document

removes a document

DELETE /_api/document/{collection-name}/{document-key}

Path Parameters

  • collection-name (required): The name of the collection.

  • document-key (required): The key of the document.
    Query Parameters

  • rev (optional): You can conditionally remove a document based on a target revision id by using the rev query parameter.
  • policy (optional): To control the update behavior in case there is a revision mismatch, you can use the policy parameter. This is the same as when replacing documents (see replacing documents for more details).

  • waitForSync (optional): Wait until deletion operation has been synced to disk.
    Header Parameters

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


    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 new 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.

    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/720980097

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
show response body


Unknown document handle: 

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

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


Revision conflict: 

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

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

Read document header

reads a single document head

HEAD /_api/document/{collection-name}/{document-key}

Path Parameters

  • collection-name (required): The name of the collection.

  • document-key (required): The key of the document.
    Query Parameters

  • rev (optional): You can conditionally fetch a document based on a target revision id by using the rev query parameter.
    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 different 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): You can conditionally fetch a document based on a target revision id by using the if-match HTTP header.


    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.

    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 same version ///*

  • 404: is returned if the document or collection was not found

  • 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 etag header.

Examples 

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

Read all documents

reads all documents from collection

GET /_api/document

Query Parameters

  • collection (required): The name of the collection.
  • type (optional): 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.
    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.

    Return codes

    • 200: All went good.

    • 404: The collection does not exist.

Examples
Return all document paths 

shell> curl --dump - http://localhost:8529/_api/document/?collection=products

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
show response body


Return all document keys 

shell> curl --dump - http://localhost:8529/_api/document/?collection=products&type=key

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
show response body


Collection does not exist 

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

HTTP/1.1 404 Not Found
content-type: application/json; charset=utf-8
show response body
❮  Address and ETag

© ArangoDB - the native multi-model NoSQL database