Collection Methods

All

collection.all()

Fetches all documents from a collection and returns a cursor. You can use toArray(), next(), or hasNext() to access the result. The result can 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();

{ 
  "_id" : "five/108", 
  "_key" : "108", 
  "_rev" : "_fyvMKg---_" 
}
{ 
  "_id" : "five/110", 
  "_key" : "110", 
  "_rev" : "_fyvMKgC---" 
}
{ 
  "_id" : "five/112", 
  "_key" : "112", 
  "_rev" : "_fyvMKgG---" 
}
{ 
  "_id" : "five/114", 
  "_key" : "114", 
  "_rev" : "_fyvMKgG--_" 
}
{ 
  "_id" : "five/116", 
  "_key" : "116", 
  "_rev" : "_fyvMKgK---" 
}
[ 
  { 
    "_key" : "108", 
    "_id" : "five/108", 
    "_rev" : "_fyvMKg---_", 
    "name" : "one" 
  }, 
  { 
    "_key" : "110", 
    "_id" : "five/110", 
    "_rev" : "_fyvMKgC---", 
    "name" : "two" 
  }, 
  { 
    "_key" : "112", 
    "_id" : "five/112", 
    "_rev" : "_fyvMKgG---", 
    "name" : "three" 
  }, 
  { 
    "_key" : "114", 
    "_id" : "five/114", 
    "_rev" : "_fyvMKgG--_", 
    "name" : "four" 
  }, 
  { 
    "_key" : "116", 
    "_id" : "five/116", 
    "_rev" : "_fyvMKgK---", 
    "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();

{ 
  "_id" : "five/128", 
  "_key" : "128", 
  "_rev" : "_fyvMKhu---" 
}
{ 
  "_id" : "five/130", 
  "_key" : "130", 
  "_rev" : "_fyvMKhu--_" 
}
{ 
  "_id" : "five/132", 
  "_key" : "132", 
  "_rev" : "_fyvMKhy---" 
}
{ 
  "_id" : "five/134", 
  "_key" : "134", 
  "_rev" : "_fyvMKhy--_" 
}
{ 
  "_id" : "five/136", 
  "_key" : "136", 
  "_rev" : "_fyvMKh2---" 
}
[ 
  { 
    "_key" : "128", 
    "_id" : "five/128", 
    "_rev" : "_fyvMKhu---", 
    "name" : "one" 
  }, 
  { 
    "_key" : "130", 
    "_id" : "five/130", 
    "_rev" : "_fyvMKhu--_", 
    "name" : "two" 
  } 
]

Query by example

collection.byExample(example)

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

You can use toArray(), next(), or hasNext() to access the result. 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 attribute a 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();

{ 
  "_id" : "users/148", 
  "_key" : "148", 
  "_rev" : "_fyvMKiW---" 
}
{ 
  "_id" : "users/150", 
  "_key" : "150", 
  "_rev" : "_fyvMKiW--_" 
}
{ 
  "_id" : "users/152", 
  "_key" : "152", 
  "_rev" : "_fyvMKia---" 
}
[ 
  { 
    "_key" : "148", 
    "_id" : "users/148", 
    "_rev" : "_fyvMKiW---", 
    "name" : "Gerhard" 
  }, 
  { 
    "_key" : "150", 
    "_id" : "users/150", 
    "_rev" : "_fyvMKiW--_", 
    "name" : "Helmut" 
  }, 
  { 
    "_key" : "152", 
    "_id" : "users/152", 
    "_rev" : "_fyvMKia---", 
    "name" : "Angela" 
  } 
]
[ ]
[ 
  { 
    "_key" : "148", 
    "_id" : "users/148", 
    "_rev" : "_fyvMKiW---", 
    "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());

{ 
  "_id" : "users/170", 
  "_key" : "170", 
  "_rev" : "_fyvMKjC---" 
}
{ 
  "_id" : "users/172", 
  "_key" : "172", 
  "_rev" : "_fyvMKjC--_" 
}
{ 
  "_id" : "users/174", 
  "_key" : "174", 
  "_rev" : "_fyvMKjC--A" 
}
{ 
  "_key" : "174", 
  "_id" : "users/174", 
  "_rev" : "_fyvMKjC--A", 
  "name" : "Angela" 
}

First Example

collection.firstExample(example)

Returns some document of a collection that matches the specified example. 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");

{ 
  "_key" : "73905", 
  "_id" : "users/73905", 
  "_rev" : "_fyvNHmC---", 
  "name" : "Angela" 
}

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();

0

toArray

collection.toArray()

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

Document

collection.document(object [, options])

The document() method finds a document given an object object containing the _id or _key attribute. The method returns the document if it can be found. If both attributes are given, the _id takes precedence, it is an error, if the collection part of the _id does not match the collection.

An error is thrown if _rev is specified but the document found has a different revision already. An error is also thrown if no document exists with the given _id or _key value.

Please note that if the method is executed on the arangod server (e.g. from inside a Foxx application), an immutable document object will be returned for performance reasons. It is not possible to change attributes of this immutable object. To update or patch the returned document, it needs to be cloned/copied into a regular JavaScript object first. This is not necessary if the document method is called from out of arangosh or from any other client.

If you pass options as the second argument, it must be an object. If this object has the allowDirtyReads attribute set to true, then the Coordinator is allowed to read from any shard replica and not only from the leader shard. See Read from followers for details.

collection.document(document-handle [, options])

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

collection.document(document-key [, options])

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

collection.document(array [, options])

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 members of the array separately and all results are returned in an array. If an error occurs with any of the documents, no exception is risen! Instead of a document an error object is returned in the result array.

Examples

Returns the document for a document-handle:

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

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

Returns the document for a document-key:

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

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

Returns the document for an object:

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

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

Returns the document for an array of two keys:

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

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

An error is raised if the document is unknown:

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

[ArangoError 1202: document not found]

An error is raised if the handle is invalid:

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

[ArangoError 1205: illegal document identifier]

Exists

Checks whether a document exists:

collection.exists(object [, options])

The exists() method determines whether a document exists given an object object containing the _id or _key attribute. If both attributes are given, the _id takes precedence, it is an error, if the collection part of the _id does not match the collection.

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

Instead of returning the found document or an error, this method will only return an object with the attributes _id, _key and _rev, or false if no document with the given _id or _key exists. It can thus be used for easy existence checks.

This method will throw an error if used improperly, e.g. when called with a non-document handle, a non-document, or when a cross-collection request is performed.

If you pass options as the second argument, it must be an object. If this object has the allowDirtyReads attribute set to true, then the Coordinator is allowed to read from any shard replica and not only from the leader shard. See Read from followers for details.

collection.exists(document-handle [, options])

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

collection.exists(document-key [, options])

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

collection.exists(array [, options])

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 all members of the array separately and all results are returned in an array. If an error occurs with any of the documents, the operation stops immediately returning only an error object.

Lookup By Keys

collection.documents(keys)

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

This method is deprecated in favor 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);

[ ]
{ 
  "documents" : [ 
    { 
      "_key" : "test0", 
      "_id" : "example/test0", 
      "_rev" : "_fyvNHqK---", 
      "value" : 0 
    }, 
    { 
      "_key" : "test1", 
      "_id" : "example/test1", 
      "_rev" : "_fyvNHqK--_", 
      "value" : 1 
    }, 
    { 
      "_key" : "test2", 
      "_id" : "example/test2", 
      "_rev" : "_fyvNHqK--A", 
      "value" : 2 
    }, 
    { 
      "_key" : "test3", 
      "_id" : "example/test3", 
      "_rev" : "_fyvNHqO---", 
      "value" : 3 
    }, 
    { 
      "_key" : "test4", 
      "_id" : "example/test4", 
      "_rev" : "_fyvNHqO--_", 
      "value" : 4 
    }, 
    { 
      "_key" : "test5", 
      "_id" : "example/test5", 
      "_rev" : "_fyvNHqO--A", 
      "value" : 5 
    }, 
    { 
      "_key" : "test6", 
      "_id" : "example/test6", 
      "_rev" : "_fyvNHqS---", 
      "value" : 6 
    }, 
    { 
      "_key" : "test7", 
      "_id" : "example/test7", 
      "_rev" : "_fyvNHqS--_", 
      "value" : 7 
    }, 
    { 
      "_key" : "test8", 
      "_id" : "example/test8", 
      "_rev" : "_fyvNHqS--A", 
      "value" : 8 
    }, 
    { 
      "_key" : "test9", 
      "_id" : "example/test9", 
      "_rev" : "_fyvNHqW---", 
      "value" : 9 
    } 
  ] 
}

Insert / Save

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

Creates a new document in the collection from the given data. The data must be an object. The attributes _id and _rev are ignored and are automatically generated. A unique value for the attribute _key will be automatically generated if not specified. If specified, there must 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 newly created document, the attribute _key the document key and the attribute _rev contains the document revision.

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

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

• waitForSync: One can force synchronization of the document creation operation to disk even in case that the waitForSync flag is been disabled for the entire collection. Thus, the waitForSync option can be used to force synchronization of just specific operations. To use this, set the waitForSync parameter to true. If the waitForSync parameter is not specified or set to false, then the collection’s default waitForSync behavior is applied. The waitForSync parameter cannot be used to disable synchronization for collections that have a default waitForSync value of true.
• silent: If this flag is set to true, the method does not return any output.
• returnNew: If this flag is set to true, the complete new document is returned in the output under the attribute new.
• returnOld: If this flag is set to true, the complete old document is returned in the output under the attribute old. Only available in combination with the overwrite option
• overwrite: If set to true, the insert becomes a replace-insert. If a document with the same _key exists already the new document is not rejected with unique constraint violated but will replace the old document. Note that operations with overwrite parameter require a _key attribute in the request payload, therefore they can only be performed on collections sharded by _key.
• overwriteMode: this optional flag can have one of the following values:
  • ignore: if a document with the specified _key value exists already, nothing will be done and no write operation will be carried out (introduced in v3.7.0). The insert operation will return success in this case. This mode does not support returning the old document version using the returnOld attribute. returnNew will only set the new attribute in the response if a new document was inserted.
  • replace: if a document with the specified _key value exists already, it will be overwritten with the specified document value. This mode will also be used when no overwrite mode is specified but the overwrite flag is set to true.
  • update: if a document with the specified _key value exists already, it will be patched (partially updated) with the specified document value (introduced in v3.7.0). The overwrite mode can be further controlled via the keepNull and mergeObjects parameters.
  • conflict: if a document with the specified _key value exists already, return a unique constraint violation error so that the insert operation fails. This is also the default behavior in case the overwrite mode is not set, and the overwrite flag is false or not set either.
• keepNull: The optional keepNull parameter can be used to modify the behavior when handling null values. Normally, null values are stored in the database. By setting the keepNull parameter to false, this behavior can be changed so that all attributes in data with null values will be removed from the target document. This option controls the update-insert behavior only.
• mergeObjects: Controls whether objects (not arrays) will be merged if present in both the existing and the patch document. If set to false, the value in the patch document will overwrite the existing document’s value. If set to true, objects will be merged. The default is true. This option controls the update-insert behavior only.

collection.insert(array)

collection.insert(array, options)

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

Examples

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

{ 
  "_id" : "example/74343", 
  "_key" : "74343", 
  "_rev" : "_fyvNHyq--_" 
}
{ 
  "_id" : "example/74345", 
  "_key" : "74345", 
  "_rev" : "_fyvNHyu---" 
}

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

[ 
  { 
    "_id" : "example/74330", 
    "_key" : "74330", 
    "_rev" : "_fyvNHyK---" 
  }, 
  { 
    "_id" : "example/74331", 
    "_key" : "74331", 
    "_rev" : "_fyvNHyK--_" 
  } 
]
[ 
  { 
    "_id" : "example/74333", 
    "_key" : "74333", 
    "_rev" : "_fyvNHyK--A" 
  }, 
  { 
    "_id" : "example/74334", 
    "_key" : "74334", 
    "_rev" : "_fyvNHyK--B" 
  } 
]

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

{ 
  "_id" : "example/666", 
  "_key" : "666", 
  "_rev" : "_fyvNHz---_" 
}
{ 
  "_id" : "example/666", 
  "_key" : "666", 
  "_rev" : "_fyvNHzC---", 
  "_oldRev" : "_fyvNHz---_", 
  "old" : { 
    "_key" : "666", 
    "_id" : "example/666", 
    "_rev" : "_fyvNHz---_", 
    "Hello" : "World" 
  } 
}

Replace

collection.replace(selector, data)

Replaces an existing document described by the selector, which must be an object containing the _id or _key attribute. There must be a document with that _id or _key in the current collection. This document 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 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 the selector contains a _rev attribute, the method first checks that 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 force synchronization of the document creation operation to disk even in case that the waitForSync flag is been disabled for the entire collection. Thus, the waitForSync option can be used to force synchronization of just specific operations. To use this, set the waitForSync parameter to true. If the waitForSync parameter is not specified or set to false, then the collection’s default waitForSync behavior is applied. The waitForSync parameter cannot be used to disable synchronization for collections that have a default waitForSync value of true.
• overwrite: If this flag is set to true, a _rev attribute in the selector is ignored.
• returnNew: If this flag is set to true, the complete new document is returned in the output under the attribute new.
• returnOld: If this flag is set to true, the complete previous revision of the document is returned in the output under the attribute 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 as first 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 as first argument. No revision precondition is tested.

collection.replace(selector-array, data-array)

collection.replace(selector-array, data-array, options)

These two variants allow to perform the operation on a whole array of selector/data pairs. The two arrays given as selector-array and data-array must have the same length. The behavior is exactly as if replace() would have been called on all respective members of the two arrays and all results are returned in an array. If an error occurs with any of the documents, no exception is risen! Instead of a document an error object is returned in the result 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 });

{ 
  "_id" : "example/74451", 
  "_key" : "74451", 
  "_rev" : "_fyvNH1C--_" 
}
{ 
  "_id" : "example/74451", 
  "_key" : "74451", 
  "_rev" : "_fyvNH1G---", 
  "_oldRev" : "_fyvNH1C--_" 
}
[ArangoError 1200: conflict, _rev values do not match]

Use a document handle:

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

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

Update

collection.update(selector, data)

Updates an existing document described by the selector, which must be an object containing the _id or _key attribute. There must be a document with that _id or _key in the current collection. This document 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 the updated document, the attribute _rev contains the document revision of the updated document, the attribute _oldRev contains the revision of the old (now updated) document.

If the selector contains a _rev attribute, the method first checks that 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 following boolean attributes:

• waitForSync: One can force synchronization of the document creation operation to disk even in case that the waitForSync flag is been disabled for the entire collection. Thus, the waitForSync option can be used to force synchronization of just specific operations. To use this, set the waitForSync parameter to true. If the waitForSync parameter is not specified or set to false, then the collection’s default waitForSync behavior is applied. The waitForSync parameter cannot be used to disable synchronization for collections that have a default waitForSync value of true.
• overwrite: If this flag is set to true, a _rev attribute in the selector is ignored.
• returnNew: If this flag is set to true, the complete new document is returned in the output under the attribute new.
• returnOld: If this flag is set to true, the complete previous revision 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 values are stored in the database. By setting the keepNull parameter to false, this behavior can be changed so that all attributes in data 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. If set to false, the value in the patch document will overwrite the existing 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 as first 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 as first argument. No revision precondition is tested.

collection.update(selector-array, data-array)

collection.update(selector-array, data-array, options)

These two variants allow to perform the operation on a whole array of selector/data pairs. The two arrays given as selector-array and data-array must have the same length. The behavior is exactly as if update() would have been called on all respective members of the two arrays and all results are returned in an array. If an error occurs with any of the documents, no exception is risen! Instead of a document an error object is returned in the result 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);

