Basics and Terminology

Documents in ArangoDB are JSON objects. These objects can be nested (toany depth) and may contain lists. Each document has a unique primary key which identifies it within its collection. Furthermore, each document is uniquely identifiedby its document handle across all collections in the same database. Different revisions ofthe same document (identified by its handle) can be distinguished by their document revision.Any transaction only ever sees a single revision of a document.For example:

  1. {
  2.   "_id" : "myusers/3456789",
  3.   "_key" : "3456789",
  4.   "_rev" : "14253647",
  5.   "firstName" : "John",
  6.   "lastName" : "Doe",
  7.   "address" : {
  8.     "street" : "Road To Nowhere 1",
  9.     "city" : "Gotham"
  10.   },
  11.   "hobbies" : [
  12.     {"name": "swimming", "howFavorite": 10},
  13.     {"name": "biking", "howFavorite": 6},
  14.     {"name": "programming", "howFavorite": 4}
  15.   ]
  16. }

All documents contain special attributes: the document handle is storedas a string in _id, thedocument’s primary key in _key and the document revision in_rev. The value of the _key attribute can be specified by the user whencreating a document. _id and _key values are immutable once the documenthas been created. The _rev value is maintained by ArangoDB automatically.

Document Handle

A document handle uniquely identifies a document in the database. Itis a string and consists of the collection’s name and the document key(_key attribute) separated by /.

Document Key

A document key uniquely identifies a document in the collection it isstored in. It can and should be used by clients when specific documentsare queried. The document key is stored in the _key attribute ofeach document. The key values are automatically indexed by ArangoDB ina collection’s primary index. Thus looking up a document by itskey is a fast operation. The _key value of a document isimmutable once the document has been created. By default, ArangoDB willauto-generate a document key if no _key attribute is specified, and usethe user-specified _key otherwise. The generated _key is guaranteed tobe unique in the collection it was generated for. This also applies tosharded collections in a cluster. It can’t be guaranteed that the _key isunique within a database or across a whole node or instance however.

This behavior can be changed on a per-collection level by creatingcollections with the keyOptions attribute.

Using keyOptions it is possible to disallow user-specified keyscompletely, or to force a specific regime for auto-generating the _keyvalues.

Document Revision

Every document in ArangoDB has a revision, stored in the system attribute_rev. It is fully managed by the server and read-only for the user.

Its value should be treated as opaque, no guarantees regarding its formatand properties are given except that it will be different after adocument update. More specifically, _rev values are unique across alldocuments and all collections in a single server setup. In a cluster setup,within one shard it is guaranteed that two different document revisionshave a different _rev string, even if they are written in the samemillisecond.

The rev attribute can be used as a pre-condition for queries, to avoid_lost update situations. That is, if a client fetches a document from the server,modifies it locally (but with the _rev attribute untouched) and sends it backto the server to update the document, but meanwhile the document was changed byanother operation, then the revisions do not match anymore and the operationis cancelled by the server. Without this mechanism, the client wouldaccidentally overwrite changes made to the document without knowing about it.

When an existing document is updated or replaced, ArangoDB will write a newversion of this document to the write-ahead logfile (regardless of thestorage engine). When the new version of the document has been written, theold version(s) will still be present, at least on disk. The same is true whenan existing document (version) gets removed: the old version of the documentplus the removal operation will be on disk for some time.

On disk it is therefore possible that multiple revisions of the same document(as identified by the same _key value) exist at the same time. However,stale revisions are not accessible. Once a document was updated or removedsuccessfully, no query or other data retrieval operation done by the userwill be able to see it any more. Furthermore, after some time, old revisionswill be removed internally. This is to avoid ever-growing disk usage.

From a user perspective, there is just one single document revisionpresent per different _key at every point in time. There is no built-insystem to automatically keep a history of all changes done to a documentand old versions of a document can not be restored via the _rev value.

Multiple Documents in a single Command

Beginning with ArangoDB 3.0 the basic document API has been extendedto handle not only single documents but multiple documents in a singlecommand. This is crucial for performance, in particular in the clustersituation, in which a single request can involve multiple network hopswithin the cluster. Another advantage is that it reduces the overhead ofindividual network round trips between the clientand the server. The general idea to perform multiple document operations in a single command is to use JSON arrays of objects in the place of a single document. As a consequence, document keys, handles and revisionsfor preconditions have to be supplied embedded in the individual documentsgiven. Multiple document operations are restricted to a single documentor edge collection. See the API descriptions for collection objects for details. Note that the API for database objectsdo not offer these operations.