Collection Methods

All

collection.all()

Fetches all documents from a collection and returns a cursor. You can usetoArray, next, or hasNext to access the result. The resultcan be limited using the skip and limit operator.

Examples

Use toArray to get all documents at once:

arangosh> db.five.insert({ name : "one" });
arangosh> db.five.insert({ name : "two" });
arangosh> db.five.insert({ name : "three" });
arangosh> db.five.insert({ name : "four" });
arangosh> db.five.insert({ name : "five" });
arangosh> db.five.all().toArray();

Show execution results

Hide execution results

{ 
  "_id" : "five/107", 
  "_key" : "107", 
  "_rev" : "_Z2KCTmq---" 
}
{ 
  "_id" : "five/109", 
  "_key" : "109", 
  "_rev" : "_Z2KCTmy---" 
}
{ 
  "_id" : "five/111", 
  "_key" : "111", 
  "_rev" : "_Z2KCTm2---" 
}
{ 
  "_id" : "five/113", 
  "_key" : "113", 
  "_rev" : "_Z2KCTm2--A" 
}
{ 
  "_id" : "five/115", 
  "_key" : "115", 
  "_rev" : "_Z2KCTm6---" 
}
[ 
  { 
    "_key" : "107", 
    "_id" : "five/107", 
    "_rev" : "_Z2KCTmq---", 
    "name" : "one" 
  }, 
  { 
    "_key" : "109", 
    "_id" : "five/109", 
    "_rev" : "_Z2KCTmy---", 
    "name" : "two" 
  }, 
  { 
    "_key" : "111", 
    "_id" : "five/111", 
    "_rev" : "_Z2KCTm2---", 
    "name" : "three" 
  }, 
  { 
    "_key" : "113", 
    "_id" : "five/113", 
    "_rev" : "_Z2KCTm2--A", 
    "name" : "four" 
  }, 
  { 
    "_key" : "115", 
    "_id" : "five/115", 
    "_rev" : "_Z2KCTm6---", 
    "name" : "five" 
  } 
]

Use limit to restrict the documents:

arangosh> db.five.insert({ name : "one" });
arangosh> db.five.insert({ name : "two" });
arangosh> db.five.insert({ name : "three" });
arangosh> db.five.insert({ name : "four" });
arangosh> db.five.insert({ name : "five" });
arangosh> db.five.all().limit(2).toArray();

Show execution results

Hide execution results

{ 
  "_id" : "five/126", 
  "_key" : "126", 
  "_rev" : "_Z2KCToS---" 
}
{ 
  "_id" : "five/128", 
  "_key" : "128", 
  "_rev" : "_Z2KCToS--A" 
}
{ 
  "_id" : "five/130", 
  "_key" : "130", 
  "_rev" : "_Z2KCToW---" 
}
{ 
  "_id" : "five/132", 
  "_key" : "132", 
  "_rev" : "_Z2KCToa---" 
}
{ 
  "_id" : "five/134", 
  "_key" : "134", 
  "_rev" : "_Z2KCToa--A" 
}
[ 
  { 
    "_key" : "126", 
    "_id" : "five/126", 
    "_rev" : "_Z2KCToS---", 
    "name" : "one" 
  }, 
  { 
    "_key" : "128", 
    "_id" : "five/128", 
    "_rev" : "_Z2KCToS--A", 
    "name" : "two" 
  } 
]

Query by example

collection.byExample(example)

Fetches all documents from a collection that match the specifiedexample and returns a cursor.

You can use toArray, next, or hasNext to access theresult. The result can be limited using the skip and _limit_operator.

An attribute name of the form a.b is interpreted as attribute path,not as attribute. If you use

{ "a" : { "c" : 1 } }

as example, then you will find all documents, such that the attributea contains a document of the form {c : 1 }. For example the document

{ "a" : { "c" : 1 }, "b" : 1 }

will match, but the document

{ "a" : { "c" : 1, "b" : 1 } }

will not.

However, if you use

{ "a.c" : 1 }

then you will find all documents, which contain a sub-document in a_that has an attribute _c of value 1. Both the following documents

{ "a" : { "c" : 1 }, "b" : 1 }

and

{ "a" : { "c" : 1, "b" : 1 } }

will match.

collection.byExample(path1, value1, ...)

As alternative you can supply an array of paths and values.

Examples

Use toArray to get all documents at once:

arangosh> db.users.insert({ name: "Gerhard" });
arangosh> db.users.insert({ name: "Helmut" });
arangosh> db.users.insert({ name: "Angela" });
arangosh> db.users.all().toArray();
arangosh> db.users.byExample({ "_id" : "users/20" }).toArray();
arangosh> db.users.byExample({ "name" : "Gerhard" }).toArray();
arangosh> db.users.byExample({ "name" : "Helmut", "_id" : "users/15" }).toArray();

Show execution results

Hide execution results

