Fix #1573

Documentation/Books/Users/Foxx/Develop/Queries.mdpp

@@ -2,11 +2,46 @@
 
 This chapter describes helpers for performing AQL queries in Foxx. For a full overview of AQL syntax and semantics see the chapter on the ArangoDB Query Language (AQL).
 
+!SECTION Raw AQL Queries
+
+The most straightforward way to perform AQL queries is using the `db._query` API. You can learn more about this API in the [chapter on invoking AQL queries](../../Aql/Invoke.md).
+
+**Examples**
+```js
+var db = require('org/arangodb').db;
+var console = require('console');
+
+var result = db._query('RETURN 42').toArray();
+console.log(result);
+```
+
+!SECTION AQL Template Strings
+
+ArangoDB supports ES2015-style template strings for queries using the `aqlQuery` template helper.
+
+**Examples**
+
+```js
+var db = require('org/arangodb').db;
+var console = require('console');
+
+var isAdmin = true;
+var userCollection = applicationContext.collection('users');
+
+var usernames = db._query(aqlQuery`
+    FOR user IN ${userCollection}
+    FILTER user.isAdmin == ${isAdmin}
+    RETURN user
+`).toArray();
+
+console.log('usernames:', usernames);
+```
+
 !SECTION ArangoDB Query Builder
 
 The [ArangoDB Query Builder](https://www.npmjs.org/package/aqb) NPM module comes bundled with Foxx and provides a fluid API for generating complex AQL queries while avoiding raw string concatenation.
 
-Query Builder query objects can be used in any function that would normally expect an AQL string.
+Query Builder objects can be used in any function that would normally expect an AQL string.
 
 For a full overview of the query builder API [see the project documentation](https://github.com/arangodb/aqbjs).
 
@@ -17,7 +52,16 @@ var db = require('org/arangodb').db;
 var qb = require('aqb');
 var console = require('console');
 
-var usernames = db._query(qb.for('user').in('_users').return('user.user')).toArray();
+var isAdmin = true;
+var userCollection = applicationContext.collection('users');
+
+var usernames = db._query(qb
+    .for('user')
+    .in(userCollection)
+    .filter(qb(isAdmin).eq('user.isAdmin'))
+    .return('user')
+).toArray();
+
 console.log('usernames:', usernames);
 ```
 
@@ -49,6 +93,8 @@ If **params** is provided, the query function will accept positional arguments i
 
 If both *model*** and **transform** are provided, the **transform** function will be applied to the result array _after_ the results have been converted into model instances. The **transform** function is always passed the entire result array and its return value will be returned by the query function.
 
+**Note**: `Foxx.createQuery` provides a high-level abstraction around the underlying `db._query` API and provides an easy way to generate Foxx models from query results at the expense of hiding internals like query metadata (e.g. number of documents affected by a modification query). If you just want to perform AQL queries and don't need the abstractions provided by `Foxx.createQuery` you can just use the lower-level `db._query` API directly.
+
 **Examples**
 
 Basic usage example: