diff --git a/Documentation/Books/Users/DataModeling/Documents/DatabaseMethods.mdpp b/Documentation/Books/Users/DataModeling/Documents/DatabaseMethods.mdpp index a5a8c7e44e..61f0790c58 100644 --- a/Documentation/Books/Users/DataModeling/Documents/DatabaseMethods.mdpp +++ b/Documentation/Books/Users/DataModeling/Documents/DatabaseMethods.mdpp @@ -4,26 +4,28 @@ -looks up a document and returns it -`db._document(document)` +`db._document(object)` -This method finds a document given its identifier. It returns the document -if the document exists. An error is thrown if no document with the given -identifier exists, or if the specified *_rev* value does not match the -current revision of the document. +The *_document* method finds a document given an object *object* +containing the *_id* attribute. The method returns +the document if it can be found. -**Note**: If the method is executed on the arangod server (e.g. from +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*. + +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 the *_document* method is called from out of arangosh or from any other +client. `db._document(document-handle)` -As before. Instead of document a *document-handle* can be passed as -first argument. +As before. Instead of *object* a *document-handle* can be passed as +first argument. No revision can be specified in this case. **Examples** @@ -46,62 +48,87 @@ Returns the document: -checks whether a document exists -`db._exists(document)` +`db._exists(object)` + +The *_exists* method determines whether a document exists given an object +`object` containing the *_id* attribute. + +An error is thrown if *_rev* is specified but the document found has a +different revision already. -This 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. +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. -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. +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. `db._exists(document-handle)` -As before, but instead of a document a document-handle can be passed. +As before. Instead of *object* a *document-handle* can be passed as +first argument. + +!SUBSUBSECTION 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. !SUBSECTION Replace -replaces a document -`db._replace(document, data)` +`db._replace(selector, data)` -The method returns a document with the attributes *_id*, *_rev* and -*_oldRev*. The attribute *_id* contains the document handle of the +Replaces an existing document described by the *selector*, which must +be an object containing the *_id* attribute. There must be +a document with that *_id* in the current database. 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 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. +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. -`db._replace(document, data, true)` +`collection.replace(selector, data, options)` -As before, but in case of a conflict, the conflict is ignored and the old -document is overwritten. +As before, but *options* must be an object that can contain the following +boolean attributes: -`db._replace(document, data, true, 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*. + - *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. `db._replace(document-handle, data)` -As before. Instead of document a *document-handle* can be passed as -first argument. +`db._replace(document-handle, data, options)` + +As before. Instead of *selector* a *document-handle* can be passed as +first argument. No revision precondition is tested. **Examples** @@ -120,53 +147,73 @@ Create and replace a document: @endDocuBlock documentsDocumentReplace +!SUBSUBSECTION Changes in 3.0 from 2.8: + +The options *silent*, *returnNew* and *returnOld* are new. + !SUBSECTION Update +`db._update(selector, data)` -update a document -`db._update(document, data, overwrite, keepNull, waitForSync)` +Updates an existing document described by the *selector*, which must +be an object containing the *_id* attribute. There must be +a document with that *_id* in the current database. This +document is then patched with the *data* given as second argument. +Any attribute *_id*, *_key* or *_rev* in *data* is ignored. -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 +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. +the old (now updated) 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. +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. -`db._update(document, data, true)` +`db._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*. -As before, but in case of a conflict, the conflict is ignored and the old -document is overwritten. `db._update(document-handle, data)` -As before. Instead of document a *document-handle* can be passed as -first argument. +`db._update(document-handle, data, options)` + +As before. Instead of *selector* a *document-handle* can be passed as +first argument. No revision precondition is tested. **Examples** @@ -185,42 +232,59 @@ Create and update a document: @endDocuBlock documentDocumentUpdate +!SUBSUBSECTION Changes in 3.0 from 2.8: + +The options *silent*, *returnNew* and *returnOld* are new. + !SUBSECTION Remove -removes a document -`db._remove(document)` +`db._remove(selector)` -Removes a document. If there is revision mismatch, then an error is thrown. +Removes a document described by the *selector*, which must be an object +containing the *_id* attribute. There must be a document with +that *_id* in the current database. This document is then +removed. -`db._remove(document, true)` +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 eocument. -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. +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. -`db._remove(document, true, waitForSync)` or -`db._remove(document, {overwrite: true or false, waitForSync: true or false})` +`db._remove(selector, options)` -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*. +As before, but *options* must be an object that can contain the following +boolean attributes: -`db._remove(document-handle, data)` + - *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. -As before. Instead of document a *document-handle* can be passed as first -argument. +`db._remove(document-handle)` +`db._remove(document-handle, options)` + +As before. Instead of *selector* a *document-handle* can be passed as +first argument. No revision check is performed. **Examples** @@ -264,4 +328,7 @@ Remove a document using new signature: @END_EXAMPLE_ARANGOSH_OUTPUT @endDocuBlock documentsCollectionRemoveSignature +!SUBSUBSECTION 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. diff --git a/Documentation/Books/Users/DataModeling/Documents/DocumentMethods.mdpp b/Documentation/Books/Users/DataModeling/Documents/DocumentMethods.mdpp index d6ace93c37..034f76983d 100644 --- a/Documentation/Books/Users/DataModeling/Documents/DocumentMethods.mdpp +++ b/Documentation/Books/Users/DataModeling/Documents/DocumentMethods.mdpp @@ -315,7 +315,7 @@ in a production environment. `collection.document(object)` -The *document* method finds a document given an object `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 @@ -335,12 +335,12 @@ client. `collection.document(document-handle)` -As before. Instead of document a *document-handle* can be passed as +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 document a *document-key* can be passed as +As before. Instead of *object* a *document-key* can be passed as first argument. `collection.document(array)` @@ -450,12 +450,12 @@ request is performed. `collection.exists(document-handle)` -As before. Instead of document a *document-handle* can be passed as +As before. Instead of *object* a *document-handle* can be passed as first argument. `collection.exists(document-key)` -As before. Instead of document a *document-key* can be passed as +As before. Instead of *object* a *document-key* can be passed as first argument. `collection.exists(array)` @@ -637,14 +637,14 @@ boolean attributes: `collection.replace(document-handle, data, options)` -As before. Instead of a selector a *document-handle* can be passed as +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 a selector a *document-key* can be passed as +As before. Instead of *selector* a *document-key* can be passed as first argument. No revision precondition is tested. `collection.replace(selectorarray, dataarray)` @@ -753,14 +753,14 @@ boolean attributes: `collection.update(document-handle, data, options)` -As before. Instead of a selector a *document-handle* can be passed as +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 a selector a *document-key* can be passed as +As before. Instead of *selector* a *document-key* can be passed as first argument. No revision precondition is tested. `collection.update(selectorarray, dataarray)` @@ -895,14 +895,14 @@ boolean attributes: `collection.remove(document-handle, options)` -As before. Instead of document a *document-handle* can be passed as +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 document a *document-handle* can be passed as +As before. Instead of *selector* a *document-handle* can be passed as first argument. No revision check is performed. `collection.remove(selectorarray)`