Hawkin
/
arangodb
mirror of https://gitee.com/bigwinds/arangodb
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Finishing touches for database operations for documents. 

Mention changes from 2.8 to 3.0 .
This commit is contained in:
Max Neunhoeffer 2016-03-17 12:52:28 +01:00 committed by Simran Brucherseifer
parent abebe4b281
commit 27a4b2a27a
2 changed files with 178 additions and 111 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

267
Documentation/Books/Users/DataModeling/Documents/DatabaseMethods.mdpp
View File

@ -4,26 +4,28 @@
<!-- arangod/V8Server/v8-vocbase.cpp --> <!-- arangod/V8Server/v8-vocbase.cpp -->
looks up a document and returns it `db._document(object)`
`db._document(document)`
This method finds a document given its identifier. It returns the document The *_document* method finds a document given an object *object*
if the document exists. An error is thrown if no document with the given containing the *_id* attribute. The method returns
identifier exists, or if the specified *_rev* value does not match the the document if it can be found.
current revision of the document.
**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 inside a Foxx application), an immutable document object will be returned
for performance reasons. It is not possible to change attributes of this 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 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 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 if the *_document* method is called from out of arangosh or from any other
other client. client.
`db._document(document-handle)` `db._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. first argument. No revision can be specified in this case.
**Examples** **Examples**
@ -46,62 +48,87 @@ Returns the document:
<!-- arangod/V8Server/v8-vocbase.cpp --> <!-- arangod/V8Server/v8-vocbase.cpp -->
checks whether a document exists `db._exists(object)`
`db._exists(document)`
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 Instead of returning the found document or an error, this method will
return either *true* or *false*. It can thus be used only return an object with the attributes *_id*, *_key* and *_rev*, or
for easy existence checks. *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 This method will throw an error if used improperly, e.g. when called
exist. with a non-document handle, a non-document, or when a cross-collection
Still this method will throw an error if used improperly, e.g. when called request is performed.
with a non-document handle.
`db._exists(document-handle)` `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 !SUBSECTION Replace
<!-- arangod/V8Server/v8-vocbase.cpp --> <!-- arangod/V8Server/v8-vocbase.cpp -->
replaces a document `db._replace(selector, data)`
`db._replace(document, data)`
The method returns a document with the attributes *_id*, *_rev* and Replaces an existing document described by the *selector*, which must
*_oldRev*. The attribute *_id* contains the document handle of the 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 updated document, the attribute *_rev* contains the document revision of
the updated document, the attribute *_oldRev* contains the revision of the updated document, the attribute *_oldRev* contains the revision of
the old (now replaced) document. the old (now replaced) document.
If there is a conflict, i. e. if the revision of the *document* does not If the selector contains a *_rev* attribute, the method first checks
match the revision in the collection, then an error is thrown. 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 As before, but *options* must be an object that can contain the following
document is overwritten. boolean attributes:
`db._replace(document, data, true, waitForSync)` - *waitForSync*: One can force
synchronization of the document creation operation to disk even in
The optional *waitForSync* parameter can be used to force case that the *waitForSync* flag is been disabled for the entire
synchronization of the document replacement operation to disk even in case collection. Thus, the *waitForSync* option can be used to force
that the *waitForSync* flag had been disabled for the entire collection. synchronization of just specific operations. To use this, set the
Thus, the *waitForSync* parameter can be used to force synchronization *waitForSync* parameter to *true*. If the *waitForSync* parameter
of just specific operations. To use this, set the *waitForSync* parameter is not specified or set to *false*, then the collection's default
to *true*. If the *waitForSync* parameter is not specified or set to *waitForSync* behavior is applied. The *waitForSync* parameter
*false*, then the collection's default *waitForSync* behavior is cannot be used to disable synchronization for collections that have
applied. The *waitForSync* parameter cannot be used to disable a default *waitForSync* value of *true*.
synchronization for collections that have a default *waitForSync* value - *overwrite*: If this flag is set to *true*, a *_rev* attribute in
of *true*. 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)` `db._replace(document-handle, data)`
As before. Instead of document a *document-handle* can be passed as `db._replace(document-handle, data, options)`
first argument.
As before. Instead of *selector* a *document-handle* can be passed as
first argument. No revision precondition is tested.
**Examples** **Examples**
@ -120,53 +147,73 @@ Create and replace a document:
@endDocuBlock documentsDocumentReplace @endDocuBlock documentsDocumentReplace
!SUBSUBSECTION Changes in 3.0 from 2.8:
The options *silent*, *returnNew* and *returnOld* are new.
!SUBSECTION Update !SUBSECTION Update
<!-- arangod/V8Server/v8-vocbase.cpp --> <!-- arangod/V8Server/v8-vocbase.cpp -->
`db._update(selector, data)`
update a document Updates an existing document described by the *selector*, which must
`db._update(document, data, overwrite, keepNull, waitForSync)` 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 method returns a document with the attributes *_id*, *_key*, *_rev*
the current collection. This document is then patched with the and *_oldRev*. The attribute *_id* contains the document handle of 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 updated document, the attribute *_rev* contains the document revision of
the updated document, the attribute *_oldRev* contains the 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 If the selector contains a *_rev* attribute, the method first checks
match the revision in the collection, then an error is thrown. 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)` `db._update(document-handle, data)`
As before. Instead of document a *document-handle* can be passed as `db._update(document-handle, data, options)`
first argument.
As before. Instead of *selector* a *document-handle* can be passed as
first argument. No revision precondition is tested.
**Examples** **Examples**
@ -185,42 +232,59 @@ Create and update a document:
@endDocuBlock documentDocumentUpdate @endDocuBlock documentDocumentUpdate
!SUBSUBSECTION Changes in 3.0 from 2.8:
The options *silent*, *returnNew* and *returnOld* are new.
!SUBSECTION Remove !SUBSECTION Remove
<!-- arangod/V8Server/v8-vocbase.cpp --> <!-- arangod/V8Server/v8-vocbase.cpp -->
removes a document `db._remove(selector)`
`db._remove(document)`
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 If the selector contains a *_rev* attribute, the method first checks
and document is deleted. The function returns *true* if the document that the specified revision is the current revision of that document.
existed and was deleted. It returns *false*, if the document was already If not, there is a conflict, and an error is thrown.
deleted.
`db._remove(document, true, waitForSync)` or `db._remove(selector, options)`
`db._remove(document, {overwrite: true or false, waitForSync: true or false})`
The optional *waitForSync* parameter can be used to force synchronization As before, but *options* must be an object that can contain the following
of the document deletion operation to disk even in case that the boolean attributes:
*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*.
`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 `db._remove(document-handle)`
argument.
`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** **Examples**
@ -264,4 +328,7 @@ Remove a document using new signature:
@END_EXAMPLE_ARANGOSH_OUTPUT @END_EXAMPLE_ARANGOSH_OUTPUT
@endDocuBlock documentsCollectionRemoveSignature @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.

