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

Show execution results

Hide execution results

{ 
  "_id" : "five/117", 
  "_key" : "117", 
  "_rev" : "_dAzO9si---" 
}
{ 
  "_id" : "five/119", 
  "_key" : "119", 
  "_rev" : "_dAzO9sm---" 
}
{ 
  "_id" : "five/121", 
  "_key" : "121", 
  "_rev" : "_dAzO9sm--A" 
}
{ 
  "_id" : "five/123", 
  "_key" : "123", 
  "_rev" : "_dAzO9sq---" 
}
{ 
  "_id" : "five/125", 
  "_key" : "125", 
  "_rev" : "_dAzO9sq--A" 
}
[ 
  { 
    "_key" : "117", 
    "_id" : "five/117", 
    "_rev" : "_dAzO9si---", 
    "name" : "one" 
  }, 
  { 
    "_key" : "119", 
    "_id" : "five/119", 
    "_rev" : "_dAzO9sm---", 
    "name" : "two" 
  }, 
  { 
    "_key" : "121", 
    "_id" : "five/121", 
    "_rev" : "_dAzO9sm--A", 
    "name" : "three" 
  }, 
  { 
    "_key" : "123", 
    "_id" : "five/123", 
    "_rev" : "_dAzO9sq---", 
    "name" : "four" 
  }, 
  { 
    "_key" : "125", 
    "_id" : "five/125", 
    "_rev" : "_dAzO9sq--A", 
    "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/137", 
  "_key" : "137", 
  "_rev" : "_dAzO9t6---" 
}
{ 
  "_id" : "five/139", 
  "_key" : "139", 
  "_rev" : "_dAzO9t6--A" 
}
{ 
  "_id" : "five/141", 
  "_key" : "141", 
  "_rev" : "_dAzO9u----" 
}
{ 
  "_id" : "five/143", 
  "_key" : "143", 
  "_rev" : "_dAzO9u---A" 
}
{ 
  "_id" : "five/145", 
  "_key" : "145", 
  "_rev" : "_dAzO9uC---" 
}
[ 
  { 
    "_key" : "137", 
    "_id" : "five/137", 
    "_rev" : "_dAzO9t6---", 
    "name" : "one" 
  }, 
  { 
    "_key" : "139", 
    "_id" : "five/139", 
    "_rev" : "_dAzO9t6--A", 
    "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();

Show execution results

Hide execution results

{ 
  "_id" : "users/157", 
  "_key" : "157", 
  "_rev" : "_dAzO9ua--A" 
}
{ 
  "_id" : "users/159", 
  "_key" : "159", 
  "_rev" : "_dAzO9ue---" 
}
{ 
  "_id" : "users/161", 
  "_key" : "161", 
  "_rev" : "_dAzO9ue--A" 
}
[ 
  { 
    "_key" : "157", 
    "_id" : "users/157", 
    "_rev" : "_dAzO9ua--A", 
    "name" : "Gerhard" 
  }, 
  { 
    "_key" : "159", 
    "_id" : "users/159", 
    "_rev" : "_dAzO9ue---", 
    "name" : "Helmut" 
  }, 
  { 
    "_key" : "161", 
    "_id" : "users/161", 
    "_rev" : "_dAzO9ue--A", 
    "name" : "Angela" 
  } 
]
[ ]
[ 
  { 
    "_key" : "157", 
    "_id" : "users/157", 
    "_rev" : "_dAzO9ua--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/179", 
  "_key" : "179", 
  "_rev" : "_dAzO9vC---" 
}
{ 
  "_id" : "users/181", 
  "_key" : "181", 
  "_rev" : "_dAzO9vC--A" 
}
{ 
  "_id" : "users/183", 
  "_key" : "183", 
  "_rev" : "_dAzO9vG---" 
}
{ 
  "_key" : "183", 
  "_id" : "users/183", 
  "_rev" : "_dAzO9vG---", 
  "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");

Show execution results

Hide execution results

{ 
  "_key" : "75628", 
  "_id" : "users/75628", 
  "_rev" : "_dAzP03W---", 
  "name" : "Angela" 
}

Range

collection.range(attribute, left, right)

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

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.

Note: the range simple query function is deprecated as of ArangoDB 2.6. The function may be removed in future versions of ArangoDB. The preferred way for retrieving documents from a collection within a specific range is 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/194", 
  "isNewlyCreated" : true, 
  "name" : "idx_1712165072807133184", 
  "selectivityEstimate" : 1, 
  "sparse" : false, 
  "type" : "skiplist", 
  "unique" : false, 
  "code" : 201 
}
{ 
  "_id" : "old/198", 
  "_key" : "198", 
  "_rev" : "_dAzO9vi---" 
}
{ 
  "_id" : "old/200", 
  "_key" : "200", 
  "_rev" : "_dAzO9vm---" 
}
{ 
  "_id" : "old/202", 
  "_key" : "202", 
  "_rev" : "_dAzO9vm--A" 
}
[ 
  { 
    "_key" : "198", 
    "_id" : "old/198", 
    "_rev" : "_dAzO9vi---", 
    "age" : 15 
  }, 
  { 
    "_key" : "200", 
    "_id" : "old/200", 
    "_rev" : "_dAzO9vm---", 
    "age" : 25 
  } 
]

Closed range

collection.closedRange(attribute, left, right)

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

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.

Note: the closedRange simple query function is deprecated as of ArangoDB 2.6. The function may be removed in future versions of ArangoDB. The preferred way for retrieving documents from a collection within a specific range is 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/214", 
  "isNewlyCreated" : true, 
  "name" : "idx_1712165072817618946", 
  "selectivityEstimate" : 1, 
  "sparse" : false, 
  "type" : "skiplist", 
  "unique" : false, 
  "code" : 201 
}
{ 
  "_id" : "old/218", 
  "_key" : "218", 
  "_rev" : "_dAzO9wK---" 
}
{ 
  "_id" : "old/220", 
  "_key" : "220", 
  "_rev" : "_dAzO9wO---" 
}
{ 
  "_id" : "old/222", 
  "_key" : "222", 
  "_rev" : "_dAzO9wO--A" 
}
[ 
  { 
    "_key" : "218", 
    "_id" : "old/218", 
    "_rev" : "_dAzO9wK---", 
    "age" : 15 
  }, 
  { 
    "_key" : "220", 
    "_id" : "old/220", 
    "_rev" : "_dAzO9wO---", 
    "age" : 25 
  }, 
  { 
    "_key" : "222", 
    "_id" : "old/222", 
    "_rev" : "_dAzO9wO--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 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 collecion.

Document

collection.document(object)

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.

collection.document(document-handle)

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)

As before. Instead of object a document-key can be passed as first 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 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");

Show execution results

Hide execution results

{ 
  "_key" : "2873916", 
  "_id" : "example/2873916", 
  "_rev" : "_dAzP1Cm--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" : "_dAzP1B2---" 
}

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" : "_dAzP1CG---" 
}

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" : "_dAzP1CW---" 
  }, 
  { 
    "_key" : "2873917", 
    "_id" : "example/2873917", 
    "_rev" : "_dAzP1Ca---" 
  } 
]

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 identifier]