{ 
  "_id" : "example/74474", 
  "_key" : "74474", 
  "_rev" : "_fyvNH1i---" 
}
{ 
  "_id" : "example/74474", 
  "_key" : "74474", 
  "_rev" : "_fyvNH1i--_", 
  "_oldRev" : "_fyvNH1i---" 
}
[ArangoError 1200: conflict, _rev values do not match]
{ 
  "_id" : "example/74474", 
  "_key" : "74474", 
  "_rev" : "_fyvNH1m---", 
  "_oldRev" : "_fyvNH1i--_" 
}
{ 
  "_key" : "74474", 
  "_id" : "example/74474", 
  "_rev" : "_fyvNH1m---", 
  "a" : 1, 
  "b" : 2, 
  "c" : 3, 
  "e" : 5, 
  "f" : 6 
}
{ 
  "_id" : "example/74474", 
  "_key" : "74474", 
  "_rev" : "_fyvNH1q---", 
  "_oldRev" : "_fyvNH1m---" 
}
{ 
  "_key" : "74474", 
  "_id" : "example/74474", 
  "_rev" : "_fyvNH1q---", 
  "a" : 1, 
  "b" : 2, 
  "c" : 9, 
  "e" : 42, 
  "f" : 6 
}

Use a document handle:

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

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

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");

