From abebe4b281ad3fefc8fa919a0814fd4a841cc52d Mon Sep 17 00:00:00 2001 From: Max Neunhoeffer Date: Thu, 17 Mar 2016 11:29:29 +0100 Subject: [PATCH] Finishing touches for document API in JS, collection methods. Add changes from 3.0 to 2.8. --- .../Documents/DocumentAddress.mdpp | 2 +- .../Documents/DocumentMethods.mdpp | 82 ++++++++++--------- .../Users/DataModeling/Documents/README.mdpp | 7 +- 3 files changed, 49 insertions(+), 42 deletions(-) diff --git a/Documentation/Books/Users/DataModeling/Documents/DocumentAddress.mdpp b/Documentation/Books/Users/DataModeling/Documents/DocumentAddress.mdpp index 19af1369a1..0f2edbe236 100644 --- a/Documentation/Books/Users/DataModeling/Documents/DocumentAddress.mdpp +++ b/Documentation/Books/Users/DataModeling/Documents/DocumentAddress.mdpp @@ -109,7 +109,7 @@ in a single command is to use JSON arrays of objects in the place of a single document. As a consequence, document keys, handles and revisions for preconditions have to be supplied embedded in the individual documents given. Multiple document operations are restricted to a single document -or edge collections. +or edge collection. See the [API descriptions for collection objects](DocumentMethods.md) for details. Note that the [API for database objects](DatabaseMethods.md) do not offer these operations. diff --git a/Documentation/Books/Users/DataModeling/Documents/DocumentMethods.mdpp b/Documentation/Books/Users/DataModeling/Documents/DocumentMethods.mdpp index 9ec91d84bf..d6ace93c37 100644 --- a/Documentation/Books/Users/DataModeling/Documents/DocumentMethods.mdpp +++ b/Documentation/Books/Users/DataModeling/Documents/DocumentMethods.mdpp @@ -4,7 +4,6 @@ -constructs an all query for a collection `collection.all()` Fetches all documents from a collection and returns a cursor. You can use @@ -51,7 +50,6 @@ Use *limit* to restrict the documents: -constructs a query-by-example for a collection `collection.byExample(example)` Fetches all documents from a collection that match the specified @@ -147,7 +145,6 @@ Use *next* to loop over all documents: -constructs a query-by-example for a collection `collection.firstExample(example)` Returns some document of a collection that matches the specified @@ -180,7 +177,6 @@ As alternative you can supply an array of paths and values. -constructs a range query for a collection `collection.range(attribute, left, right)` Returns all documents from a collection such that the *attribute* is @@ -231,7 +227,6 @@ Use *toArray* to get all documents at once: -constructs a closed range query for a collection `collection.closedRange(attribute, left, right)` Returns all documents of a collection such that the *attribute* is @@ -277,7 +272,6 @@ Use *toArray* to get all documents at once: -returns any document from a collection `collection.any()` Returns a random document from the collection or *null* if none exists. @@ -287,7 +281,6 @@ Returns a random document from the collection or *null* if none exists. -counts the number of documents in a result set `collection.count()` Returns the number of living documents in the collection. @@ -310,7 +303,6 @@ Returns the number of living documents in the collection. -converts collection into an array `collection.toArray()` Converts the collection into an array of documents. Never use this call @@ -321,7 +313,6 @@ in a production environment. -looks up a document `collection.document(object)` The *document* method finds a document given an object `object` @@ -428,6 +419,9 @@ An error is raised if the handle is invalid: @END_EXAMPLE_ARANGOSH_OUTPUT @endDocuBlock documentsCollectionNameHandle +!SUBSUBSECTION Changes in 3.0 from 2.8: + +*document* can now query multiple documents with one call. !SUBSECTION Exists @@ -472,19 +466,26 @@ members of the array and all results are returned in an array. If an error occurs with any of the documents, the operation stops immediately returning only an error object. +!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. + +*exists* can now query multiple documents with one call. + !SUBSECTION Lookup By Keys -fetches multiple documents by their keys `collection.documents(keys)` -Looks up the documents in the specified collection using the array of keys -provided. All documents for which a matching key was specified in the *keys* -array and that exist in the collection will be returned. -Keys for which no document can be found in the underlying collection are ignored, -and no exception will be thrown for them. +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. This method is deprecated in favour of the array variant of *document*. @@ -510,7 +511,6 @@ This method is deprecated in favour of the array variant of *document*. -insert a new document `collection.insert(data)` Creates a new document in the *collection* from the given *data*. The @@ -558,6 +558,11 @@ array. If an error occurs with any of the documents, the operation stops immediately returning only an error object. The options behave exactly as before. +!SUBSUBSECTION Changes in 3.0 from 2.8: + +The options *silent* and *returnNew* are new. The method can now insert +multiple documents with one call. + **Examples** @@ -586,7 +591,6 @@ as before. -replaces a document `collection.replace(selector, data)` Replaces an existing document described by the *selector*, which must @@ -683,12 +687,15 @@ Use a document handle: @END_EXAMPLE_ARANGOSH_OUTPUT @endDocuBlock documentsCollectionReplaceHandle +!SUBSUBSECTION Changes in 3.0 from 2.8: + +The options *silent*, *returnNew* and *returnOld* are new. The method +can now replace multiple documents with one call. !SUBSECTION Update -updates a document `collection.update(selector, data)` Updates an existing document described by the *selector*, which must @@ -837,12 +844,15 @@ Patching array values: @endDocuBlock documentsCollection_UpdateHandleArray +!SUBSUBSECTION Changes in 3.0 from 2.8: + +The options *silent*, *returnNew* and *returnOld* are new. The method +can now update multiple documents with one call. + !SUBSECTION Remove -removes a document - `collection.remove(selector)` Removes a document described by the *selector*, which must be an object @@ -879,6 +889,7 @@ boolean attributes: - *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. `collection.remove(document-handle)` @@ -935,13 +946,18 @@ Remove a document with a conflict: @END_EXAMPLE_ARANGOSH_OUTPUT @endDocuBlock documentDocumentRemoveConflict +!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. The method +can now remove multiple documents with one call. + !SUBSECTION Remove By Keys -removes multiple documents by their keys `collection.removeByKeys(keys)` @@ -979,7 +995,6 @@ This method is deprecated in favour of the array variant of *remove*. -removes documents matching an example `collection.removeByExample(example)` Removes all documents matching an example. @@ -1022,7 +1037,6 @@ removed. -replaces documents matching an example `collection.replaceByExample(example, newValue)` Replaces all documents matching an example with a new document body. @@ -1068,7 +1082,6 @@ replaced. -partially updates documents matching an example `collection.updateByExample(example, newValue)` Partially updates all documents matching an example with a new document body. @@ -1109,10 +1122,11 @@ updated. Using this variant, the options for the operation can be passed using an object with the following sub-attributes: -- *keepNull* -- *waitForSync* -- *limit* -- *mergeObjects* + + - *keepNull* + - *waitForSync* + - *limit* + - *mergeObjects* **Examples** @@ -1132,7 +1146,6 @@ an object with the following sub-attributes: !SUBSECTION Collection type -returns the type of a collection `collection.type()` Returns the type of a collection. Possible values are: @@ -1143,7 +1156,6 @@ Returns the type of a collection. Possible values are: !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 @@ -1163,28 +1175,24 @@ database. !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 @@ -1194,10 +1202,10 @@ as second argument. *options* must be an object with the following attributes: -- *limit* (optional, default none): use at most *limit* documents. + - *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. + - *probability* (optional, default all): a number between *0* and + *1*. Documents are chosen with this probability. **Examples** diff --git a/Documentation/Books/Users/DataModeling/Documents/README.mdpp b/Documentation/Books/Users/DataModeling/Documents/README.mdpp index 380d79eae5..12eecbd808 100644 --- a/Documentation/Books/Users/DataModeling/Documents/README.mdpp +++ b/Documentation/Books/Users/DataModeling/Documents/README.mdpp @@ -1,9 +1,8 @@ !CHAPTER Documents -This is an introduction to ArangoDB's interface for documents to and how -handle documents from the JavaScript shell *arangosh* or with JavaScript -code in the server. For other languages see the corresponding language -API. +This is an introduction to ArangoDB's interface for working with +documents from the JavaScript shell *arangosh* or in JavaScript code in +the server. For other languages see the corresponding language API. We begin with a