data-modification AQL

Documentation/Books/Users/Aql/Basics.mdpp

@@ -1,5 +1,19 @@
 !CHAPTER Language basics
 
+An AQL query must either produce a result (indicated by usage of the *RETURN*
+keyword) or execute a data-modification operation (indicated by usage
+of one of the keywords *INSERT*, *UPDATE*, *REPLACE* or *REMOVE*).
+
+Data-modification queries are restricted to modifying one collection per query.
+That means a data-modification query cannot modify data in multiple collections
+with a single query. The name of the modified collection must be known to the
+AQL executor at query-compile time and cannot be dynamic at runtime. Using a
+bind parameter to specify the collection name is allowed.
+
+In SQL, the semicolon can be used to indicate the end of a query and to separate
+multiple queries. This is not supported in AQL. Using a semicolon to terminate
+a query string is not allowed in AQL.
+
 !SUBSECTION Whitespace 
 
 Whitespace can be used in the query text to increase its readability.  However,

Documentation/Books/Users/Aql/Invoke.mdpp

@@ -3,13 +3,42 @@
 You can run AQL queries from your application via the HTTP REST API. The full
 API description is available at [Http Interface for AQL Query Cursor](../HttpAqlQueryCursor/README.md). 
 
-You can also run AQL queries from arangosh. To do so, first create an
+You can also run AQL queries from arangosh. To do so, you can use the *_query* method 
+of the *db* object. This will run the specified query in the context of the currently
+selected database and return the query results in a cursor. The results of the cursor
+can be printed using its *toArray* method:
+    
+    arangosh> db._query("FOR my IN mycollection RETURN my._key").toArray();
+
+To pass bind parameters into a query, they can be specified as second argument to the
+*_query* method:
+
+    arangosh> db._query("FOR c IN @@collection FILTER c._key == @key RETURN c._key", { 
+      "@collection": "mycollection", 
+      "key": "test1" 
+    }).toArray();
+
+Data-modifying AQL queries do not return a result, so the *toArray* method will always
+return an empty list. To retrieve statistics for a data-modification query, use the
+*getExtra* method:
+
+    arangosh> db._query("FOR i IN 1..100 INSERT { _key: CONCAT('test', TO_STRING(i)) } INTO mycollection").getExtra();
+    { 
+      "operations" : {
+        "executed" : 100,
+        "ignored" : 0
+      }
+    }
+
+The *_query* method is a shorthand for creating an ArangoStatement object,
+executing it and iterating over the resulting cursor. If more control over the
+result set iteration is needed, it is recommended to first create an
 ArangoStatement object as follows:
 
-    stmt = db._createStatement( { "query": "FOR i IN [ 1, 2 ] RETURN i * 2" } );
+    arangosh> stmt = db._createStatement( { "query": "FOR i IN [ 1, 2 ] RETURN i * 2" } );
     [object ArangoQueryCursor]
 
-To execute the query, use the *execute* method:
+To execute the query, use the *execute* method of the statement:
 
     arangosh> c = stmt.execute();
     [object ArangoQueryCursor]
@@ -57,7 +86,7 @@ or
     2
     4
 
-Please note that bind variables can also be passed into the *_createStatement* method directly,
+Please note that bind parameters can also be passed into the *_createStatement* method directly,
 making it a bit more convenient:
     
     arangosh> stmt = db._createStatement( { 
@@ -67,7 +96,7 @@ making it a bit more convenient:
         "two": 2 
       } 
     } );
-
+    
 Cursors also optionally provide the total number of results. By default, they do not. 
 To make the server return the total number of results, you may set the *count* attribute to 
 *true* when creating a statement:
@@ -96,4 +125,4 @@ Please note that at the moment the server will always create the full result set
 specifying or omitting the *count* attribute currently does not have any impact on query execution.
 This might change in the future. Future versions of ArangoDB might create result sets incrementally 
 on the server-side and might be able to apply optimizations if a result set is not fully fetched by 
-a client.
+a client.

Documentation/Books/Users/Aql/README.mdpp

@@ -1,31 +1,28 @@
 !CHAPTER Introduction 
 
-The ArangoDB query language (AQL) can be used to retrieve data that is stored in
-ArangoDB. The general workflow when executing a query is as follows:
+The ArangoDB query language (AQL) can be used to retrieve and modify data that 
+are stored in ArangoDB. The general workflow when executing a query is as follows:
 
 - A client application ships an AQL query to the ArangoDB server. The query text
   contains everything ArangoDB needs to compile the result set
 - ArangoDB will parse the query, execute it and compile the results. If the
   query is invalid or cannot be executed, the server will return an error that
   the client can process and react to. If the query can be executed
-  successfully, the server will return the query results to the client
+  successfully, the server will return the query results (if any) to the client
 
 AQL is mainly a declarative language, meaning that in a query it is expressed
 what result should be achieved and not how. AQL aims to be human- readable and
 therefore uses keywords from the English language. Another design goal of AQL
 was client independency, meaning that the language and syntax are the same for
 all clients, no matter what programming language the clients might use.  Further
-design goals of AQL were to support complex query patterns, and to support the
-different data models ArangoDB offers.
+design goals of AQL were the support of complex query patterns and the different
+data models ArangoDB offers.
 
 In its purpose, AQL is similar to the Structured Query Language (SQL), but the
-two languages have major syntactic differences. Furthermore, to avoid any
-confusion between the two languages, the keywords in AQL have been chosen to be
-different from the keywords used in SQL.
+two languages have major syntactic differences and keywords. 
 
-AQL currently supports reading data only. That means you can use the language to
-issue read-requests on your database, but modifying data via AQL is currently
-not supported.
+AQL supports reading and modifying data, but doesn't support data-definition
+operations such as creating and dropping databases, collections and indexes.
 
 For some example queries, please refer to the page [AQL Examples](../AqlExamples/README.md).
 

Documentation/Books/Users/AqlExamples/CollectionQueries.mdpp

@@ -86,7 +86,7 @@ relationships between users. The example data for *relations* are as follows:
 Note that all documents created in the two collections will automatically get the
 following server-generated attributes:
 
-* *_id*: An unique id, consisting of collection name and a server-side sequence value
+* *_id*: A unique id, consisting of collection name and a server-side sequence value
 * *_key*: The server sequence value
 * *_rev*: The document's revision id
 
@@ -99,4 +99,4 @@ used in *FILTER* statements may considerably speed up queries. Furthermore, inst
 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
 establishing references / links between documents. These features have been left out here 
-for brevity as well.
+for brevity as well.