{ 
  "_id" : "example/19988372", 
  "_key" : "19988372", 
  "_rev" : "_fyvNH2W---" 
}
{ 
  "_id" : "example/19988371", 
  "_key" : "19988371", 
  "_rev" : "_fyvNH2W--_", 
  "_oldRev" : "_fyvNH2S--_" 
}
{ 
  "_key" : "19988371", 
  "_id" : "example/19988371", 
  "_rev" : "_fyvNH2W--_", 
  "d" : 3, 
  "c" : null, 
  "b" : null 
}
{ 
  "_id" : "example/19988371", 
  "_key" : "19988371", 
  "_rev" : "_fyvNH2a---", 
  "_oldRev" : "_fyvNH2W--_" 
}
{ 
  "_key" : "19988371", 
  "_id" : "example/19988371", 
  "_rev" : "_fyvNH2a---", 
  "d" : 3, 
  "c" : null, 
  "b" : null 
}
{ 
  "_id" : "example/19988371", 
  "_key" : "19988371", 
  "_rev" : "_fyvNH2e---", 
  "_oldRev" : "_fyvNH2a---" 
}
{ 
  "_key" : "19988371", 
  "_id" : "example/19988371", 
  "_rev" : "_fyvNH2e---" 
}

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");

{ 
  "_id" : "example/20774804", 
  "_key" : "20774804", 
  "_rev" : "_fyvNH2---_" 
}
{ 
  "_id" : "example/20774803", 
  "_key" : "20774803", 
  "_rev" : "_fyvNH2C---", 
  "_oldRev" : "_fyvNH2----" 
}
{ 
  "_key" : "20774803", 
  "_id" : "example/20774803", 
  "_rev" : "_fyvNH2C---", 
  "a" : { 
    "four" : 4 
  }, 
  "b" : { 
    "b1" : 1 
  } 
}
{ 
  "_id" : "example/20774803", 
  "_key" : "20774803", 
  "_rev" : "_fyvNH2C--_", 
  "_oldRev" : "_fyvNH2C---" 
}
{ 
  "_key" : "20774803", 
  "_id" : "example/20774803", 
  "_rev" : "_fyvNH2C--_", 
  "a" : { 
    "four" : 4 
  } 
}

