Database Methods

Document

db._document(object)

The document_ method finds a document given an object _object_containing the id_ attribute. The method returnsthe document if it can be found.

An error is thrown if rev_ is specified but the document found has adifferent revision already. An error is also thrown if no document existswith the given id_.

Please note that if the method is executed on the arangod server (e.g. frominside a Foxx application), an immutable document object will be returnedfor performance reasons. It is not possible to change attributes of thisimmutable object. To update or patch the returned document, it needs to becloned/copied into a regular JavaScript object first. This is not necessaryif the _document method is called from out of arangosh or from any otherclient.

db._document(document-handle)

As before. Instead of object a document-handle can be passed asfirst argument. No revision can be specified in this case.

Examples

Returns the document:

  1. arangosh> db._document("example/12345");

Show execution results

  1. { 
  2.   "_key" : "12345", 
  3.   "_id" : "example/12345", 
  4.   "_rev" : "_ZP4PTxa---" 
  5. }

Hide execution results

Exists

db._exists(object)

The exists_ method determines whether a document exists given an objectobject containing the id_ attribute.

An error is thrown if _rev is specified but the document found has adifferent revision already.

Instead of returning the found document or an error, this method willonly return an object with the attributes id_, key and __rev, orfalse if no document with the given id_ or key_ exists. It canthus be used for easy existence checks.

This method will throw an error if used improperly, e.g. when calledwith a non-document handle, a non-document, or when a cross-collectionrequest is performed.

db._exists(document-handle)

As before. Instead of object a document-handle can be passed asfirst argument.

Changes in 3.0 from 2.8:

In the case of a revision mismatch _exists now throws an error insteadof simply returning false. This is to make it possible to tell thedifference between a revision mismatch and a non-existing document.

Replace

db._replace(selector, data)

Replaces an existing document described by the selector, which mustbe an object containing the id_ attribute. There must bea document with that id in the current database. Thisdocument is then replaced with the _data given as second argument.Any attribute id_, key or __rev in data is ignored.

The method returns a document with the attributes id_, key, rev_and oldRev. The attribute id_ contains the document handle of theupdated document, the attribute rev contains the document revision ofthe updated document, the attribute __oldRev contains the revision ofthe old (now replaced) document.

If the selector contains a _rev attribute, the method first checksthat the specified revision is the current revision of that document.If not, there is a conflict, and an error is thrown.

collection.replace(selector, data, options)

As before, but options must be an object that can contain the following boolean attributes:

  • waitForSync: One can forcesynchronization of the document creation operation to disk even incase that the waitForSync flag is been disabled for the entirecollection. Thus, the waitForSync option can be used to forcesynchronization of just specific operations. To use this, set thewaitForSync parameter to true. If the waitForSync parameteris not specified or set to false, then the collection’s defaultwaitForSync behavior is applied. The waitForSync parametercannot be used to disable synchronization for collections that havea default waitForSync value of true.
  • overwrite: If this flag is set to true, a _rev attribute inthe selector is ignored.
  • returnNew: If this flag is set to true, the complete new documentis returned in the output under the attribute new.
  • returnOld: If this flag is set to true, the complete previousrevision of the document is returned in the output under the attribute old.
  • silent: If this flag is set to true, no output is returned.db._replace(document-handle, data)

db._replace(document-handle, data, options)

As before. Instead of selector a document-handle can be passed asfirst argument. No revision precondition is tested.

Examples

Create and replace a document:

  1. arangosh> a1 = db.example.insert({ a : 1 });
  2. arangosh> a2 = db._replace(a1, { a : 2 });
  3. arangosh> a3 = db._replace(a1, { a : 3 });

Show execution results

  1. { 
  2.   "_id" : "example/73719", 
  3.   "_key" : "73719", 
  4.   "_rev" : "_ZP4PTxq---" 
  5. }
  6. { 
  7.   "_id" : "example/73719", 
  8.   "_key" : "73719", 
  9.   "_rev" : "_ZP4PTxu--_", 
  10.   "_oldRev" : "_ZP4PTxq---" 
  11. }
  12. [ArangoError 1200: precondition failed]

Hide execution results

Changes in 3.0 from 2.8:

The options silent, returnNew and returnOld are new.

Update

db._update(selector, data)

Updates an existing document described by the selector, which mustbe an object containing the id_ attribute. There must bea document with that id in the current database. Thisdocument is then patched with the _data given as second argument.Any attribute id_, key or __rev in data is ignored.

The method returns a document with the attributes id_, key, rev_and oldRev. The attribute id_ contains the document handle of theupdated document, the attribute rev contains the document revision ofthe updated document, the attribute __oldRev contains the revision ofthe old (now updated) document.

If the selector contains a _rev attribute, the method first checksthat the specified revision is the current revision of that document.If not, there is a conflict, and an error is thrown.

db._update(selector, data, options)

