ArangoDB Manual

This is an introduction to ArangoDB's interface for documents and how handle documents from the JavaScript shell arangosh. For other languages see the corresponding language API.

Handling Documents

Documents, Identifiers, Handles

Document: Documents in ArangoDB are JSON objects. These objects can be nested (to any depth) and may contains lists. Each document is unique 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 two special fields, the document handle in _id and the etag aka document revision in _rev.

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

Document Identifier: A document identifier identifies a document in a given collection. It is an integer and is unique within the collection of the document.

Document Revision: As AvocaodDB 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 an integer and unique within the list of document revision for a single document. Earlier revision of a document have smaller numbers. In order to find a particular revision of a document, you need the document handle and the document revision.

Document Etag: The document revision enclosed in double quotes.

Address and ETag of an Document

All documents in ArangoDB have a document handle. This handle uniquely defines a document and is managed by ArangoDB. The interface allows you to access the documents of a collection as:

db.collection.documet(document-handle)

For example: Assume that the document handle, which is stored in the _id field of the document, is 7254820/362549736 and the document lives in a collection named demo, then that document can be accessed as:

db.demo.document("7254820/362549736")

Because the document handle is unique within the database, you can leave out the collection and use the shortcut:

db._document("7254820/362549736")

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

Working with Documents

Collection Methods

collection.document(document)

The document method finds a document given it's identifier. It returns the document. Note that the returned document contains two pseudo-attributes, namely _id and _rev. _id contains the document-handle and _rev the revision of the document.

An error is thrown if there _rev does not longer match the current revision of the document.

An error is thrown if the document does not exist.

The document must be part of the collection; otherwise, an error is thrown.

collection.document(document-handle)

As before. Instead of document a document-handle can be passed as first argument.

Examples

Returns the document for a document-handle:

arango> db.example.document("1432124/2873916");
{ "_id" : "1432124/2873916", "_rev" : 2873916, "Hallo" : "World" }

An error is raised if the document is unknown:

arango> db.example.document("1432124/123456");
JavaScript exception in file '(arango)' at 1,12:
  [ArangoError 1202: document not found: document not found]
!db.example.document("1432124/123456");
!           ^

An error is raised if the handle is invalid:

arango> db.example.document("12345");
JavaScript exception in file '(arango)' at 1,12:
  [ArangoError 10: bad parameter: <document-idenifier> must be a document identifier]
!db.example.document("12345");
!           ^

This function makes the distinction between document and edge collections and dispatches the request to the collection's specialised save function

collection.replace(document, data)

Replaces an existing document. The document must be a document in the current collection. This document is then replaced with the data given as second argument.

The method returns a document with the attributes _id, _rev and _oldRev. The attribute _id contains the document handle of the updated document, the attribute _rev contains the document revision of the updated document, the attribute _oldRev contains the revision of the old (now replaced) document.

If there is a conflict, i. e. if the revision of the document does not match the revision in the collection, then an error is thrown.

collection.replace(document, data, true)

As before, but in case of a conflict, the conflict is ignored and the old document is overwritten.

collection.replace(document-handle, data)

As before. Instead of document a document-handle can be passed as first argument.

Examples

Create and update a document:

arango> a1 = db.example.save({ a : 1 });
{ "_id" : "1432124/3903044", "_rev" : 3903044 }
arango> a2 = db.example.replace(a1, { a : 2 });
{ "_id" : "1432124/3903044", "_rev" : 3968580, "_oldRev" : 3903044 }
arango> a3 = db.example.replace(a1, { a : 3 });
JavaScript exception in file '(arango)' at 1,17: [ArangoError 1200: conflict: cannot replace document]
!a3 = db.example.replace(a1, { a : 3 })
!                ^
arango> a4 = db.example.replace(a1, { a : 4 }, true);
{ "_id" : "1432124/3903044", "_rev" : 4034116, "_oldRev" : 3968580 }

Use a document handle:

arango> a5 = db.example.replace("1432124/3903044", { a : 5 });
{ "_id" : "1432124/3903044", "_rev" : 4099652, "_oldRev" : 4034116 }

collection.remove(document)

Deletes a document. If there is revision mismatch, then an error is thrown.

collection.remove(document, true)