{ 
  "_id" : "users/145", 
  "_key" : "145", 
  "_rev" : "_Z2KCTp---A" 
}
{ 
  "_id" : "users/147", 
  "_key" : "147", 
  "_rev" : "_Z2KCTpC---" 
}
{ 
  "_id" : "users/149", 
  "_key" : "149", 
  "_rev" : "_Z2KCTpG---" 
}
[ 
  { 
    "_key" : "145", 
    "_id" : "users/145", 
    "_rev" : "_Z2KCTp---A", 
    "name" : "Gerhard" 
  }, 
  { 
    "_key" : "147", 
    "_id" : "users/147", 
    "_rev" : "_Z2KCTpC---", 
    "name" : "Helmut" 
  }, 
  { 
    "_key" : "149", 
    "_id" : "users/149", 
    "_rev" : "_Z2KCTpG---", 
    "name" : "Angela" 
  } 
]
[ ]
[ 
  { 
    "_key" : "145", 
    "_id" : "users/145", 
    "_rev" : "_Z2KCTp---A", 
    "name" : "Gerhard" 
  } 
]
[ ]

Use next to loop over all documents:

arangosh> db.users.insert({ name: "Gerhard" });
arangosh> db.users.insert({ name: "Helmut" });
arangosh> db.users.insert({ name: "Angela" });
arangosh> var a = db.users.byExample( {"name" : "Angela" } );
arangosh> while (a.hasNext()) print(a.next());

Show execution results

Hide execution results

{ 
  "_id" : "users/163", 
  "_key" : "163", 
  "_rev" : "_Z2KCTp2---" 
}
{ 
  "_id" : "users/165", 
  "_key" : "165", 
  "_rev" : "_Z2KCTp2--A" 
}
{ 
  "_id" : "users/167", 
  "_key" : "167", 
  "_rev" : "_Z2KCTp6---" 
}
{ 
  "_key" : "167", 
  "_id" : "users/167", 
  "_rev" : "_Z2KCTp6---", 
  "name" : "Angela" 
}

First Example

collection.firstExample(example)

Returns some document of a collection that matches the specifiedexample. If no such document exists, null will be returned.The example has to be specified as paths and values.See byExample for details.

collection.firstExample(path1, value1, …)

As alternative you can supply an array of paths and values.

Examples

arangosh> db.users.firstExample("name", "Angela");

Show execution results

Hide execution results

{ 
  "_key" : "73852", 
  "_id" : "users/73852", 
  "_rev" : "_Z2KDPju---", 
  "name" : "Angela" 
}

Range

collection.range(attribute, left, right)

Returns all documents from a collection such that the attribute isgreater or equal than left and strictly less than right.

You can use toArray, next, or hasNext to access theresult. The result can be limited using the skip and _limit_operator.

An attribute name of the form a.b is interpreted as attribute path,not as attribute.

Note: the range simple query function is deprecated as of ArangoDB 2.6.The function may be removed in future versions of ArangoDB. The preferredway for retrieving documents from a collection within a specific rangeis to use an AQL query as follows:

FOR doc IN @@collection
  FILTER doc.value >= @left && doc.value < @right
  LIMIT @skip, @limit
  RETURN doc

Examples

Use toArray to get all documents at once:

arangosh> db.old.ensureIndex({ type: "skiplist", fields: [ "age" ] });
arangosh> db.old.insert({ age: 15 });
arangosh> db.old.insert({ age: 25 });
arangosh> db.old.insert({ age: 30 });
arangosh> db.old.range("age", 10, 30).toArray();

Show execution results

Hide execution results

{ 
  "deduplicate" : true, 
  "fields" : [ 
    "age" 
  ], 
  "id" : "old/177", 
  "isNewlyCreated" : true, 
  "name" : "idx_1655125937786716162", 
  "selectivityEstimate" : 1, 
  "sparse" : false, 
  "type" : "skiplist", 
  "unique" : false, 
  "code" : 201 
}
{ 
  "_id" : "old/181", 
  "_key" : "181", 
  "_rev" : "_Z2KCTqW---" 
}
{ 
  "_id" : "old/183", 
  "_key" : "183", 
  "_rev" : "_Z2KCTqa---" 
}
{ 
  "_id" : "old/185", 
  "_key" : "185", 
  "_rev" : "_Z2KCTqa--A" 
}
[ 
  { 
    "_key" : "181", 
    "_id" : "old/181", 
    "_rev" : "_Z2KCTqW---", 
    "age" : 15 
  }, 
  { 
    "_key" : "183", 
    "_id" : "old/183", 
    "_rev" : "_Z2KCTqa---", 
    "age" : 25 
  } 
]

Closed range

collection.closedRange(attribute, left, right)

Returns all documents of a collection such that the attribute isgreater or equal than left and less or equal than right.

You can use toArray, next, or hasNext to access theresult. The result can be limited using the skip and _limit_operator.

An attribute name of the form a.b is interpreted as attribute path,not as attribute.

Note: the closedRange simple query function is deprecated as of ArangoDB 2.6.The function may be removed in future versions of ArangoDB. The preferredway for retrieving documents from a collection within a specific rangeis to use an AQL query as follows:

FOR doc IN @@collection
  FILTER doc.value >= @left && doc.value <= @right
  LIMIT @skip, @limit
  RETURN doc

Examples

Use toArray to get all documents at once:

arangosh> db.old.ensureIndex({ type: "skiplist", fields: [ "age" ] });
arangosh> db.old.insert({ age: 15 });
arangosh> db.old.insert({ age: 25 });
arangosh> db.old.insert({ age: 30 });
arangosh> db.old.closedRange("age", 10, 30).toArray();

Show execution results

Hide execution results

{ 
  "deduplicate" : true, 
  "fields" : [ 
    "age" 
  ], 
  "id" : "old/196", 
  "isNewlyCreated" : true, 
  "name" : "idx_1655125937801396224", 
  "selectivityEstimate" : 1, 
  "sparse" : false, 
  "type" : "skiplist", 
  "unique" : false, 
  "code" : 201 
}
{ 
  "_id" : "old/200", 
  "_key" : "200", 
  "_rev" : "_Z2KCTrO---" 
}
{ 
  "_id" : "old/202", 
  "_key" : "202", 
  "_rev" : "_Z2KCTrS---" 
}
{ 
  "_id" : "old/204", 
  "_key" : "204", 
  "_rev" : "_Z2KCTrS--A" 
}
[ 
  { 
    "_key" : "200", 
    "_id" : "old/200", 
    "_rev" : "_Z2KCTrO---", 
    "age" : 15 
  }, 
  { 
    "_key" : "202", 
    "_id" : "old/202", 
    "_rev" : "_Z2KCTrS---", 
    "age" : 25 
  }, 
  { 
    "_key" : "204", 
    "_id" : "old/204", 
    "_rev" : "_Z2KCTrS--A", 
    "age" : 30 
  } 
]

Any

collection.any()

Returns a random document from the collection or null if none exists.

Note: this method is expensive when using the RocksDB storage engine.

Count

collection.count()

Returns the number of living documents in the collection.

Examples

arangosh> db.users.count();

Show execution results

Hide execution results

0

toArray

collection.toArray()

Converts the collection into an array of documents. Never use this callin a production environment as it will basically create a copy of yourcollection in RAM which will use resources depending on the number and sizeof the documents in your collecion.

Document

collection.document(object)

The document method finds a document given an object object_containing the __id or key_ attribute. The method returnsthe document if it can be found. If both attributes are given,the id takes precedence, it is an error, if the collection partof the __id does not match the collection.

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 or __key value.

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.

collection.document(document-handle)

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

collection.document(document-key)

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

collection.document(array)

This variant allows to perform the operation on a whole array of arguments.The behavior is exactly as if document would have been called on all membersof the array separately and all results are returned in an array. If an erroroccurs with any of the documents, no exception is risen! Instead of a documentan error object is returned in the result array.

Examples

Returns the document for a document-handle:

arangosh> db.example.document("example/2873916");

Show execution results

Hide execution results

{ 
  "_key" : "2873916", 
  "_id" : "example/2873916", 
  "_rev" : "_Z2KDP4O--A" 
}

Returns the document for a document-key:

arangosh> db.example.document("2873916");

Show execution results

Hide execution results

{ 
  "_key" : "2873916", 
  "_id" : "example/2873916", 
  "_rev" : "_Z2KDP3e--A" 
}

Returns the document for an object:

arangosh> db.example.document({_id: "example/2873916"});

Show execution results

Hide execution results

{ 
  "_key" : "2873916", 
  "_id" : "example/2873916", 
  "_rev" : "_Z2KDP3u---" 
}

Returns the document for an array of two keys:

arangosh> db.example.document(["2873916","2873917"]);

Show execution results

Hide execution results

[ 
  { 
    "_key" : "2873916", 
    "_id" : "example/2873916", 
    "_rev" : "_Z2KDP4----" 
  }, 
  { 
    "_key" : "2873917", 
    "_id" : "example/2873917", 
    "_rev" : "_Z2KDP4---A" 
  } 
]

An error is raised if the document is unknown:

arangosh> db.example.document("example/4472917");

Show execution results

Hide execution results

[ArangoError 1202: document not found]

An error is raised if the handle is invalid:

arangosh> db.example.document("");

Show execution results

Hide execution results

[ArangoError 1205: illegal document handle]

Changes in 3.0 from 2.8:

document can now query multiple documents with one call.

Exists

checks whether a document existscollection.exists(object)

The exists method determines whether a document exists given an objectobject containing the id_ or key attribute. If both attributesare given, the __id takes precedence, it is an error, if the collectionpart of the _id does not match the collection.

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.

collection.exists(document-handle)

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

collection.exists(document-key)

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

collection.exists(array)

This variant allows to perform the operation on a whole array of arguments.The behavior is exactly as if exists would have been called on allmembers of the array separately and all results are returned in an array. If an erroroccurs with any of the documents, the operation stops immediately returningonly an error object.

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.

exists can now query multiple documents with one call.

Lookup By Keys

collection.documents(keys)

Looks up the documents in the specified collection using the array ofkeys provided. All documents for which a matching key was specified inthe keys array and that exist in the collection will be returned. Keysfor which no document can be found in the underlying collection areignored, and no exception will be thrown for them.

This method is deprecated in favour of the array variant of document.

Examples

arangosh> keys = [ ];
arangosh> for (var i = 0; i < 10; ++i) {
........>   db.example.insert({ _key: "test" + i, value: i });
........>   keys.push("test" + i);
........> }
arangosh> db.example.documents(keys);

Show execution results

Hide execution results

[ ]
{ 
  "documents" : [ 
    { 
      "_key" : "test0", 
      "_id" : "example/test0", 
      "_rev" : "_Z2KDPlu---", 
      "value" : 0 
    }, 
    { 
      "_key" : "test1", 
      "_id" : "example/test1", 
      "_rev" : "_Z2KDPlu--A", 
      "value" : 1 
    }, 
    { 
      "_key" : "test2", 
      "_id" : "example/test2", 
      "_rev" : "_Z2KDPly---", 
      "value" : 2 
    }, 
    { 
      "_key" : "test3", 
      "_id" : "example/test3", 
      "_rev" : "_Z2KDPly--A", 
      "value" : 3 
    }, 
    { 
      "_key" : "test4", 
      "_id" : "example/test4", 
      "_rev" : "_Z2KDPl2---", 
      "value" : 4 
    }, 
    { 
      "_key" : "test5", 
      "_id" : "example/test5", 
      "_rev" : "_Z2KDPl2--A", 
      "value" : 5 
    }, 
    { 
      "_key" : "test6", 
      "_id" : "example/test6", 
      "_rev" : "_Z2KDPl2--C", 
      "value" : 6 
    }, 
    { 
      "_key" : "test7", 
      "_id" : "example/test7", 
      "_rev" : "_Z2KDPl6---", 
      "value" : 7 
    }, 
    { 
      "_key" : "test8", 
      "_id" : "example/test8", 
      "_rev" : "_Z2KDPl6--A", 
      "value" : 8 
    }, 
    { 
      "_key" : "test9", 
      "_id" : "example/test9", 
      "_rev" : "_Z2KDPl6--C", 
      "value" : 9 
    } 
  ] 
}

Insert / Save

Note: since ArangoDB 2.2, insert is an alias for save.

collection.insert(data)collection.save(data)

Creates a new document in the collection from the given data. Thedata must be an object. The attributes id_ and rev are ignoredand are automatically generated. A unique value for the attribute key_will be automatically generated if not specified. If specified, theremust not be a document with the given key in the collection.

The method returns a document with the attributes id_, key and__rev. The attribute id_ contains the document handle of the newlycreated document, the attribute key the document key and theattribute __rev contains the document revision.

collection.insert(data, options)collection.save(data, options)

Creates a new document in the collection from the given data asabove. The optional options parameter must be an object and can beused to specify the following options:

• 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.
• silent: If this flag is set to true, the method does not returnany output.
• overwrite: If set to true, the insert becomes a replace-insert.If a document with the same _key already exists the new documentis not rejected with unique constraint violated but will replacethe old document.
• 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 old documentis returned in the output under the attribute old. Only available in combination with the overwrite option

collection.insert(array)

collection.insert(array, options)

These two variants allow to perform the operation on a whole array ofarguments. The behavior is exactly as if insert would have been called on allmembers of the array separately and all results are returned in an array. If anerror occurs with any of the documents, no exception is risen! Instead of adocument an error object is returned in the result array. The options behaveexactly as before.

Changes in 3.0 from 2.8:

The options silent and returnNew are new. The method can now insertmultiple documents with one call.

Examples

arangosh> db.example.insert({ Hello : "World" });
arangosh> db.example.insert({ Hello : "World" }, {waitForSync: true});

Show execution results

Hide execution results

{ 
  "_id" : "example/74163", 
  "_key" : "74163", 
  "_rev" : "_Z2KDP1m---" 
}
{ 
  "_id" : "example/74165", 
  "_key" : "74165", 
  "_rev" : "_Z2KDP1q---" 
}

arangosh> db.example.insert([{ Hello : "World" }, {Hello: "there"}])
arangosh> db.example.insert([{ Hello : "World" }, {}], {waitForSync: true});

Show execution results

Hide execution results

[ 
  { 
    "_id" : "example/74150", 
    "_key" : "74150", 
    "_rev" : "_Z2KDP0i---" 
  }, 
  { 
    "_id" : "example/74151", 
    "_key" : "74151", 
    "_rev" : "_Z2KDP0i--A" 
  } 
]
[ 
  { 
    "_id" : "example/74153", 
    "_key" : "74153", 
    "_rev" : "_Z2KDP0m---" 
  }, 
  { 
    "_id" : "example/74154", 
    "_key" : "74154", 
    "_rev" : "_Z2KDP0m--A" 
  } 
]

arangosh> db.example.insert({ _key : "666", Hello : "World" });
arangosh> db.example.insert({ _key : "666", Hello : "Universe" }, {overwrite: true, returnOld: true});

Show execution results

Hide execution results

{ 
  "_id" : "example/666", 
  "_key" : "666", 
  "_rev" : "_Z2KDP2a---" 
}
{ 
  "_id" : "example/666", 
  "_key" : "666", 
  "_rev" : "_Z2KDP2e--A", 
  "_oldRev" : "_Z2KDP2a---", 
  "old" : { 
    "_key" : "666", 
    "_id" : "example/666", 
    "_rev" : "_Z2KDP2a---", 
    "Hello" : "World" 
  } 
}

Replace

collection.replace(selector, data)

Replaces an existing document described by the selector, which mustbe an object containing the id_ or key attribute. There must bea document with that __id or key in the current collection. 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 followingboolean 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 theattribute old.
• silent: If this flag is set to true, no output is returned.

collection.replace(document-handle, data)

collection.replace(document-handle, data, options)

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

collection.replace(document-key, data)

collection.replace(document-key, data, options)

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

collection.replace(selectorarray, dataarray)

collection.replace(selectorarray, dataarray, options)

These two variants allow to perform the operation on a whole array ofselector/data pairs. The two arrays given as selectorarray and dataarray_must have the same length. The behavior is exactly as if _replace would havebeen called on all respective members of the two arrays and all results arereturned in an array. If an error occurs with any of the documents, noexception is risen! Instead of a document an error object is returned in theresult array. The options behave exactly as before.