Changes in 3.0 from 2.8:

document can now query multiple documents with one call.

Exists

checks whether a document exists collection.exists(object)

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.

collection.exists(document-handle)

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

collection.exists(document-key)

As before. Instead of object a document-key can be passed as first 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 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.

Changes in 3.0 from 2.8:

In the case of a revision mismatch exists now throws an error instead of simply returning false. This is to make it possible to tell the difference 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 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 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" : "_dAzP04y--A", 
      "value" : 0 
    }, 
    { 
      "_key" : "test1", 
      "_id" : "example/test1", 
      "_rev" : "_dAzP042---", 
      "value" : 1 
    }, 
    { 
      "_key" : "test2", 
      "_id" : "example/test2", 
      "_rev" : "_dAzP042--A", 
      "value" : 2 
    }, 
    { 
      "_key" : "test3", 
      "_id" : "example/test3", 
      "_rev" : "_dAzP046---", 
      "value" : 3 
    }, 
    { 
      "_key" : "test4", 
      "_id" : "example/test4", 
      "_rev" : "_dAzP046--A", 
      "value" : 4 
    }, 
    { 
      "_key" : "test5", 
      "_id" : "example/test5", 
      "_rev" : "_dAzP046--C", 
      "value" : 5 
    }, 
    { 
      "_key" : "test6", 
      "_id" : "example/test6", 
      "_rev" : "_dAzP046--E", 
      "value" : 6 
    }, 
    { 
      "_key" : "test7", 
      "_id" : "example/test7", 
      "_rev" : "_dAzP05----", 
      "value" : 7 
    }, 
    { 
      "_key" : "test8", 
      "_id" : "example/test8", 
      "_rev" : "_dAzP05---A", 
      "value" : 8 
    }, 
    { 
      "_key" : "test9", 
      "_id" : "example/test9", 
      "_rev" : "_dAzP05---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. 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.

Changes in 3.0 from 2.8:

The options silent and returnNew are new. The method can now insert multiple 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/75954", 
  "_key" : "75954", 
  "_rev" : "_dAzP1Ai---" 
}
{ 
  "_id" : "example/75956", 
  "_key" : "75956", 
  "_rev" : "_dAzP1Ai--A" 
}

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