Deletes a document. If there is revision mismatch, then mismatch is ignored and document is deleted. The function returns true if the document existed and was deleted. It returns false, if the document was already deleted.

collection.remove(document-handle, data)

As before. Instead of document a document-handle can be passed as first argument.

Examples

Delete a document:

arango> a1 = db.example.save({ a : 1 });
{ "_id" : "116308/3449537", "_rev" : 3449537 }
arango> db.example.document(a1);
{ "_id" : "116308/3449537", "_rev" : 3449537, "a" : 1 }
arango> db.example.delete(a1);
true
arango> db.example.document(a1);
JavaScript exception in file '(arango)' at 1,12: [ArangoError 1202: document not found: document not found]
!db.example.document(a1);
!           ^

Delete a document with a conflict:

arango> a1 = db.example.save({ a : 1 });
{ "_id" : "116308/3857139", "_rev" : 3857139 }
arango> a2 = db.example.replace(a1, { a : 2 });
{ "_id" : "116308/3857139", "_rev" : 3922675, "_oldRev" : 3857139 }
arango> db.example.delete(a1);
JavaScript exception in file '(arango)' at 1,18: [ArangoError 1200: conflict: cannot delete document]
!db.example.delete(a1);
!                 ^
arango> db.example.delete(a1, true);
true
arango> db.example.document(a1);
JavaScript exception in file '(arango)' at 1,12: [ArangoError 1202: document not found: document not found]
!db.example.document(a1);
!           ^

Database Methods

db._document(document)

An error is thrown if there _rev does not longer match the current revision of the document.

db._document(document-handle)

As before. Instead of document a document-handle can be passed as first argument.

Examples

Returns the document:

arango> db._document("1432124/3053939");
{ "_id" : "1432124/3053939", "_rev" : 3053939, "Hallo" : "World" }

db._replace(document, data)

If there is a conflict, i. e. if the revision of the document does not match the revision in the collection, then an error is thrown.

db._replace(document, data, true)

As before, but in case of a conflict, the conflict is ignored and the old document is overwritten.

db._replace(document-handle, data)

As before. Instead of document a document-handle can be passed as first argument.

Examples

Create and update a document:

arango> a1 = db.example.save({ a : 1 });
{ "_id" : "116308/1717678", "_rev" : 1717678 }
arango> a2 = db._replace(a1, { a : 2 });
{ "_id" : "116308/1717678", "_rev" : 1783214, "_oldRev" : 1717678 }
arango> a3 = db._replace(a1, { a : 3 });
JavaScript exception in file '(arango)' at 1,9: [ArangoError 1200: conflict: cannot replace document]
!a3 = db._replace(a1, { a : 3 });
!        ^
arango> a4 = db.example.replace(a1, { a : 4 }, true);
{ "_id" : "116308/1717678", "_rev" : 1848750, "_oldRev" : 1783214 }

db._remove(document)

Deletes a document. If there is revision mismatch, then an error is thrown.

db._remove(document, true)

db._remove(document-handle, data)

As before. Instead of document a document-handle can be passed as first argument.

Examples

Delete a document:

arango> a1 = db.example.save({ a : 1 });
{ "_id" : "116308/4214943", "_rev" : 4214943 }
arango> db._delete(a1);
true
arango> db._delete(a1);
JavaScript exception in file '(arango)' at 1,4: [ArangoError 1202: document not found: cannot delete document]
!db._delete(a1);
!   ^
arango> db._delete(a1, true);
false

Delete a document with a conflict:

arango> a1 = db.example.save({ a : 1 });
{ "_id" : "116308/4042634", "_rev" : 4042634 }
arango> a2 = db._replace(a1, { a : 2 });
{ "_id" : "116308/4042634", "_rev" : 4108170, "_oldRev" : 4042634 }
arango> db._delete(a1);
JavaScript exception in file '(arango)' at 1,4: [ArangoError 1200: conflict: cannot delete document]
!db._delete(a1);
!   ^
arango> db._delete(a1, true);
true
arango> db._document(a1);
JavaScript exception in file '(arango)' at 1,4: [ArangoError 1202: document not found: document not found]
!db._document(a1);
!   ^

Handling Documents

Documents, Identifiers, Handles

Address and ETag of an Document

Working with Documents

Collection Methods

Database Methods