mirror of https://gitee.com/bigwinds/arangodb
1103 lines
36 KiB
Plaintext
1103 lines
36 KiB
Plaintext
!CHAPTER Collection Methods
|
|
|
|
!SUBSECTION All
|
|
<!-- js/common/modules/@arangodb/arango-collection-common.js-->
|
|
|
|
|
|
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
|
|
<!-- js/common/modules/@arangodb/arango-collection-common.js-->
|
|
|
|
|
|
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
|
|
<!-- js/server/modules/@arangodb/arango-collection.js-->
|
|
|
|
|
|
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
|
|
<!-- js/common/modules/@arangodb/arango-collection-common.js-->
|
|
|
|
|
|
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
|
|
<!-- js/common/modules/@arangodb/arango-collection-common.js-->
|
|
|
|
|
|
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
|
|
<!-- js/server/modules/@arangodb/arango-collection.js-->
|
|
|
|
|
|
returns any document from a collection
|
|
`collection.any()`
|
|
|
|
Returns a random document from the collection or *null* if none exists.
|
|
|
|
|
|
!SUBSECTION Count
|
|
<!-- arangod/V8Server/v8-vocbase.cpp -->
|
|
|
|
|
|
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
|
|
<!-- js/server/modules/@arangodb/arango-collection.js-->
|
|
|
|
|
|
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
|
|
<!-- arangod/V8Server/v8-vocbase.cpp -->
|
|
|
|
|
|
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 documentsCollectionName
|
|
@EXAMPLE_ARANGOSH_OUTPUT{documentsCollectionName}
|
|
~ db._create("example");
|
|
~ var myid = db.example.insert({_key: "2873916"});
|
|
db.example.document("example/2873916");
|
|
~ db._drop("example");
|
|
@END_EXAMPLE_ARANGOSH_OUTPUT
|
|
@endDocuBlock documentsCollectionName
|
|
|
|
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
|
|
<!-- arangod/V8Server/v8-vocbase.cpp -->
|
|
|
|
|
|
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
|
|
<!-- arangod/V8Server/v8-query.cpp-->
|
|
|
|
|
|
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
|
|
<!-- arangod/V8Server/v8-vocbase.cpp -->
|
|
|
|
|
|
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
|
|
<!-- arangod/V8Server/v8-vocbase.cpp -->
|
|
|
|
|
|
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 documentsCollectionReplace
|
|
@EXAMPLE_ARANGOSH_OUTPUT{documentsCollectionReplace}
|
|
~ 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 documentsCollectionReplace
|
|
|
|
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
|
|
<!-- arangod/V8Server/v8-vocbase.cpp -->
|
|
|
|
|
|
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 documentsCollectionUpdate
|
|
@EXAMPLE_ARANGOSH_OUTPUT{documentsCollectionUpdate}
|
|
~ 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 documentsCollectionUpdate
|
|
|
|
Use a document handle:
|
|
|
|
@startDocuBlockInline documentsCollectionUpdateHandle
|
|
@EXAMPLE_ARANGOSH_OUTPUT{documentsCollectionUpdateHandle}
|
|
~ 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 documentsCollectionUpdateHandle
|
|
|
|
Use the keepNull parameter to remove attributes with null values:
|
|
|
|
@startDocuBlockInline documentsCollectionUpdateHandleKeepNull
|
|
@EXAMPLE_ARANGOSH_OUTPUT{documentsCollectionUpdateHandleKeepNull}
|
|
~ 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 documentsCollectionUpdateHandleKeepNull
|
|
|
|
Patching array values:
|
|
|
|
@startDocuBlockInline documentsCollectionUpdateHandleArray
|
|
@EXAMPLE_ARANGOSH_OUTPUT{documentsCollectionUpdateHandleArray}
|
|
~ 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 documentsCollectionUpdateHandleArray
|
|
|
|
|
|
|
|
!SUBSECTION Remove
|
|
<!-- arangod/V8Server/v8-vocbase.cpp -->
|
|
|
|
|
|
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 documentDocumentRemove
|
|
@EXAMPLE_ARANGOSH_OUTPUT{documentDocumentRemove}
|
|
~ 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 documentDocumentRemove
|
|
|
|
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
|
|
<!-- arangod/V8Server/v8-query.cpp-->
|
|
|
|
|
|
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
|
|
<!-- js/common/modules/@arangodb/arango-collection-common.js-->
|
|
|
|
|
|
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
|
|
<!-- js/common/modules/@arangodb/arango-collection-common.js-->
|
|
|
|
|
|
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 such as *_id*,
|
|
*_key*, *_from*, *_to* 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
|
|
<!-- js/common/modules/@arangodb/arango-collection-common.js-->
|
|
|
|
|
|
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 such as *_id*, *_key*, *_from*,
|
|
*_to* 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
|
|
<!-- js/server/modules/@arangodb/arango-collection.js-->
|
|
|
|
|
|
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 documentsCollectionFirst
|
|
@EXAMPLE_ARANGOSH_OUTPUT{documentsCollectionFirst}
|
|
~ 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 documentsCollectionFirst
|
|
|
|
@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
|
|
<!-- js/server/modules/@arangodb/arango-collection.js-->
|
|
|
|
|
|
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 documentsCollectionLast
|
|
@EXAMPLE_ARANGOSH_OUTPUT{documentsCollectionLast}
|
|
~ 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 documentsCollectionLast
|
|
|
|
@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*.
|
|
|
|
|