Remove

collection.remove(selector)

Removes a document described by the selector, which must be an object containing the _id or _key attribute. There must be a document with that _id or _key in the current collection. This document is then removed.

The method returns a document with the attributes _id, _key and _rev. The attribute _id contains the document handle of the removed document, the attribute _rev contains the document revision of the removed document.

If the selector contains a _rev attribute, the method first checks that 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 following boolean attributes:

• waitForSync: One can force synchronization of the document creation operation to disk even in case that the waitForSync flag is been disabled for the entire collection. Thus, the waitForSync option can be used to force synchronization of just specific operations. To use this, set the waitForSync parameter to true. If the waitForSync parameter is not specified or set to false, then the collection’s default waitForSync behavior is applied. The waitForSync parameter cannot be used to disable synchronization for collections that have a default waitForSync value of true.
• overwrite: If this flag is set to true, a _rev attribute in the selector is ignored.
• returnOld: If this flag is set to true, the complete previous revision of the document is returned in the output under the attribute 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 as first 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 as first argument. No revision check is performed.

collection.remove(selector-array)

collection.remove(selector-array, options)

These two variants allow to perform the operation on a whole array of selectors. The behavior is exactly as if remove() would have been called on all members of the array separately and all results are returned in an array. If an error occurs with any of the documents, no exception is risen! Instead of a document an error object is returned in the result array. The options behave exactly 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);