Examples

Create and update a document:

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

Show execution results

Hide execution results

{ 
  "_id" : "example/74290", 
  "_key" : "74290", 
  "_rev" : "_Z2KDP5u--A" 
}
{ 
  "_id" : "example/74290", 
  "_key" : "74290", 
  "_rev" : "_Z2KDP5y--_", 
  "_oldRev" : "_Z2KDP5u--A" 
}
[ArangoError 1200: precondition failed]

Use a document handle:

arangosh> a1 = db.example.insert({ a : 1 });
arangosh> a2 = db.example.replace("example/3903044", { a : 2 });

Show execution results

Hide execution results

{ 
  "_id" : "example/3903045", 
  "_key" : "3903045", 
  "_rev" : "_Z2KDP6C--A" 
}
{ 
  "_id" : "example/3903044", 
  "_key" : "3903044", 
  "_rev" : "_Z2KDP6G--_", 
  "_oldRev" : "_Z2KDP6C---" 
}

Changes in 3.0 from 2.8:

The options silent, returnNew and returnOld are new. The methodcan now replace multiple documents with one call.

Update

collection.update(selector, data)

Updates an existing document described by the selector, which mustbe an object containing the id_ or key attribute. There must bea document with that __id or key in the current collection. 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.

collection.update(selector, data, options)

As before, but options must be an object that can contain the followingboolean 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 theattribute old.
• silent: If this flag is set to true, no output is returned.
• keepNull: The optional keepNull parameter can be used to modifythe 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 bemerged 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.

collection.update(document-handle, data)

collection.update(document-handle, data, options)

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

collection.update(document-key, data)

collection.update(document-key, data, options)

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

collection.update(selectorarray, dataarray)

collection.update(selectorarray, dataarray, options)

These two variants allow to perform the operation on a whole array ofselector/data pairs. The two arrays given as selectorarray and dataarray_must have the same length. The behavior is exactly as if _update would havebeen called on all respective members of the two arrays and all results arereturned in an array. If an error occurs with any of the documents, noexception is risen! Instead of a document an error object is returned in theresult array. The options behave exactly as before.

Examples

Create and update a document:

arangosh> a1 = db.example.insert({"a" : 1});
arangosh> a2 = db.example.update(a1, {"b" : 2, "c" : 3});
arangosh> a3 = db.example.update(a1, {"d" : 4});
arangosh> a4 = db.example.update(a2, {"e" : 5, "f" : 6 });
arangosh> db.example.document(a4);
arangosh> a5 = db.example.update(a4, {"a" : 1, c : 9, e : 42 });
arangosh> db.example.document(a5);

Show execution results

Hide execution results

{ 
  "_id" : "example/74368", 
  "_key" : "74368", 
  "_rev" : "_Z2KDP8G---" 
}
{ 
  "_id" : "example/74368", 
  "_key" : "74368", 
  "_rev" : "_Z2KDP8G--B", 
  "_oldRev" : "_Z2KDP8G---" 
}
[ArangoError 1200: precondition failed]
{ 
  "_id" : "example/74368", 
  "_key" : "74368", 
  "_rev" : "_Z2KDP8K--_", 
  "_oldRev" : "_Z2KDP8G--B" 
}
{ 
  "_key" : "74368", 
  "_id" : "example/74368", 
  "_rev" : "_Z2KDP8K--_", 
  "a" : 1, 
  "c" : 3, 
  "b" : 2, 
  "f" : 6, 
  "e" : 5 
}
{ 
  "_id" : "example/74368", 
  "_key" : "74368", 
  "_rev" : "_Z2KDP8O--_", 
  "_oldRev" : "_Z2KDP8K--_" 
}
{ 
  "_key" : "74368", 
  "_id" : "example/74368", 
  "_rev" : "_Z2KDP8O--_", 
  "a" : 1, 
  "c" : 9, 
  "b" : 2, 
  "f" : 6, 
  "e" : 42 
}

Use a document handle:

arangosh> a1 = db.example.insert({"a" : 1});
arangosh> a2 = db.example.update("example/18612115", { "x" : 1, "y" : 2 });

Show execution results

Hide execution results

{ 
  "_id" : "example/18612116", 
  "_key" : "18612116", 
  "_rev" : "_Z2KDP9i--A" 
}
{ 
  "_id" : "example/18612115", 
  "_key" : "18612115", 
  "_rev" : "_Z2KDP9m--_", 
  "_oldRev" : "_Z2KDP9i---" 
}

Use the keepNull parameter to remove attributes with null values:

arangosh> db.example.insert({"a" : 1});
arangosh> db.example.update("example/19988371",
........> { "b" : null, "c" : null, "d" : 3 });
arangosh> db.example.document("example/19988371");
arangosh> db.example.update("example/19988371", { "a" : null }, false, false);
arangosh> db.example.document("example/19988371");
arangosh> db.example.update("example/19988371",
........> { "b" : null, "c": null, "d" : null }, false, false);
arangosh> db.example.document("example/19988371");

Show execution results

Hide execution results

