mirror of https://gitee.com/bigwinds/arangodb
Finishing touches for database operations for documents.
Mention changes from 2.8 to 3.0 .
This commit is contained in:
Max Neunhoeffer
Simran Brucherseifer
parent
abebe4b281
commit
27a4b2a27a
|
|
@ -4,26 +4,28 @@
|
|||
<!-- arangod/V8Server/v8-vocbase.cpp -->
|
||||
|
||||
|
||||
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:
|
|||
<!-- arangod/V8Server/v8-vocbase.cpp -->
|
||||
|
||||
|
||||
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
|
||||
<!-- arangod/V8Server/v8-vocbase.cpp -->
|
||||
|
||||
|
||||
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
|
||||
<!-- arangod/V8Server/v8-vocbase.cpp -->
|
||||
|
||||
`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
|
||||
<!-- arangod/V8Server/v8-vocbase.cpp -->
|
||||
|
||||
|
||||
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.
|
||||
|
|
|
|||
|
|
@ -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)`
|
||||
|
|
|
|||
Loading…
Reference in New Issue