{ 
  "_id" : "example/74306", 
  "_key" : "74306", 
  "_rev" : "_fyvNHxm--_" 
}
{ 
  "_key" : "74306", 
  "_id" : "example/74306", 
  "_rev" : "_fyvNHxm--_", 
  "a" : 1 
}
{ 
  "_id" : "example/74306", 
  "_key" : "74306", 
  "_rev" : "_fyvNHxm--_" 
}
[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);

{ 
  "_id" : "example/74292", 
  "_key" : "74292", 
  "_rev" : "_fyvNHxS---" 
}
{ 
  "_id" : "example/74292", 
  "_key" : "74292", 
  "_rev" : "_fyvNHxS--_", 
  "_oldRev" : "_fyvNHxS---" 
}
[ArangoError 1200: conflict, _rev values do not match]
{ 
  "_id" : "example/74292", 
  "_key" : "74292", 
  "_rev" : "_fyvNHxS--_" 
}
[ArangoError 1202: document not found]

Remove By Keys

collection.removeByKeys(keys)

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

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

This method is deprecated in favor 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);

[ ]
{ 
  "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 synchronization of the document deletion operation to disk even in case that the waitForSync flag had been disabled for the entire collection. Thus, the waitForSync parameter can be used to force synchronization of just specific operations. To use this, set the waitForSync parameter to true. If the waitForSync parameter is not specified or set to false, then the collection’s default waitForSync behavior is applied. The waitForSync parameter cannot be used to disable synchronization for collections that have a default waitForSync value of true.

collection.removeByExample(document, waitForSync, limit)

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

Examples

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

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 be replaced 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 synchronization of the document replacement operation to disk even in case that the waitForSync flag had been disabled for the entire collection. Thus, the waitForSync parameter can be used to force synchronization of just specific operations. To use this, set the waitForSync parameter to true. If the waitForSync parameter is not specified or set to false, then the collection’s default waitForSync behavior is applied. The waitForSync parameter cannot be used to disable synchronization for collections that have a default waitForSync value of true.

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

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

Examples

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

{ 
  "_id" : "example/196", 
  "_key" : "196", 
  "_rev" : "_fyvMKjy---" 
}
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 the example 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 when handling null values. Normally, null values are stored in the database. By setting the keepNull parameter to false, this behavior can be changed so that all attributes in data with null values will be removed from the target document.

The optional waitForSync parameter can be used to force synchronization of the document replacement operation to disk even in case that the waitForSync flag had been disabled for the entire collection. Thus, the waitForSync parameter can be used to force synchronization of just specific operations. To use this, set the waitForSync parameter to true. If the waitForSync parameter is not specified or set to false, then the collection’s default waitForSync behavior is applied. The waitForSync parameter cannot be used to disable synchronization for collections that have a default waitForSync value of true.

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

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

collection.updateByExample(document, newValue, options)

Using this variant, the options for the operation can be passed using an 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()

{ 
  "_id" : "example/207", 
  "_key" : "207", 
  "_rev" : "_fyvMKkG---" 
}
1
[ 
  { 
    "_key" : "207", 
    "_id" : "example/207", 
    "_rev" : "_fyvMKkK---", 
    "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 a valid document id.

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

Edges

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

edge-collection.edges(vertex)

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

edge-collection.edges(vertices)

The edges operator finds all edges starting from (outbound) or ending in (inbound) a document from vertices, which must be a list of documents or 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);

[ArangoCollection 61275, "vertex" (type document, status loaded)]
[ArangoCollection 61280, "relation" (type edge, status loaded)]
{ 
  "_id" : "vertex/61287", 
  "_key" : "61287", 
  "_rev" : "_fyvMSA---_" 
}
{ 
  "_id" : "vertex/61289", 
  "_key" : "61289", 
  "_rev" : "_fyvMSA---A" 
}
{ 
  "_id" : "relation/61291", 
  "_key" : "61291", 
  "_rev" : "_fyvMSAC---" 
}
{ 
  "_key" : "61291", 
  "_id" : "relation/61291", 
  "_from" : "vertex/61287", 
  "_to" : "vertex/61289", 
  "_rev" : "_fyvMSAC---", 
  "label" : "knows" 
}
[ ]

edge-collection.inEdges(vertex)

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

edge-collection.inEdges(vertices)

The inEdges() operator finds all edges ending in (inbound) a document from 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.inEdges(myGraph.v1._id);
arangosh> db.relation.inEdges(myGraph.v2._id);

[ArangoCollection 61299, "vertex" (type document, status loaded)]
[ArangoCollection 61304, "relation" (type edge, status loaded)]
{ 
  "_id" : "vertex/61311", 
  "_key" : "61311", 
  "_rev" : "_fyvMSAe---" 
}
{ 
  "_id" : "vertex/61313", 
  "_key" : "61313", 
  "_rev" : "_fyvMSAe--_" 
}
{ 
  "_id" : "relation/61315", 
  "_key" : "61315", 
  "_rev" : "_fyvMSAe--A" 
}
{ 
  "_key" : "61315", 
  "_id" : "relation/61315", 
  "_from" : "vertex/61311", 
  "_to" : "vertex/61313", 
  "_rev" : "_fyvMSAe--A", 
  "label" : "knows" 
}
[ ]
[ 
  { 
    "_key" : "61315", 
    "_id" : "relation/61315", 
    "_from" : "vertex/61311", 
    "_to" : "vertex/61313", 
    "_rev" : "_fyvMSAe--A", 
    "label" : "knows" 
  } 
]

edge-collection.outEdges(vertex)

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

edge-collection.outEdges(vertices)

The outEdges() operator finds all edges starting from (outbound) a document from 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);

[ArangoCollection 61325, "vertex" (type document, status loaded)]
[ArangoCollection 61330, "relation" (type edge, status loaded)]
{ 
  "_id" : "vertex/61337", 
  "_key" : "61337", 
  "_rev" : "_fyvMSB---_" 
}
{ 
  "_id" : "vertex/61339", 
  "_key" : "61339", 
  "_rev" : "_fyvMSBC---" 
}
{ 
  "_id" : "relation/61341", 
  "_key" : "61341", 
  "_rev" : "_fyvMSBC--_" 
}
{ 
  "_key" : "61341", 
  "_id" : "relation/61341", 
  "_from" : "vertex/61337", 
  "_to" : "vertex/61339", 
  "_rev" : "_fyvMSBC--_", 
  "label" : "knows" 
}
[ 
  { 
    "_key" : "61341", 
    "_id" : "relation/61341", 
    "_from" : "vertex/61337", 
    "_to" : "vertex/61339", 
    "_rev" : "_fyvMSBC--_", 
    "label" : "knows" 
  } 
]
[ ]

Misc

collection.iterate(iterator, options)

Iterates over some elements of the collection and apply the function iterator to the elements. The function will be called with the document as first argument and the current number (starting with 0) as second argument.

options must be an object with the following attributes:

• limit (optional, default none): use at most limit documents.

• probability (optional, default all): a number between 0 and 1. Documents are chosen with this probability.

Examples

arangosh> for (i = -90;  i <= 90;  i += 10) {
........>  for (j = -180;  j <= 180;  j += 10) {
........>    db.example.insert({ name : "Name/" + i + "/" + j,
........>                      home : [ i, j ],
........>                      work : [ -i, -j ] });
........>  }
........> }
........> 
arangosh> db.example.ensureIndex({ type: "geo", fields: [ "home" ] });
arangosh> items = db.example.getIndexes().map(function(x) { return x.id; });
........> db.example.index(items[1]);

{ 
  "bestIndexedLevel" : 17, 
  "fields" : [ 
    "home" 
  ], 
  "geoJson" : false, 
  "id" : "example/72416", 
  "isNewlyCreated" : true, 
  "legacyPolygons" : false, 
  "maxNumCoverCells" : 8, 
  "name" : "idx_1762249898571333633", 
  "sparse" : true, 
  "type" : "geo", 
  "unique" : false, 
  "worstIndexedLevel" : 4, 
  "code" : 201 
}
[ 
  "example/0", 
  "example/72416" 
]