!CHAPTER Collection Methods !SUBSECTION All constructs an all query for a collection `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: @startDocuBlockInline 001_collectionAll @EXAMPLE_ARANGOSH_OUTPUT{001_collectionAll} ~ db._create("five"); db.five.save({ name : "one" }); db.five.save({ name : "two" }); db.five.save({ name : "three" }); db.five.save({ name : "four" }); db.five.save({ name : "five" }); db.five.all().toArray(); ~ db._drop("five"); @END_EXAMPLE_ARANGOSH_OUTPUT @endDocuBlock 001_collectionAll Use *limit* to restrict the documents: @startDocuBlockInline 002_collectionAllNext @EXAMPLE_ARANGOSH_OUTPUT{002_collectionAllNext} ~ db._create("five"); db.five.save({ name : "one" }); db.five.save({ name : "two" }); db.five.save({ name : "three" }); db.five.save({ name : "four" }); db.five.save({ name : "five" }); db.five.all().limit(2).toArray(); ~ db._drop("five"); @END_EXAMPLE_ARANGOSH_OUTPUT @endDocuBlock 002_collectionAllNext !SUBSECTION Query by example constructs a query-by-example for a collection `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 ```json { 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 ```json { a : { c : 1 }, b : 1 } ``` will match, but the document ```json { a : { c : 1, b : 1 } } ``` will not. However, if you use ```json { 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 ```json { a : { c : 1 }, b : 1 } ``` and ```json { 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: @startDocuBlockInline 003_collectionByExample @EXAMPLE_ARANGOSH_OUTPUT{003_collectionByExample} ~ db._create("users"); db.users.save({ name: "Gerhard" }); db.users.save({ name: "Helmut" }); db.users.save({ name: "Angela" }); db.users.all().toArray(); db.users.byExample({ "_id" : "users/20" }).toArray(); db.users.byExample({ "name" : "Gerhard" }).toArray(); db.users.byExample({ "name" : "Helmut", "_id" : "users/15" }).toArray(); ~ db._drop("users"); @END_EXAMPLE_ARANGOSH_OUTPUT @endDocuBlock 003_collectionByExample Use *next* to loop over all documents: @startDocuBlockInline 004_collectionByExampleNext @EXAMPLE_ARANGOSH_OUTPUT{004_collectionByExampleNext} ~ db._create("users"); db.users.save({ name: "Gerhard" }); db.users.save({ name: "Helmut" }); db.users.save({ name: "Angela" }); var a = db.users.byExample( {"name" : "Angela" } ); while (a.hasNext()) print(a.next()); ~ db._drop("users"); @END_EXAMPLE_ARANGOSH_OUTPUT @endDocuBlock 004_collectionByExampleNext !SUBSECTION First Example constructs a query-by-example for a collection `collection.firstExample(example)` Returns the first 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** @startDocuBlockInline collectionFirstExample @EXAMPLE_ARANGOSH_OUTPUT{collectionFirstExample} ~ db._create("users"); ~ db.users.save({ name: "Gerhard" }); ~ db.users.save({ name: "Helmut" }); ~ db.users.save({ name: "Angela" }); db.users.firstExample("name", "Angela"); ~ db._drop("users"); @END_EXAMPLE_ARANGOSH_OUTPUT @endDocuBlock collectionFirstExample !SUBSECTION Range constructs a range query for a collection `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. For range queries it is required that a skiplist index is present for the queried attribute. If no skiplist index is present on the attribute, an error will be thrown. 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: @startDocuBlockInline 005_collectionRange @EXAMPLE_ARANGOSH_OUTPUT{005_collectionRange} ~ db._create("old"); db.old.ensureIndex({ type: "skiplist", fields: [ "age" ] }); db.old.save({ age: 15 }); db.old.save({ age: 25 }); db.old.save({ age: 30 }); db.old.range("age", 10, 30).toArray(); ~ db._drop("old") @END_EXAMPLE_ARANGOSH_OUTPUT @endDocuBlock 005_collectionRange !SUBSECTION Closed range constructs a closed range query for a collection `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: @startDocuBlockInline 006_collectionClosedRange @EXAMPLE_ARANGOSH_OUTPUT{006_collectionClosedRange} ~ db._create("old"); db.old.ensureIndex({ type: "skiplist", fields: [ "age" ] }); db.old.save({ age: 15 }); db.old.save({ age: 25 }); db.old.save({ age: 30 }); db.old.closedRange("age", 10, 30).toArray(); ~ db._drop("old") @END_EXAMPLE_ARANGOSH_OUTPUT @endDocuBlock 006_collectionClosedRange !SUBSECTION Any returns any document from a collection `collection.any()` Returns a random document from the collection or *null* if none exists. !SUBSECTION Count counts the number of documents in a result set `collection.count()` Returns the number of living documents in the collection. **Examples** @startDocuBlockInline collectionCount @EXAMPLE_ARANGOSH_OUTPUT{collectionCount} ~ db._create("users"); db.users.count(); ~ db._drop("users"); @END_EXAMPLE_ARANGOSH_OUTPUT @endDocuBlock collectionCount !SUBSECTION toArray converts collection into an array `collection.toArray()` Converts the collection into an array of documents. Never use this call in a production environment. !SUBSECTION Document looks up a document `collection.document(document)` The *document* method finds a document given its identifier or a document object containing the *_id* or *_key* attribute. The method returns the document if it can be found. 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 document a *document-handle* can be passed as first argument. *Examples* Returns the document for a document-handle: @startDocuBlockInline documentsCollectionNameValid @EXAMPLE_ARANGOSH_OUTPUT{documentsCollectionNameValid} ~ db._create("example"); ~ var myid = db.example.insert({_key: "2873916"}); db.example.document("example/2873916"); ~ db._drop("example"); @END_EXAMPLE_ARANGOSH_OUTPUT @endDocuBlock documentsCollectionNameValid An error is raised if the document is unknown: @startDocuBlockInline documentsCollectionNameUnknown @EXAMPLE_ARANGOSH_OUTPUT{documentsCollectionNameUnknown} ~ db._create("example"); ~ var myid = db.example.insert({_key: "2873916"}); db.example.document("example/4472917"); // xpError(ERROR_ARANGO_DOCUMENT_NOT_FOUND) ~ db._drop("example"); @END_EXAMPLE_ARANGOSH_OUTPUT @endDocuBlock documentsCollectionNameUnknown An error is raised if the handle is invalid: @startDocuBlockInline documentsCollectionNameHandle @EXAMPLE_ARANGOSH_OUTPUT{documentsCollectionNameHandle} ~ db._create("example"); db.example.document(""); // xpError(ERROR_ARANGO_DOCUMENT_HANDLE_BAD) ~ db._drop("example"); @END_EXAMPLE_ARANGOSH_OUTPUT @endDocuBlock documentsCollectionNameHandle !SUBSECTION Exists checks whether a document exists `collection.exists(document)` The *exists* method determines whether a document exists given its identifier. Instead of returning the found document or an error, this method will return either *true* or *false*. It can thus be used for easy existence checks. The *document* method finds a document given its identifier. It returns the document. Note that the returned document contains two pseudo-attributes, namely *_id* and *_rev*. *_id* contains the document-handle and *_rev* the revision of the document. No error will be thrown if the sought document or collection does not exist. Still 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 document a *document-handle* can be passed as first argument. !SUBSECTION Lookup By Keys fetches multiple documents by their 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. **Examples** @startDocuBlockInline collectionLookupByKeys @EXAMPLE_ARANGOSH_OUTPUT{collectionLookupByKeys} ~ db._drop("example"); ~ db._create("example"); keys = [ ]; | for (var i = 0; i < 10; ++i) { | db.example.insert({ _key: "test" + i, value: i }); | keys.push("test" + i); } db.example.documents(keys); ~ db._drop("example"); @END_EXAMPLE_ARANGOSH_OUTPUT @endDocuBlock collectionLookupByKeys !SUBSECTION Insert insert a new document `collection.insert(data)` Creates a new document in the *collection* from the given *data*. The *data* must be an object. The method returns a document with the attributes *_id* and *_rev*. The attribute *_id* contains the document handle of the newly created document, the attribute *_rev* contains the document revision. `collection.insert(data, waitForSync)` Creates a new document in the *collection* from the given *data* as above. The optional *waitForSync* parameter can be used to force synchronization of the document creation 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*. Note: since ArangoDB 2.2, *insert* is an alias for *save*. **Examples** @startDocuBlockInline documentsCollectionInsert @EXAMPLE_ARANGOSH_OUTPUT{documentsCollectionInsert} ~ db._create("example"); db.example.insert({ Hello : "World" }); db.example.insert({ Hello : "World" }, true); ~ db._drop("example"); @END_EXAMPLE_ARANGOSH_OUTPUT @endDocuBlock documentsCollectionInsert !SUBSECTION Replace replaces a document `collection.replace(document, data)` Replaces an existing *document*. The *document* must be a document in the current collection. This document is then replaced with the *data* given as second argument. The method returns a document with the attributes *_id*, *_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 there is a conflict, i. e. if the revision of the *document* does not match the revision in the collection, then an error is thrown. `collection.replace(document, data, true)` or `collection.replace(document, data, overwrite: true)` As before, but in case of a conflict, the conflict is ignored and the old document is overwritten. `collection.replace(document, data, true, waitForSync)` or `collection.replace(document, data, overwrite: true, waitForSync: true or false)` 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.replace(document-handle, data)` As before. Instead of document a *document-handle* can be passed as first argument. **Examples** Create and update a document: @startDocuBlockInline documentsCollectionReplace1 @EXAMPLE_ARANGOSH_OUTPUT{documentsCollectionReplace1} ~ db._create("example"); a1 = db.example.insert({ a : 1 }); a2 = db.example.replace(a1, { a : 2 }); a3 = db.example.replace(a1, { a : 3 }); // xpError(ERROR_ARANGO_CONFLICT); ~ db._drop("example"); @END_EXAMPLE_ARANGOSH_OUTPUT @endDocuBlock documentsCollectionReplace1 Use a document handle: @startDocuBlockInline documentsCollectionReplaceHandle @EXAMPLE_ARANGOSH_OUTPUT{documentsCollectionReplaceHandle} ~ db._create("example"); ~ var myid = db.example.insert({_key: "3903044"}); a1 = db.example.insert({ a : 1 }); a2 = db.example.replace("example/3903044", { a : 2 }); ~ db._drop("example"); @END_EXAMPLE_ARANGOSH_OUTPUT @endDocuBlock documentsCollectionReplaceHandle !SUBSECTION Update updates a document `collection.update(document, data, overwrite, keepNull, waitForSync)` or `collection.update(document, data, overwrite: true or false, keepNull: true or false, waitForSync: true or false)` Updates an existing *document*. The *document* must be a document in the current collection. This document is then patched with the *data* given as second argument. The optional *overwrite* parameter can be used to control the behavior in case of version conflicts (see below). 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 update 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*. The method returns a document with the attributes *_id*, *_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 there is a conflict, i. e. if the revision of the *document* does not match the revision in the collection, then an error is thrown. `collection.update(document, data, true)` As before, but in case of a conflict, the conflict is ignored and the old document is overwritten. collection.update(document-handle, data)` As before. Instead of document a document-handle can be passed as first argument. *Examples* Create and update a document: @startDocuBlockInline documentsCollection_UpdateDocument @EXAMPLE_ARANGOSH_OUTPUT{documentsCollection_UpdateDocument} ~ db._create("example"); a1 = db.example.insert({"a" : 1}); a2 = db.example.update(a1, {"b" : 2, "c" : 3}); a3 = db.example.update(a1, {"d" : 4}); // xpError(ERROR_ARANGO_CONFLICT); a4 = db.example.update(a2, {"e" : 5, "f" : 6 }); db.example.document(a4); a5 = db.example.update(a4, {"a" : 1, c : 9, e : 42 }); db.example.document(a5); ~ db._drop("example"); @END_EXAMPLE_ARANGOSH_OUTPUT @endDocuBlock documentsCollection_UpdateDocument Use a document handle: @startDocuBlockInline documentsCollection_UpdateHandleSingle @EXAMPLE_ARANGOSH_OUTPUT{documentsCollection_UpdateHandleSingle} ~ db._create("example"); ~ var myid = db.example.insert({_key: "18612115"}); a1 = db.example.insert({"a" : 1}); a2 = db.example.update("example/18612115", { "x" : 1, "y" : 2 }); ~ db._drop("example"); @END_EXAMPLE_ARANGOSH_OUTPUT @endDocuBlock documentsCollection_UpdateHandleSingle Use the keepNull parameter to remove attributes with null values: @startDocuBlockInline documentsCollection_UpdateHandleKeepNull @EXAMPLE_ARANGOSH_OUTPUT{documentsCollection_UpdateHandleKeepNull} ~ db._create("example"); ~ var myid = db.example.insert({_key: "19988371"}); db.example.insert({"a" : 1}); |db.example.update("example/19988371", { "b" : null, "c" : null, "d" : 3 }); db.example.document("example/19988371"); db.example.update("example/19988371", { "a" : null }, false, false); db.example.document("example/19988371"); | db.example.update("example/19988371", { "b" : null, "c": null, "d" : null }, false, false); db.example.document("example/19988371"); ~ db._drop("example"); @END_EXAMPLE_ARANGOSH_OUTPUT @endDocuBlock documentsCollection_UpdateHandleKeepNull Patching array values: @startDocuBlockInline documentsCollection_UpdateHandleArray @EXAMPLE_ARANGOSH_OUTPUT{documentsCollection_UpdateHandleArray} ~ db._create("example"); ~ var myid = db.example.insert({_key: "20774803"}); | db.example.insert({"a" : { "one" : 1, "two" : 2, "three" : 3 }, "b" : { }}); | db.example.update("example/20774803", {"a" : { "four" : 4 }, "b" : { "b1" : 1 }}); db.example.document("example/20774803"); | db.example.update("example/20774803", { "a" : { "one" : null }, | "b" : null }, false, false); db.example.document("example/20774803"); ~ db._drop("example"); @END_EXAMPLE_ARANGOSH_OUTPUT @endDocuBlock documentsCollection_UpdateHandleArray !SUBSECTION Remove removes a document `collection.remove(document)` Removes a document. If there is revision mismatch, then an error is thrown. `collection.remove(document, true)` Removes a document. If there is revision mismatch, then mismatch is ignored and document is deleted. The function returns *true* if the document existed and was deleted. It returns *false*, if the document was already deleted. `collection.remove(document, true, 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.remove(document-handle, data)` As before. Instead of document a *document-handle* can be passed as first argument. **Examples** Remove a document: @startDocuBlockInline documentDocumentRemoveSimple @EXAMPLE_ARANGOSH_OUTPUT{documentDocumentRemoveSimple} ~ db._create("example"); a1 = db.example.insert({ a : 1 }); db.example.document(a1); db.example.remove(a1); db.example.document(a1); // xpError(ERROR_ARANGO_DOCUMENT_NOT_FOUND); ~ db._drop("example"); @END_EXAMPLE_ARANGOSH_OUTPUT @endDocuBlock documentDocumentRemoveSimple Remove a document with a conflict: @startDocuBlockInline documentDocumentRemoveConflict @EXAMPLE_ARANGOSH_OUTPUT{documentDocumentRemoveConflict} ~ db._create("example"); a1 = db.example.insert({ a : 1 }); a2 = db.example.replace(a1, { a : 2 }); db.example.remove(a1); // xpError(ERROR_ARANGO_CONFLICT); db.example.remove(a1, true); db.example.document(a1); // xpError(ERROR_ARANGO_DOCUMENT_NOT_FOUND); ~ db._drop("example"); @END_EXAMPLE_ARANGOSH_OUTPUT @endDocuBlock documentDocumentRemoveConflict !SUBSECTION Remove By Keys removes multiple documents by their 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. **Examples** @startDocuBlockInline collectionRemoveByKeys @EXAMPLE_ARANGOSH_OUTPUT{collectionRemoveByKeys} ~ db._drop("example"); ~ db._create("example"); keys = [ ]; | for (var i = 0; i < 10; ++i) { | db.example.insert({ _key: "test" + i, value: i }); | keys.push("test" + i); } db.example.removeByKeys(keys); ~ db._drop("example"); @END_EXAMPLE_ARANGOSH_OUTPUT @endDocuBlock collectionRemoveByKeys !SUBSECTION Remove By Example removes documents matching an 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** @startDocuBlockInline 010_documentsCollectionRemoveByExample @EXAMPLE_ARANGOSH_OUTPUT{010_documentsCollectionRemoveByExample} ~ db._create("example"); ~ db.example.save({ Hello : "world" }); db.example.removeByExample( {Hello : "world"} ); ~ db._drop("example"); @END_EXAMPLE_ARANGOSH_OUTPUT @endDocuBlock 010_documentsCollectionRemoveByExample !SUBSECTION Replace By Example replaces documents matching an 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** @startDocuBlockInline 011_documentsCollectionReplaceByExample @EXAMPLE_ARANGOSH_OUTPUT{011_documentsCollectionReplaceByExample} ~ db._create("example"); db.example.save({ Hello : "world" }); db.example.replaceByExample({ Hello: "world" }, {Hello: "mars"}, false, 5); ~ db._drop("example"); @END_EXAMPLE_ARANGOSH_OUTPUT @endDocuBlock 011_documentsCollectionReplaceByExample !SUBSECTION Update By Example partially updates documents matching an 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** @startDocuBlockInline 012_documentsCollectionUpdateByExample @EXAMPLE_ARANGOSH_OUTPUT{012_documentsCollectionUpdateByExample} ~ db._create("example"); db.example.save({ Hello : "world", foo : "bar" }); db.example.updateByExample({ Hello: "world" }, { Hello: "foo", World: "bar" }, false); db.example.byExample({ Hello: "foo" }).toArray() ~ db._drop("example"); @END_EXAMPLE_ARANGOSH_OUTPUT @endDocuBlock 012_documentsCollectionUpdateByExample !SUBSECTION First selects the n first documents in the collection `collection.first(count)` The *first* method returns the n first documents from the collection, in order of document insertion/update time. If called with the *count* argument, the result is a list of up to *count* documents. If *count* is bigger than the number of documents in the collection, then the result will contain as many documents as there are in the collection. The result list is ordered, with the "oldest" documents being positioned at the beginning of the result list. When called without an argument, the result is the first document from the collection. If the collection does not contain any documents, the result returned is *null*. **Note**: this method is not supported in sharded collections with more than one shard. **Examples** @startDocuBlockInline documentsCollectionFirstSuccess @EXAMPLE_ARANGOSH_OUTPUT{documentsCollectionFirstSuccess} ~ db._create("example"); ~ db.example.save({ Hello : "world" }); ~ db.example.save({ Foo : "bar" }); db.example.first(1); ~ db._drop("example"); @END_EXAMPLE_ARANGOSH_OUTPUT @endDocuBlock documentsCollectionFirstSuccess @startDocuBlockInline documentsCollectionFirstNull @EXAMPLE_ARANGOSH_OUTPUT{documentsCollectionFirstNull} ~ db._create("example"); ~ db.example.save({ Hello : "world" }); db.example.first(); ~ db._drop("example"); @END_EXAMPLE_ARANGOSH_OUTPUT @endDocuBlock documentsCollectionFirstNull !SUBSECTION Last selects the n last documents in the collection `collection.last(count)` The *last* method returns the n last documents from the collection, in order of document insertion/update time. If called with the *count* argument, the result is a list of up to *count* documents. If *count* is bigger than the number of documents in the collection, then the result will contain as many documents as there are in the collection. The result list is ordered, with the "latest" documents being positioned at the beginning of the result list. When called without an argument, the result is the last document from the collection. If the collection does not contain any documents, the result returned is *null*. **Note**: this method is not supported in sharded collections with more than one shard. **Examples** @startDocuBlockInline documentsCollectionLastFound @EXAMPLE_ARANGOSH_OUTPUT{documentsCollectionLastFound} ~ db._create("example"); ~ db.example.save({ Hello : "world" }); ~ db.example.save({ Foo : "bar" }); db.example.last(2); ~ db._drop("example"); @END_EXAMPLE_ARANGOSH_OUTPUT @endDocuBlock documentsCollectionLastFound @startDocuBlockInline documentsCollectionLastNull @EXAMPLE_ARANGOSH_OUTPUT{documentsCollectionLastNull} ~ db._create("example"); ~ db.example.save({ Hello : "world" }); db.example.last(1); ~ db._drop("example"); @END_EXAMPLE_ARANGOSH_OUTPUT @endDocuBlock documentsCollectionLastNull !SUBSECTION Collection type returns the type of a collection `collection.type()` Returns the type of a collection. Possible values are: - 2: document collection - 3: edge collection !SUBSECTION Get the Version of ArangoDB return the server version string `db._version()` Returns the server version string. Note that this is not the version of the database. **Examples** @startDocuBlockInline dbVersion @EXAMPLE_ARANGOSH_OUTPUT{dbVersion} require("internal").db._version(); @END_EXAMPLE_ARANGOSH_OUTPUT @endDocuBlock dbVersion !SUBSECTION Misc returns all edges connected to a vertex `collection.edges(vertex-id)` Returns all edges connected to the vertex specified by *vertex-id*. returns inbound edges connected to a vertex `collection.inEdges(vertex-id)` Returns inbound edges connected to the vertex specified by *vertex-id*. returns outbound edges connected to a vertex `collection.outEdges(vertex-id)` Returns outbound edges connected to the vertex specified by *vertex-id*. iterates over some elements of a collection `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** @startDocuBlockInline accessViaGeoIndex @EXAMPLE_ARANGOSH_OUTPUT{accessViaGeoIndex} ~db._create("example") |for (i = -90; i <= 90; i += 10) { | for (j = -180; j <= 180; j += 10) { | db.example.save({ name : "Name/" + i + "/" + j, | home : [ i, j ], | work : [ -i, -j ] }); | } |} db.example.ensureIndex({ type: "geo", fields: [ "home" ] }); |items = db.example.getIndexes().map(function(x) { return x.id; }); db.example.index(items[1]); ~ db._drop("example"); @END_EXAMPLE_ARANGOSH_OUTPUT @endDocuBlock accessViaGeoIndex `edge.setProperty(name, value)` Changes or sets the property *name* an *edges* to *value*.