As before, but options must be an object that can contain the following boolean attributes:

  • waitForSync: One can forcesynchronization of the document creation operation to disk even incase that the waitForSync flag is been disabled for the entirecollection. Thus, the waitForSync option can be used to forcesynchronization of just specific operations. To use this, set thewaitForSync parameter to true. If the waitForSync parameteris not specified or set to false, then the collection’s defaultwaitForSync behavior is applied. The waitForSync parametercannot be used to disable synchronization for collections that havea default waitForSync value of true.
  • overwrite: If this flag is set to true, a _rev attribute inthe selector is ignored.
  • returnNew: If this flag is set to true, the complete new documentis returned in the output under the attribute new.
  • returnOld: If this flag is set to true, the complete previousrevision of the document is returned in the output under the attribute old.
  • silent: If this flag is set to true, no output is returned.
  • keepNull: The optional keepNull parameter can be used to modify the behavior when handling null values. Normally, null valuesare stored in the database. By setting the keepNull parameter tofalse, this behavior can be changed so that all attributes indata with null values will be removed from the target document.
  • mergeObjects: Controls whether objects (not arrays) will be merged if present in both the existing and the patch document. Ifset to false, the value in the patch document will overwrite theexisting document’s value. If set to true, objects will be merged.The default is true.db._update(document-handle, data)

db._update(document-handle, data, options)

As before. Instead of selector a document-handle can be passed asfirst argument. No revision precondition is tested.

Examples

Create and update a document:

  1. arangosh> a1 = db.example.insert({ a : 1 });
  2. arangosh> a2 = db._update(a1, { b : 2 });
  3. arangosh> a3 = db._update(a1, { c : 3 });

Show execution results

  1. { 
  2.   "_id" : "example/73414", 
  3.   "_key" : "73414", 
  4.   "_rev" : "_ZP4PTl2---" 
  5. }
  6. { 
  7.   "_id" : "example/73414", 
  8.   "_key" : "73414", 
  9.   "_rev" : "_ZP4PTl6--_", 
  10.   "_oldRev" : "_ZP4PTl2---" 
  11. }
  12. [ArangoError 1200: precondition failed]

Hide execution results

Changes in 3.0 from 2.8:

The options silent, returnNew and returnOld are new.

Remove

db._remove(selector)

Removes a document described by the selector, which must be an objectcontaining the id_ attribute. There must be a document withthat id_ in the current database. This document is thenremoved.

The method returns a document with the attributes id_, key and __rev.The attribute id_ contains the document handle of theremoved document, the attribute rev_ contains the document revision ofthe removed eocument.

If the selector contains a _rev attribute, the method first checksthat the specified revision is the current revision of that document.If not, there is a conflict, and an error is thrown.

db._remove(selector, options)

As before, but options must be an object that can contain the following boolean attributes:

  • waitForSync: One can forcesynchronization of the document creation operation to disk even incase that the waitForSync flag is been disabled for the entirecollection. Thus, the waitForSync option can be used to forcesynchronization of just specific operations. To use this, set thewaitForSync parameter to true. If the waitForSync parameteris not specified or set to false, then the collection’s defaultwaitForSync behavior is applied. The waitForSync parametercannot be used to disable synchronization for collections that havea default waitForSync value of true.
  • overwrite: If this flag is set to true, a _rev attribute inthe selector is ignored.
  • returnOld: If this flag is set to true, the complete previousrevision of the document is returned in the output under the attribute old.
  • silent: If this flag is set to true, no output is returned.db._remove(document-handle)

db._remove(document-handle, options)

As before. Instead of selector a document-handle can be passed asfirst argument. No revision check is performed.

Examples

Remove a document:

  1. arangosh> a1 = db.example.insert({ a : 1 });
  2. arangosh> db._remove(a1);
  3. arangosh> db._remove(a1);
  4. arangosh> db._remove(a1, {overwrite: true});

Show execution results

  1. { 
  2.   "_id" : "example/73553", 
  3.   "_key" : "73553", 
  4.   "_rev" : "_ZP4PTrm---" 
  5. }
  6. { 
  7.   "_id" : "example/73553", 
  8.   "_key" : "73553", 
  9.   "_rev" : "_ZP4PTrm---" 
  10. }
  11. [ArangoError 1202: document not found]
  12. [ArangoError 1202: document not found]

Hide execution results

Remove the document in the revision a1 with a conflict:

  1. arangosh> a1 = db.example.insert({ a : 1 });
  2. arangosh> a2 = db._replace(a1, { a : 2 });
  3. arangosh> db._remove(a1);
  4. arangosh> db._remove(a1, {overwrite: true} );
  5. arangosh> db._document(a1);

Show execution results

  1. { 
  2.   "_id" : "example/73531", 
  3.   "_key" : "73531", 
  4.   "_rev" : "_ZP4PTqy---" 
  5. }
  6. { 
  7.   "_id" : "example/73531", 
  8.   "_key" : "73531", 
  9.   "_rev" : "_ZP4PTqy--B", 
  10.   "_oldRev" : "_ZP4PTqy---" 
  11. }
  12. [ArangoError 1200: precondition failed]
  13. { 
  14.   "_id" : "example/73531", 
  15.   "_key" : "73531", 
  16.   "_rev" : "_ZP4PTqy--B" 
  17. }
  18. [ArangoError 1202: document not found]

Hide execution results

Remove a document using new signature:

  1. arangosh> db.example.insert({ _key: "11265325374", a:  1 } );
  2. arangosh> db.example.remove("example/11265325374",
  3. ........> { overwrite: true, waitForSync: false})

Show execution results

  1. { 
  2.   "_id" : "example/11265325374", 
  3.   "_key" : "11265325374", 
  4.   "_rev" : "_ZP4PTrS---" 
  5. }
  6. { 
  7.   "_id" : "example/11265325374", 
  8.   "_key" : "11265325374", 
  9.   "_rev" : "_ZP4PTrS---" 
  10. }

Hide execution results

Changes in 3.0 from 2.8:

The method now returns not only true but information about the removeddocument(s). The options silent and returnOld are new.