{ 
  "_id" : "example/19988372", 
  "_key" : "19988372", 
  "_rev" : "_Z2KDP9C--A" 
}
{ 
  "_id" : "example/19988371", 
  "_key" : "19988371", 
  "_rev" : "_Z2KDP9G--_", 
  "_oldRev" : "_Z2KDP9C---" 
}
{ 
  "_key" : "19988371", 
  "_id" : "example/19988371", 
  "_rev" : "_Z2KDP9G--_", 
  "b" : null, 
  "d" : 3, 
  "c" : null 
}
{ 
  "_id" : "example/19988371", 
  "_key" : "19988371", 
  "_rev" : "_Z2KDP9K--_", 
  "_oldRev" : "_Z2KDP9G--_" 
}
{ 
  "_key" : "19988371", 
  "_id" : "example/19988371", 
  "_rev" : "_Z2KDP9K--_", 
  "b" : null, 
  "d" : 3, 
  "c" : null 
}
{ 
  "_id" : "example/19988371", 
  "_key" : "19988371", 
  "_rev" : "_Z2KDP9O--_", 
  "_oldRev" : "_Z2KDP9K--_" 
}
{ 
  "_key" : "19988371", 
  "_id" : "example/19988371", 
  "_rev" : "_Z2KDP9O--_" 
}

Patching array values:

arangosh>  db.example.insert({"a" : { "one" : 1, "two" : 2, "three" : 3 },
........> "b" : { }});
arangosh> db.example.update("example/20774803", {"a" : { "four" : 4 },
........> "b" : { "b1" : 1 }});
arangosh> db.example.document("example/20774803");
arangosh> db.example.update("example/20774803", { "a" : { "one" : null },
........>                                         "b" : null },
........> false, false);
arangosh> db.example.document("example/20774803");

Show execution results

Hide execution results

{ 
  "_id" : "example/20774804", 
  "_key" : "20774804", 
  "_rev" : "_Z2KDP8q---" 
}
{ 
  "_id" : "example/20774803", 
  "_key" : "20774803", 
  "_rev" : "_Z2KDP8q--B", 
  "_oldRev" : "_Z2KDP8m--A" 
}
{ 
  "_key" : "20774803", 
  "_id" : "example/20774803", 
  "_rev" : "_Z2KDP8q--B", 
  "b" : { 
    "b1" : 1 
  }, 
  "a" : { 
    "four" : 4 
  } 
}
{ 
  "_id" : "example/20774803", 
  "_key" : "20774803", 
  "_rev" : "_Z2KDP8u--_", 
  "_oldRev" : "_Z2KDP8q--B" 
}
{ 
  "_key" : "20774803", 
  "_id" : "example/20774803", 
  "_rev" : "_Z2KDP8u--_", 
  "a" : { 
    "four" : 4 
  } 
}

Changes in 3.0 from 2.8:

The options silent, returnNew and returnOld are new. The methodcan now update multiple documents with one call.

Remove

collection.remove(selector)

Removes a document described by the selector, which must be an objectcontaining the id_ or key attribute. There must be a document withthat __id or _key in the current collection. 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 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.remove(selector, options)

As before, but options must be an object that can contain the followingboolean 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 theattribute old.
• silent: If this flag is set to true, no output is returned.

collection.remove(document-handle)

collection.remove(document-handle, options)

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

collection.remove(document-key)

collection.remove(document-handle, options)

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

collection.remove(selectorarray)

collection.remove(selectorarray,options)

These two variants allow to perform the operation on a whole array ofselectors. The behavior is exactly as if remove would have been called on allmembers of the array separately and all results are returned in an array. If anerror occurs with any of the documents, no exception is risen! Instead of adocument an error object is returned in the result array. The options behaveexactly as before.

Examples

Remove a document:

arangosh> a1 = db.example.insert({ a : 1 });
arangosh> db.example.document(a1);
arangosh> db.example.remove(a1);
arangosh> db.example.document(a1);

Show execution results

Hide execution results

{ 
  "_id" : "example/74116", 
  "_key" : "74116", 
  "_rev" : "_Z2KDPzq---" 
}
{ 
  "_key" : "74116", 
  "_id" : "example/74116", 
  "_rev" : "_Z2KDPzq---", 
  "a" : 1 
}
{ 
  "_id" : "example/74116", 
  "_key" : "74116", 
  "_rev" : "_Z2KDPzq---" 
}
[ArangoError 1202: document not found]

Remove a document with a conflict:

arangosh> a1 = db.example.insert({ a : 1 });
arangosh> a2 = db.example.replace(a1, { a : 2 });
arangosh> db.example.remove(a1);
arangosh> db.example.remove(a1, true);
arangosh> db.example.document(a1);

Show execution results

Hide execution results

{ 
  "_id" : "example/74103", 
  "_key" : "74103", 
  "_rev" : "_Z2KDPzO--A" 
}
{ 
  "_id" : "example/74103", 
  "_key" : "74103", 
  "_rev" : "_Z2KDPzS--_", 
  "_oldRev" : "_Z2KDPzO--A" 
}
[ArangoError 1200: precondition failed]
{ 
  "_id" : "example/74103", 
  "_key" : "74103", 
  "_rev" : "_Z2KDPzS--_" 
}
[ArangoError 1202: document not found]

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. The methodcan now remove multiple documents with one call.

Remove By Keys

collection.removeByKeys(keys)

Looks up the documents in the specified collection using the array of keysprovided, and removes all documents from the collection whose keys arecontained in the keys array. Keys for which no document can be found inthe underlying collection are ignored, and no exception will be thrown forthem.

The method will return an object containing the number of removed documentsin the removed sub-attribute, and the number of not-removed/ignoreddocuments in the ignored sub-attribute.