22
Documentation/Books/Users/DataModeling/Documents/DocumentMethods.mdpp
View File

@ -315,7 +315,7 @@ in a production environment.
`collection.document(object)` `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 containing the *_id* or *_key* attribute. The method returns
the document if it can be found. If both attributes are given, the document if it can be found. If both attributes are given,
the *_id* takes precedence, it is an error, if the collection part the *_id* takes precedence, it is an error, if the collection part
@ -335,12 +335,12 @@ client.
`collection.document(document-handle)` `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. first argument. No revision can be specified in this case.
`collection.document(document-key)` `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. first argument.
`collection.document(array)` `collection.document(array)`
@ -450,12 +450,12 @@ request is performed.
`collection.exists(document-handle)` `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. first argument.
`collection.exists(document-key)` `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. first argument.
`collection.exists(array)` `collection.exists(array)`
@ -637,14 +637,14 @@ boolean attributes:
`collection.replace(document-handle, data, options)` `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. first argument. No revision precondition is tested.
`collection.replace(document-key, data)` `collection.replace(document-key, data)`
`collection.replace(document-key, data, options)` `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. first argument. No revision precondition is tested.
`collection.replace(selectorarray, dataarray)` `collection.replace(selectorarray, dataarray)`
@ -753,14 +753,14 @@ boolean attributes:
`collection.update(document-handle, data, options)` `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. first argument. No revision precondition is tested.
`collection.update(document-key, data)` `collection.update(document-key, data)`
`collection.update(document-key, data, options)` `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. first argument. No revision precondition is tested.
`collection.update(selectorarray, dataarray)` `collection.update(selectorarray, dataarray)`
@ -895,14 +895,14 @@ boolean attributes:
`collection.remove(document-handle, options)` `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. first argument. No revision check is performed.
`collection.remove(document-key)` `collection.remove(document-key)`
`collection.remove(document-handle, options)` `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. first argument. No revision check is performed.
`collection.remove(selectorarray)` `collection.remove(selectorarray)`