Show execution results

Hide execution results

[ 
  { 
    "_id" : "example/75941", 
    "_key" : "75941", 
    "_rev" : "_dAzP1AC---" 
  }, 
  { 
    "_id" : "example/75942", 
    "_key" : "75942", 
    "_rev" : "_dAzP1AC--A" 
  } 
]
[ 
  { 
    "_id" : "example/75944", 
    "_key" : "75944", 
    "_rev" : "_dAzP1AC--C" 
  }, 
  { 
    "_id" : "example/75945", 
    "_key" : "75945", 
    "_rev" : "_dAzP1AC--E" 
  } 
]

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" : "_dAzP1B----" 
}
{ 
  "_id" : "example/666", 
  "_key" : "666", 
  "_rev" : "_dAzP1B---A", 
  "_oldRev" : "_dAzP1B----", 
  "old" : { 
    "_key" : "666", 
    "_id" : "example/666", 
    "_rev" : "_dAzP1B----", 
    "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(selectorarray, dataarray)

collection.replace(selectorarray, dataarray, options)

These two variants allow to perform the operation on a whole array of selector/data pairs. The two arrays given as selectorarray and dataarray 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 });

Show execution results

Hide execution results

{ 
  "_id" : "example/76083", 
  "_key" : "76083", 
  "_rev" : "_dAzP1E---A" 
}
{ 
  "_id" : "example/76083", 
  "_key" : "76083", 
  "_rev" : "_dAzP1E---C", 
  "_oldRev" : "_dAzP1E---A" 
}
[ArangoError 1200: conflict]

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" : "_dAzP1EO--C" 
}
{ 
  "_id" : "example/3903044", 
  "_key" : "3903044", 
  "_rev" : "_dAzP1ES---", 
  "_oldRev" : "_dAzP1EO--A" 
}

Changes in 3.0 from 2.8:

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

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(selectorarray, dataarray)

collection.update(selectorarray, dataarray, options)

These two variants allow to perform the operation on a whole array of selector/data pairs. The two arrays given as selectorarray and dataarray 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);

Show execution results

Hide execution results

