From 9e1abb4b99beff29564e6dcd25cac363b28e9754 Mon Sep 17 00:00:00 2001 From: Jan Steemann Date: Sun, 6 Jul 2014 02:13:05 +0200 Subject: [PATCH] added examples --- .../Users/AqlExamples/CollectionQueries.mdpp | 2 +- .../AqlExamples/DataModificationQueries.mdpp | 130 ++++++++++++++++++ Documentation/Books/Users/SUMMARY.md | 1 + 3 files changed, 132 insertions(+), 1 deletion(-) create mode 100644 Documentation/Books/Users/AqlExamples/DataModificationQueries.mdpp diff --git a/Documentation/Books/Users/AqlExamples/CollectionQueries.mdpp b/Documentation/Books/Users/AqlExamples/CollectionQueries.mdpp index 73c6dc463e..942911a87f 100644 --- a/Documentation/Books/Users/AqlExamples/CollectionQueries.mdpp +++ b/Documentation/Books/Users/AqlExamples/CollectionQueries.mdpp @@ -97,6 +97,6 @@ Please also note that with real-world data, you might want to create additional indexes on the data (left out here for brevity). Adding indexes on attributes that are used in *FILTER* statements may considerably speed up queries. Furthermore, instead of using attributes such as *id*, *from* and *to*, you might want to use the built-in -*_id*, *_from* and *to* attributes. Finally, edge collections provide a nice way of +*_id*, *_from* and *_to* attributes. Finally, edge collections provide a nice way of establishing references / links between documents. These features have been left out here for brevity as well. diff --git a/Documentation/Books/Users/AqlExamples/DataModificationQueries.mdpp b/Documentation/Books/Users/AqlExamples/DataModificationQueries.mdpp new file mode 100644 index 0000000000..84aee2ea2d --- /dev/null +++ b/Documentation/Books/Users/AqlExamples/DataModificationQueries.mdpp @@ -0,0 +1,130 @@ +!CHAPTER Data-modification queries + +The following operations can be used to modify data of multiple documents +with one query. This is superior to fetching and updating the documents individually +with multiple queries. However, if only a single document needs to be modified, +ArangoDB's specialized data-modification operations for single documents +might execute faster. + +!SUBSECTION Updating documents + +To update existing documents, we can either use the *UPDATE* or the *REPLACE* +operation. *UPDATE* updates only the specified attributes in the found documents, +and *REPLACE* completely replaces the found documents with the specified values. + +We'll start with an *UPDATE* query that rewrites the gender attribute in all +documents: + +```js +FOR u IN users + UPDATE u WITH { gender: TRANSLATE(u.gender, { m: 'male', f: 'female' }) } IN users +``` + +To add new attributes to existing documents, we can also use an *UPDATE* query. +The following query adds an attribute *numberOfLogins* for all users with status +active: + +```js +FOR u IN users + FILTER u.active == true + UPDATE u WITH { numberOfLogins: 0 } IN users +``` + +Existing attributes can also be updated based on their previous value: + +```js +FOR u IN users + FILTER u.active == true + UPDATE u WITH { numberOfLogins: u.numberOfLogins + 1 } IN users +``` + +The above query will only work if there was already a *numberOfLogins* attribute +present in the document. If it is unsure whether there is a *numberOfLogins* +attribute in the document, the increase must be made conditional: + +```js +FOR u IN users + FILTER u.active == true + UPDATE u WITH { + numberOfLogins: HAS(u, 'numberOfLogins') ? u.numberOfLogins + 1 : 1 + } IN users +``` + +Updates of multiple attributes can be combined in a single query: + +```js +FOR u IN users + FILTER u.active == true + UPDATE u WITH { + lastLogin: DATE_NOW(), + numberOfLogins: HAS(u, 'numberOfLogins') ? u.numberOfLogins + 1 : 1 + } IN users +``` + +To completely replace existing documents, use the *REPLACE* operation. +The following query replaces all documents in collection backup with the documents +found in collection users. Only those documents will be replaced that are present +in both collections. Documents are compared using their *_key* attributes: + +```js +FOR u IN users + REPLACE u IN backup +``` + +The above query will fail if there are documents in collection users that are +not in collection backup yet. In this case, the query would attempt to replace +documents that do not exist. To make the query succeed for such case, use the +*ignoreErrors* query option: + +```js +FOR u IN users + REPLACE u IN backup OPTIONS { ignoreErrors: true } +``` + +!SUBSECTION Removing documents + +Removing documents can be achieved with the *REMOVE* operation. +To remove all users within a certain age range, we can use the following query: + +```js +FOR u IN users + FILTER u.active == true && u.age >= 35 && u.age <= 37 + REMOVE u IN users +``` + +!SUBSECTION Creating documents + +To create new documents, there is the *INSERT* operation. +It can also be used to generate copies of existing documents from other collections, +or to create synthetic documents (e.g. for testing purposes). The following +query creates 1000 test users in collection users with some attributes set: + +```js +FOR i IN 1..1000 + INSERT { + id: 100000 + i, + age: 18 + FLOOR(RAND() * 25), + name: CONCAT('test', TO_STRING(i)), + active: false, + gender: i % 2 == 0 ? 'male' : 'female' + } IN users +``` + +!SUBSECTION Copying data from one collection into another + +To copy data from one collection into another, an *INSERT* operation can be +used: + +```js +FOR u IN users + INSERT u IN backup +``` + +This will copy over all documents from collection users into collection +backup. Note that both collections must already exist when the query is +executed. The query might fail if backup already contains documents, as +executing the insert might attempt to insert the same document again. This +will trigger a unique key constraint violation. +To make such copy operation work in all cases, the target collection can +be emptied before using a *REMOVE* query. + diff --git a/Documentation/Books/Users/SUMMARY.md b/Documentation/Books/Users/SUMMARY.md index 2fbd29e522..3ee37ae9c9 100644 --- a/Documentation/Books/Users/SUMMARY.md +++ b/Documentation/Books/Users/SUMMARY.md @@ -63,6 +63,7 @@ * [Registering Functions](AqlExtending/Functions.md) * [AQL Examples](AqlExamples/README.md) * [Collection based queries](AqlExamples/CollectionQueries.md) + * [Data-modification queries](AqlExamples/DataModificationQueries.md) * [Projections and filters](AqlExamples/ProjectionsAndFilters.md) * [Joins](AqlExamples/Join.md) * [Grouping](AqlExamples/Grouping.md)