Basics and Terminology

All documents contain special attributes: the is storedas a string in , thedocument’s primary key in _key and the 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.

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

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.

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

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

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.