ArangoDB Manual Pages


REST Interface for Documents

Documents, Identifiers, Handles

This is an introduction to ArangoDB's REST interface for documents.

Document: Documents in ArangoDB are JSON objects. These objects can be nested (to any depth) and may contains lists. Each document is uniquely identified by its document handle.

For example:

{
  "_id" : "1234567/2345678",
  "_rev" : "3456789",
  "firstName" : "Hugo",
  "lastName" : "Schlonz",
  "address" : {
    "street" : "Strasse 1",
    "city" : "Hier"
  },
  "hobbies" : [
    "swimming",
    "biking",
    "programming"
  ]
}

All documents contain special attributes: the document handle in _id, the document's unique key in _key and and the etag aka document revision in _rev. The value of the _key attribute can be specified by the user when creating a document. _id and _key values are immutable once the document has been created. The _rev value is maintained by ArangoDB autonomously.

Document Handle: A document handle uniquely identifies a document in the database. It is a string and consists of a collection name and a document key separated by /.

Document Key: A document key uniquely identifies a document in a given collection. It can and should be used by clients when specific documents are searched. Document keys are stored in the _key attribute of documents. The key values are automatically indexed by ArangoDB so looking up a document by its key is regularly a fast operation. The _key value of a document is immutable once the document has been created.By default, ArangoDB will auto-generate a document key if no _key attribute is specified, and use the user-specified _key otherwise.This behavior can be changed on a per-collection level by creating collections with the keyOptions attribute.Using keyOptions it is possible to disallow user-specified keys completely, or to force a specific regime for auto-generating the _key values.

Document Revision: As ArangoDB supports MVCC, documents can exist in more than one revision. The document revision is the MVCC token used to identify a particular revision of a document. It is a string value currently containing an integer number and is unique within the list of document revisions for a single document. Document revisions can be used to conditionally update, replace or delete documents in the database. In order to find a particular revision of a document, you need the document handle and the document revision.ArangoDB currently uses 64bit unsigned integer values to maintain document revisions internally. When returning document revisions to clients, ArangoDB will put them into a string to ensure the revision id is not clipped by clients that do not support big integers. Clients should treat the revision id returned by ArangoDB as an opaque string when they store or use it locally. This will allow ArangoDB to change the format of revision ids later if this should be required. Clients can use revisions ids to perform simple equality/non-equality comparisons (e.g. to check whether a document has changed or not), but they should not use revision ids to perform greater/less than comparisions with them to check if a document revision is older than one another, even if this might work for some cases.Note: revision ids have been returned as integers up to including ArangoDB 1.1

Document Etag: The document revision enclosed in double quotes. The revision is returned by several HTTP API methods in the Etag HTTP header.

The basic operations (create, read, update, delete) for documents are mapped to the standard HTTP methods (POST, GET, PUT, DELETE). There is also a partial update method, which is mapped to the HTTP PATCH method.

An identifier for the document revision is returned in the ETag header field. If you modify a document, you can use the If-Match field to detect conflicts. The revision of a document can be checking using the HTTP method HEAD.

Address and ETag of a Document

All documents in ArangoDB have a document handle. This handle uniquely defines a document and is managed by ArangoDB. All documents are found under the URI:

http://server:port/_api/document/document-handle

For example: Assume that the document handle, which is stored in the _id attribute of the document, is demo/362549736, then the URL of that document is:

http://localhost:8529/_api/document/demo/362549736

Each document also has a document revision or etag with is returned in the "ETag" header field when requesting a document.

If you obtain a document using GET and you want to check if a newer revision is available, then you can use the If-None-Match header. If the document is unchanged, a HTTP 412 is returned.

If you want to update or delete a document, then you can use the If-Match header. If the document has changed, then the operation is aborted and a HTTP 412 is returned.

Working with Documents using REST

GET /_api/document
(reads a document)
GET /_api/document/document-handle
Returns the document identified by document-handle. The returned document contains two special attributes: _id containing the document handle and _rev containing the revision.If the document exists, then a HTTP 200 is returned and the JSON representation of the document is the body of the response.If the document-handle points to a non-existing document, then a HTTP 404 is returned and the body contains an error document.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 a HTTP 304 is returned.If the "If-Match" header is given, then it must contain exactly one etag. The document is returned, if it has the same revision ad the given etag. Otherwise a HTTP 412 is returned. As an alternative you can supply the etag in an attribute rev in the URL.
Examples
Use a document handle:
> curl -X GET --dump - http://localhost:8529/_api/document/73482/28411694

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
etag: "28411694"

{
  "_rev": "28411694",
  "_id": "73482/28411694",
  "Hello": "World"
}
Use a document handle and an etag:
> curl -X GET '-H if-none-match: "28542766"' --dump - http://localhost:8529/_api/document/73482/28542766

HTTP/1.1 304 Not Modified
content-type: text/plain;charset=utf-8
etag: "28542766"
Unknown document handle:
> curl -X GET --dump - http://localhost:8529/_api/document/73482/234567

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

{
  "errorMessage": "document /_api/document/73482/234567 not found",
  "errorNum": 1202,
  "code": 404,
  "error": true
}

POST /_api/document
(creates a document)
POST /_api/document?collection=collection-name
Creates a new document in the collection identified by collection-name. A JSON representation of the document must be passed as the body of the POST request.If the document was created successfully, then a HTTP 201 is returned and 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 same information. The attribute _id contains the document handle of the newly created document, the attribute _rev contains the document revision.If the collection parameter waitForSync is false, then a HTTP 202 is returned in order to indicate that the document has been accepted but not yet stored.Optionally, the URL parameter waitForSync can be used to force synchronisation of the document creation operation to disk even in case that the waitForSync flag had been disabled for the entire collection. Thus, the waitForSync URL parameter can be used to force synchronisation 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 URL parameter cannot be used to disable synchronisation for collections that have a default waitForSync value of true.If the collection specified by collection-name is unknown, then a HTTP 404 is returned and the body of the response contains an error document.If the body does not contain a valid JSON representation of a document, then a HTTP 400 is returned and the body of the response contains an error document.
POST /_api/document?collection=collection-name&createCollection= create-flag
If create-flag has a value of true or yes, then the collection is created if it does not yet exist. Other values for create-flag will be ignored so the collection must be present for the operation to succeed.
Examples
Create a document given a collection identifier 161039 for the collection named demo. Note that the revision identifier might or might by equal to the last part of the document handle. It generally will be equal, but there is no guaranty.
> curl --data @- -X POST --dump - http://localhost:8529/_api/document?collection=73482
{ "Hello" : "World" }

HTTP/1.1 201 Created
content-type: application/json; charset=utf-8
etag: "26445614"

{
  "_rev": "26445614",
  "_id": "73482/26445614",
  "error": false
}
Create a document in a collection with a collection-level waitForSync value of false.
> curl --data @- -X POST --dump - http://localhost:8529/_api/document?collection=2957066
{ "Hello" : "World" }

HTTP/1.1 202 Accepted
content-type: application/json; charset=utf-8
etag: "26576686"

{
  "_rev": "26576686",
  "_id": "2957066/26576686",
  "error": false
}
Create a document in a collection with a collection-level waitForSync value of false, but with using waitForSync URL parameter.
> curl --data @- -X POST --dump - http://localhost:8529/_api/document?collection=2957066&waitForSync=true
{ "Hello" : "World" }

HTTP/1.1 201 Created
content-type: application/json; charset=utf-8
etag: "26449614"

{
  "_rev": "26449614",
  "_id": "2957066/26449614",
  "error": false
}
Create a document in a known, named collection
> curl --data @- -X POST --dump - http://localhost:8529/_api/document?collection=example
{ "Hello" : "World" }

HTTP/1.1 201 Created
content-type: application/json; charset=utf-8
etag: "26707758"

{
  "_rev": "26707758",
  "_id": "73482/26707758",
  "error": false
}
Create a document in a new, named collection
> curl --data @- -X POST --dump - http://localhost:8529/_api/document?collection=example&createCollection=true
{ "Hello" : "World" }

HTTP/1.1 202 Accepted
content-type: application/json; charset=utf-8
etag: "28280622"

{
  "_rev": "28280622",
  "_id": "26838830/28280622",
  "error": false
}
Unknown collection identifier:
> curl --data @- -X POST --dump - http://localhost:8529/_api/document?collection=123456
{}

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

{
  "errorMessage": "collection /_api/collection/123456 not found",
  "errorNum": 1203,
  "code": 404,
  "error": true
}
Illegal document:
> curl --data @- -X POST --dump - http://localhost:8529/_api/document?collection=73482
{ 1 : 2 }

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

{
  "errorMessage": "expecting attribute name",
  "errorNum": 600,
  "code": 400,
  "error": true
}

PUT /_api/document
(replaces a document)
PUT /_api/document/document-handle
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 URL parameter waitForSync can be used to force synchronisation of the document replacement operation to disk even in case that the waitForSync flag had been disabled for the entire collection. Thus, the waitForSync URL parameter can be used to force synchronisation 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 URL parameter cannot be used to disable synchronisation 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, 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 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 URL 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 the following request:
PUT /_api/document/document-handle?rev= etag
If a target revision id is provided in the request (e.g. via the etag value in the rev URL 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 409 conflict is returned and no replacement is performed. ArangoDB will return an HTTP 412 precondition failed response then.The conditional update behavior can be overriden with the policy URL parameter:
PUT /_api/document/document-handle?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.
Examples
Using document handle:
> curl --data @- -X PUT --dump - http://localhost:8529/_api/document/73482/29853486
{ "World" : "Hello" }

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

{
  "_rev": "29919022",
  "_id": "73482/29853486",
  "error": false
}
Unknown document handle:
> curl --data @- -X PUT --dump - http://localhost:8529/_api/document/73482/234567
{}

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

{
  "errorMessage": "document /_api/document/73482/234567 not found",
  "errorNum": 1202,
  "code": 404,
  "error": true
}
Produce a revision conflict:
> curl --data @- -X PUT '-H if-match: "30050093"' --dump - http://_api/localhost:8529/document/73482/30050094
{ "World" : "Hello" }

HTTP/1.1 412 Precondition Failed
content-type: application/json; charset=utf-8

{
  "_rev": "30050094",
  "_id": "73482/30050094",
  "error": true
}
Last write wins:
> curl --data @- -X PUT '-H if-match: "30246701"' --dump - http://localhost:8529/_api/document/73482/30246702?policy=last
{ "World" : "Hello" }

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

{
  "_rev": "30312238",
  "_id": "73482/30246702",
  "error": false
}
Alternative to header field:
> curl --data @- -X PUT --dump - http://localhost:8529/_api/document/73482/30443310?rev=30443309
{ "World" : "Hello" }

HTTP/1.1 412 Precondition Failed
content-type: application/json; charset=utf-8

{
  "_rev": "30443310",
  "_id": "73482/30443310",
  "error": true
}

PATCH /_api/document
(patches a document)
PATCH /_api/document/document-handle
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. If the intention is to delete existing attributes with the patch command, the URL 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.Optionally, the URL parameter waitForSync can be used to force synchronisation of the document update operation to disk even in case that the waitForSync flag had been disabled for the entire collection. Thus, the waitForSync URL parameter can be used to force synchronisation 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 URL parameter cannot be used to disable synchronisation 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, 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 URL 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).
Examples
> curl --data @- -X PATCH --dump - http://localhost:8529/_api/document/73482/7229681
{ "hello": "world" }

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

{
  "_rev": "11916057",
  "_id": "73482/7229681",
  "error": false
}

> curl --data @- -X PATCH --dump - http://localhost:8529/_api/document/73482/7229681
{ "numbers": { "one": 1, "two": 2, "three": 3, "empty": null } }

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

{
  "_rev": "12309273",
  "_id": "73482/7229681",
  "error": false
}

> curl -X GET --dump - http://localhost:8529/_api/document/73482/7229681
{ "numbers": { "one": 1, "two": 2, "three": 3, "empty": null } }

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

{
  "hello": "world",
  "numbers": {
    "empty": null,
    "one": 1,
    "two": 2,
    "three": 3
  },
  "_rev": "12309273",
  "_id": "73482/7229681"
}

> curl --data @- -X PATCH --dump - http://localhost:8529/_api/document/73482/7229681?keepNull=false
{ "hello": null, "numbers": { "four": 4 } }

{
  "_rev": "12571417",
  "_id": "73482/7229681",
  "error": false
}

> curl -X GET --dump - http://localhost:8529/_api/document/73482/7229681

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

{
  "numbers": {
    "empty": null,
    "one": 1,
    "two": 2,
    "three": 3,
    "four": 4,
  },
  "_rev": "12571417",
  "_id": "73482/7229681"
}

DELETE /_api/document
(deletes a document)
DELETE /_api/document/document-handle
Deletes the document identified by document-handle. If the document exists and could be deleted, then a HTTP 204 is returned.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, the attribute _rev contains the known 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 delete a document based on a target revision id by using either the rev URL 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 more details).Optionally, the URL parameter waitForSync can be used to force synchronisation of the document deletion operation to disk even in case that the waitForSync flag had been disabled for the entire collection. Thus, the waitForSync URL parameter can be used to force synchronisation 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 URL parameter cannot be used to disable synchronisation for collections that have a default waitForSync value of true.
Examples
Using document handle:
> curl -X DELETE --dump - http://localhost:8529/_api/document/73482/30967598

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

{
  "_rev": "30967598",
  "_id": "73482/30967598",
  "error": false
}
Unknown document handle:
> curl -X DELETE --dump - http://localhost:8529/_api/document/73482/234567

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

{
  "errorMessage": "document /_api/document/73482/234567 not found",
  "errorNum": 1202,
  "code": 404,
  "error": true
}
Revision conflict:
> curl -X DELETE '-H if-match: "31098669"' --dump - http://localhost:8529/_api/document/73482/31098670

HTTP/1.1 412 Precondition Failed
content-type: application/json; charset=utf-8

{
  "_rev": "31098670",
  "_id": "73482/31098670",
  "error": true
}

HEAD /_api/document
(reads a document header)
HEAD /_api/document/document-handle
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.
Examples
> curl -X HEAD --dump - http://localhost:8529/_api/document/73482/29591342

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
etag: "29591342"

GET /_api/document
(reads all document)
GET /_api/document?collection=collection-name
Returns a list of all URI for all documents from the collection identified by collection-name.
Examples
> curl -X GET --dump - http://localhost:8529/_api/document?collection=6627082

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

{
  "documents": [
    "/document/6627082/29198126",
    "/document/6627082/29329198",
    "/document/6627082/29263662"
  ]
}