This method is deprecated in favour of the array variant of remove.

Examples

arangosh> keys = [ ];
arangosh> for (var i = 0; i < 10; ++i) {
........>   db.example.insert({ _key: "test" + i, value: i });
........>   keys.push("test" + i);
........> }
arangosh> db.example.removeByKeys(keys);

Show execution results

Hide execution results

[ ]
{ 
  "removed" : 10, 
  "ignored" : 0 
}

Remove By Example

collection.removeByExample(example)

Removes all documents matching an example.

collection.removeByExample(document, waitForSync)

The optional waitForSync parameter can be used to force synchronizationof the document deletion operation to disk even in case that thewaitForSync flag had been disabled for the entire collection. Thus,the waitForSync parameter can be used to force synchronization of justspecific operations. To use this, set the waitForSync parameter totrue. If the waitForSync parameter is not specified or set tofalse, then the collection’s default waitForSync behavior isapplied. The waitForSync parameter cannot be used to disablesynchronization for collections that have a default waitForSync valueof true.

collection.removeByExample(document, waitForSync, limit)

The optional limit parameter can be used to restrict the number ofremovals to the specified value. If limit is specified but less than thenumber of documents in the collection, it is undefined which documents areremoved.

Examples

arangosh> db.example.removeByExample( {Hello : "world"} );

Show execution results

Hide execution results

1

Replace By Example

collection.replaceByExample(example, newValue)

Replaces all documents matching an example with a new document body.The entire document body of each document matching the example will bereplaced with newValue. The document meta-attributes id_, key and__rev will not be replaced.

collection.replaceByExample(document, newValue, waitForSync)

The optional waitForSync parameter can be used to force synchronizationof the document replacement operation to disk even in case that thewaitForSync flag had been disabled for the entire collection. Thus,the waitForSync parameter can be used to force synchronization of justspecific operations. To use this, set the waitForSync parameter totrue. If the waitForSync parameter is not specified or set tofalse, then the collection’s default waitForSync behavior isapplied. The waitForSync parameter cannot be used to disablesynchronization for collections that have a default waitForSync valueof true.

collection.replaceByExample(document, newValue, waitForSync, limit)

The optional limit parameter can be used to restrict the number ofreplacements to the specified value. If limit is specified but less thanthe number of documents in the collection, it is undefined which documents arereplaced.

Examples

arangosh> db.example.insert({ Hello : "world" });
arangosh> db.example.replaceByExample({ Hello: "world" }, {Hello: "mars"}, false, 5);

Show execution results

Hide execution results

{ 
  "_id" : "example/4488", 
  "_key" : "4488", 
  "_rev" : "_Z2KCUlO---" 
}
1

Update By Example

collection.updateByExample(example, newValue)

Partially updates all documents matching an example with a new document body.Specific attributes in the document body of each document matching theexample will be updated with the values from newValue.The document meta-attributes id_, key and __rev cannot be updated.

Partial update could also be used to append new fields,if there were no old field with same name.

collection.updateByExample(document, newValue, keepNull, waitForSync)

The optional keepNull parameter can be used to modify the behavior whenhandling null values. Normally, null values are stored in thedatabase. By setting the keepNull parameter to false, this behaviorcan be changed so that all attributes in data with null values willbe removed from the target document.

The optional waitForSync parameter can be used to force synchronizationof the document replacement operation to disk even in case that thewaitForSync flag had been disabled for the entire collection. Thus,the waitForSync parameter can be used to force synchronization of justspecific operations. To use this, set the waitForSync parameter totrue. If the waitForSync parameter is not specified or set tofalse, then the collection’s default waitForSync behavior isapplied. The waitForSync parameter cannot be used to disablesynchronization for collections that have a default waitForSync valueof true.

collection.updateByExample(document, newValue, keepNull, waitForSync, limit)

The optional limit parameter can be used to restrict the number ofupdates to the specified value. If limit is specified but less thanthe number of documents in the collection, it is undefined which documents areupdated.

collection.updateByExample(document, newValue, options)

Using this variant, the options for the operation can be passed usingan object with the following sub-attributes:

• keepNull
• waitForSync
• limit
• mergeObjects

Examples

arangosh> db.example.insert({ Hello : "world", foo : "bar" });
arangosh> db.example.updateByExample({ Hello: "world" }, { Hello: "foo", World: "bar" }, false);
arangosh> db.example.byExample({ Hello: "foo" }).toArray()

Show execution results

Hide execution results

{ 
  "_id" : "example/4498", 
  "_key" : "4498", 
  "_rev" : "_Z2KCUlq---" 
}
1
[ 
  { 
    "_key" : "4498", 
    "_id" : "example/4498", 
    "_rev" : "_Z2KCUly--_", 
    "Hello" : "foo", 
    "foo" : "bar", 
    "World" : "bar" 
  } 
]

Collection type

collection.type()

Returns the type of a collection. Possible values are:

• 2: document collection
• 3: edge collection

Convert a document key to a document id

collection.documentId(documentKey)

Qualifies the given document key with this collection’s name to derive avalid document id.

Throws if the document key is invalid. Note that this method does notcheck whether the document already exists in this collection.

Edges

Edges are normal documents that always contain a _from and a _toattribute. Therefore, you can use the document methods to operate onedges. The following methods, however, are specific to edges.

edge-collection.edges(vertex)

