issue #1005: updated documentation

Documentation/Books/Users/Aql/DataModification.mdpp

@@ -12,44 +12,55 @@ Data-modification operations are normally combined with *FOR* loops to
 iterate over a given list of documents. They can optionally be combined with
 *FILTER* statements and the like.
 
+Let's start with an example that modifies existing documents in a collection
+"users" that match some condition:
+
     FOR u IN users
       FILTER u.status == 'not active'
       UPDATE u WITH { status: 'inactive' } IN users
 
-Though there is no need to combine a data-modification query with other
+Note there is no need to combine a data-modification query with other
 AQL operations such as *FOR* and *FILTER*. For example, the following 
 stripped-down *update* query will work, too. It will *update* one document
 (with key *foo*) in collection *users*:
 
     UPDATE "foo" WITH { status: 'inactive' } IN users
 
-Data-modification queries are restricted to modifying data in a single 
-collection per query. That means a data-modification query cannot modify 
-data in multiple collections with a single query, though it is possible
-to read from one collection and modify data in another with one query.
-
-For example, to copy the contents of the collection "users" into the collection
+Now, let's copy the contents of the collection "users" into the collection
 "backup":
 
     FOR u IN users
       INSERT u IN backup
 
-To remove documents in the collection "backup" that have the same key as some
-matching documents in collection "users":
+As a final example, let's find some documents in collection "users" and
+remove them from collection "backup". The link between the documents in both
+collections is establish via the documents' keys:
 
     FOR u IN users
-      FILTER u.status == 'inactive'
+      FILTER u.status == 'deleted'
       REMOVE u._key IN backup
 
-The name of the modified collection ("backup" in the above cases) must be 
-known to the AQL executor at query-compile time and cannot change at 
+
+!SUBSECTION Restrictions
+
+The name of the modified collection ("users" and "backup" in the above cases) 
+must be known to the AQL executor at query-compile time and cannot change at 
 runtime. Using a bind parameter to specify the [collection name](../Glossary/README.html#collection_name) is allowed.
+
+Data-modification queries are restricted to modifying data in a single 
+collection per query. That means a data-modification query cannot modify 
+data in multiple collections with a single query. It is still possible (and
+was shown above) to read from one or many collections and modify data in another
+with one query.
+
+
+!SUBSECTION Transactional Execution
   
 On a single server, data-modification operations are executed transactionally.
-If a data-modification operation fails, it will be rolled back automatically
-as if it never happened.
+If a data-modification operation fails, any changes made by it will be rolled 
+back automatically as if they never happened.
 
-In a cluster, AQL data-modification queries are not executed transactionally.
+In a cluster, AQL data-modification queries are currently not executed transactionally.
 Additionally, *update*, *replace* and *remove* AQL queries currently require the 
 *_key* attribute to be specified for all documents that should be modified or 
 removed, even if a shared key attribute other than *_key* was chosen for the

Documentation/Books/Users/AqlExamples/DataModificationQueries.mdpp

@@ -6,7 +6,7 @@ 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
+###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,
@@ -61,7 +61,16 @@ FOR u IN users
   } IN users
 ``` 
 
-To completely replace existing documents, use the *REPLACE* operation.
+Note than an update query might fail during execution, for example because a 
+document to be updated does not exist. In this case, the query will abort at
+the first error. In single-server mode, all modifications done by the query will
+be rolled back as if they never happened.
+
+
+###Replacing documents
+
+To not just partially update, but completely replace existing documents, use 
+the *REPLACE* operation.
 The following query replaces all documents in the collection backup with
 the documents found in collection users. Documents common to both
 collections will be replaced. All other documents will remain unchanged.
@@ -74,15 +83,20 @@ FOR u IN users
 
 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:
+documents that do not exist. If such case is detected while executing the query,
+the query will abort. In single-server mode, all changes made by the query will
+also be rolled back.
+
+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
+
 Deleting documents can be achieved with the *REMOVE* operation.
 To remove all users within a certain age range, we can use the following query:
 
@@ -92,7 +106,8 @@ FOR u IN users
   REMOVE u IN users
 ``` 
 
-!SUBSECTION Creating documents
+
+###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,
@@ -110,7 +125,8 @@ FOR i IN 1..1000
   } IN users
 ``` 
 
-!SUBSECTION Copying data from one collection into another
+
+###Copying data from one collection into another
 
 To copy data from one collection into another, an *INSERT* operation can be
 used:
@@ -123,8 +139,27 @@ FOR u IN users
 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.
+executing the insert might attempt to insert the same document (identified
+by *_key* attribute) again. This will trigger a unique key constraint violation
+and abort the query. In single-server mode, all changes made by the query
+will also be rolled back.
 To make such copy operation work in all cases, the target collection can
-be emptied before using a *REMOVE* query.
+be emptied before, using a *REMOVE* query.
 
+
+###Handling errors
+
+In some cases it might be desirable to continue execution of a query even in 
+the face of errors (e.g. "document not found"). To continue execution of a
+query in case of errors, there is the *ignoreErrors* option.
+
+To use it, place an *OPTIONS* keyword directly after the data modification
+part of the query, e.g.
+
+```js
+FOR u IN users
+  REPLACE u IN backup OPTIONS { ignoreErrors: true } 
+```
+
+This will continue execution of the query even if errors occur during the
+*REPLACE* operation. It works similar for *UPDATE*, *INSERT*, and *REMOVE*.