{ 
  "_id" : "example/76163", 
  "_key" : "76163", 
  "_rev" : "_dAzP1G---A" 
}
{ 
  "_id" : "example/76163", 
  "_key" : "76163", 
  "_rev" : "_dAzP1GC---", 
  "_oldRev" : "_dAzP1G---A" 
}
[ArangoError 1200: conflict]
{ 
  "_id" : "example/76163", 
  "_key" : "76163", 
  "_rev" : "_dAzP1GG---", 
  "_oldRev" : "_dAzP1GC---" 
}
{ 
  "_key" : "76163", 
  "_id" : "example/76163", 
  "_rev" : "_dAzP1GG---", 
  "a" : 1, 
  "c" : 3, 
  "b" : 2, 
  "f" : 6, 
  "e" : 5 
}
{ 
  "_id" : "example/76163", 
  "_key" : "76163", 
  "_rev" : "_dAzP1GK---", 
  "_oldRev" : "_dAzP1GG---" 
}
{ 
  "_key" : "76163", 
  "_id" : "example/76163", 
  "_rev" : "_dAzP1GK---", 
  "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" : "_dAzP1Ha--A" 
}
{ 
  "_id" : "example/18612115", 
  "_key" : "18612115", 
  "_rev" : "_dAzP1Ha--C", 
  "_oldRev" : "_dAzP1Ha---" 
}

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" : "_dAzP1G6--A" 
}
{ 
  "_id" : "example/19988371", 
  "_key" : "19988371", 
  "_rev" : "_dAzP1H----", 
  "_oldRev" : "_dAzP1G6---" 
}
{ 
  "_key" : "19988371", 
  "_id" : "example/19988371", 
  "_rev" : "_dAzP1H----", 
  "b" : null, 
  "d" : 3, 
  "c" : null 
}
{ 
  "_id" : "example/19988371", 
  "_key" : "19988371", 
  "_rev" : "_dAzP1HG---", 
  "_oldRev" : "_dAzP1H----" 
}
{ 
  "_key" : "19988371", 
  "_id" : "example/19988371", 
  "_rev" : "_dAzP1HG---", 
  "b" : null, 
  "d" : 3, 
  "c" : null 
}
{ 
  "_id" : "example/19988371", 
  "_key" : "19988371", 
  "_rev" : "_dAzP1HG--A", 
  "_oldRev" : "_dAzP1HG---" 
}
{ 
  "_key" : "19988371", 
  "_id" : "example/19988371", 
  "_rev" : "_dAzP1HG--A" 
}

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" : "_dAzP1Ge--A" 
}
{ 
  "_id" : "example/20774803", 
  "_key" : "20774803", 
  "_rev" : "_dAzP1Gi---", 
  "_oldRev" : "_dAzP1Ge---" 
}
{ 
  "_key" : "20774803", 
  "_id" : "example/20774803", 
  "_rev" : "_dAzP1Gi---", 
  "b" : { 
    "b1" : 1 
  }, 
  "a" : { 
    "four" : 4 
  } 
}
{ 
  "_id" : "example/20774803", 
  "_key" : "20774803", 
  "_rev" : "_dAzP1Gm---", 
  "_oldRev" : "_dAzP1Gi---" 
}
{ 
  "_key" : "20774803", 
  "_id" : "example/20774803", 
  "_rev" : "_dAzP1Gm---", 
  "a" : { 
    "four" : 4 
  } 
}

Changes in 3.0 from 2.8:

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

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

collection.remove(selectorarray,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);

Show execution results

Hide execution results

{ 
  "_id" : "example/75906", 
  "_key" : "75906", 
  "_rev" : "_dAzP1_K--A" 
}
{ 
  "_key" : "75906", 
  "_id" : "example/75906", 
  "_rev" : "_dAzP1_K--A", 
  "a" : 1 
}
{ 
  "_id" : "example/75906", 
  "_key" : "75906", 
  "_rev" : "_dAzP1_K--A" 
}
[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/75892", 
  "_key" : "75892", 
  "_rev" : "_dAzP1-y--A" 
}
{ 
  "_id" : "example/75892", 
  "_key" : "75892", 
  "_rev" : "_dAzP1-2---", 
  "_oldRev" : "_dAzP1-y--A" 
}
[ArangoError 1200: conflict]
{ 
  "_id" : "example/75892", 
  "_key" : "75892", 
  "_rev" : "_dAzP1-2---" 
}
[ArangoError 1202: document not found]

Changes in 3.0 from 2.8:

The method now returns not only true but information about the removed document(s). The options silent and returnOld are new. The method can 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 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 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 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"} );

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

Show execution results

Hide execution results

{ 
  "_id" : "example/4511", 
  "_key" : "4511", 
  "_rev" : "_dAzP-ea---" 
}
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()

Show execution results

Hide execution results

{ 
  "_id" : "example/4522", 
  "_key" : "4522", 
  "_rev" : "_dAzP-e2---" 
}
1
[ 
  { 
    "_key" : "4522", 
    "_id" : "example/4522", 
    "_rev" : "_dAzP-e6---", 
    "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);