The edges operator finds all edges starting from (outbound) or endingin (inbound) vertex.

edge-collection.edges(vertices)

The edges operator finds all edges starting from (outbound) or endingin (inbound) a document from vertices, which must be a list of documentsor document handles.

arangosh> db._create("vertex");
arangosh> db._createEdgeCollection("relation");
arangosh> var myGraph = {};
arangosh> myGraph.v1 = db.vertex.insert({ name : "vertex 1" });
arangosh> myGraph.v2 = db.vertex.insert({ name : "vertex 2" });
arangosh> myGraph.e1 = db.relation.insert(myGraph.v1, myGraph.v2,
........> { label : "knows"});
arangosh> db._document(myGraph.e1);
arangosh> db.relation.edges(myGraph.e1._id);

Show execution results

Hide execution results

[ArangoCollection 65386, "vertex" (type document, status loaded)]
[ArangoCollection 65391, "relation" (type edge, status loaded)]
{ 
  "_id" : "vertex/65398", 
  "_key" : "65398", 
  "_rev" : "_Z2KCftK--A" 
}
{ 
  "_id" : "vertex/65400", 
  "_key" : "65400", 
  "_rev" : "_Z2KCftO---" 
}
{ 
  "_id" : "relation/65402", 
  "_key" : "65402", 
  "_rev" : "_Z2KCftS---" 
}
{ 
  "_key" : "65402", 
  "_id" : "relation/65402", 
  "_from" : "vertex/65398", 
  "_to" : "vertex/65400", 
  "_rev" : "_Z2KCftS---", 
  "label" : "knows" 
}
[ ]

edge-collection.inEdges(vertex)

The edges operator finds all edges ending in (inbound) vertex.

edge-collection.inEdges(vertices)

The edges operator finds all edges ending in (inbound) a document fromvertices, which must a list of documents or document handles.

Examples

arangosh> db._create("vertex");
arangosh> db._createEdgeCollection("relation");
arangosh> myGraph.v1 = db.vertex.insert({ name : "vertex 1" });
arangosh> myGraph.v2 = db.vertex.insert({ name : "vertex 2" });
arangosh> myGraph.e1 = db.relation.insert(myGraph.v1, myGraph.v2,
........> { label : "knows"});
arangosh> db._document(myGraph.e1);
arangosh> db.relation.inEdges(myGraph.v1._id);
arangosh> db.relation.inEdges(myGraph.v2._id);

Show execution results

Hide execution results

[ArangoCollection 65409, "vertex" (type document, status loaded)]
[ArangoCollection 65414, "relation" (type edge, status loaded)]
{ 
  "_id" : "vertex/65421", 
  "_key" : "65421", 
  "_rev" : "_Z2KCfty---" 
}
{ 
  "_id" : "vertex/65423", 
  "_key" : "65423", 
  "_rev" : "_Z2KCft2---" 
}
{ 
  "_id" : "relation/65425", 
  "_key" : "65425", 
  "_rev" : "_Z2KCft2--A" 
}
{ 
  "_key" : "65425", 
  "_id" : "relation/65425", 
  "_from" : "vertex/65421", 
  "_to" : "vertex/65423", 
  "_rev" : "_Z2KCft2--A", 
  "label" : "knows" 
}
[ ]
[ 
  { 
    "_key" : "65425", 
    "_id" : "relation/65425", 
    "_from" : "vertex/65421", 
    "_to" : "vertex/65423", 
    "_rev" : "_Z2KCft2--A", 
    "label" : "knows" 
  } 
]

edge-collection.outEdges(vertex)

The edges operator finds all edges starting from (outbound)vertices.

edge-collection.outEdges(vertices)

The edges operator finds all edges starting from (outbound) a documentfrom vertices, which must a list of documents or document handles.

Examples

arangosh> db._create("vertex");
arangosh> db._createEdgeCollection("relation");
arangosh> myGraph.v1 = db.vertex.insert({ name : "vertex 1" });
arangosh> myGraph.v2 = db.vertex.insert({ name : "vertex 2" });
arangosh> myGraph.e1 = db.relation.insert(myGraph.v1, myGraph.v2,
........> { label : "knows"});
arangosh> db._document(myGraph.e1);
arangosh> db.relation.outEdges(myGraph.v1._id);
arangosh> db.relation.outEdges(myGraph.v2._id);

Show execution results

Hide execution results

[ArangoCollection 65433, "vertex" (type document, status loaded)]
[ArangoCollection 65438, "relation" (type edge, status loaded)]
{ 
  "_id" : "vertex/65445", 
  "_key" : "65445", 
  "_rev" : "_Z2KCfua--A" 
}
{ 
  "_id" : "vertex/65447", 
  "_key" : "65447", 
  "_rev" : "_Z2KCfue---" 
}
{ 
  "_id" : "relation/65449", 
  "_key" : "65449", 
  "_rev" : "_Z2KCfui---" 
}
{ 
  "_key" : "65449", 
  "_id" : "relation/65449", 
  "_from" : "vertex/65445", 
  "_to" : "vertex/65447", 
  "_rev" : "_Z2KCfui---", 
  "label" : "knows" 
}
[ 
  { 
    "_key" : "65449", 
    "_id" : "relation/65449", 
    "_from" : "vertex/65445", 
    "_to" : "vertex/65447", 
    "_rev" : "_Z2KCfui---", 
    "label" : "knows" 
  } 
]
[ ]