Add query management API (#590)

* Add query management API

* Fix parse/explain results

* Document query API

* Add tests

Author: pluma

CHANGELOG.md

@@ -23,6 +23,10 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
   and ArangoDB will still continue processing the request, this will merely
   result in the socket being forcefully disconnected.
 
+- Added query management API
+
+  This implements most endpoints of https://docs.arangodb.com/3.4/HTTP/AqlQuery/.
+
 ## [6.9.0] - 2018-11-07
 
 ### Changed

docs/Drivers/JS/Reference/Aql.md

@@ -0,0 +1,150 @@
+# AQL Helpers
+
+These helpers are available via the `aql` export from the arangojs module:
+
+```js
+import arangojs, { aql } from "arangojs";
+
+// or CommonJS:
+
+const arangojs = require("arangojs");
+const aql = arangojs.aql;
+```
+
+## aql
+
+`aql: AqlQuery`
+
+The `aql` function is a JavaScript template string handler (or template tag).
+It can be used to write complex AQL queries as multi-line strings without
+having to worry about bindVars and the distinction between collections
+and regular parameters.
+
+To use it just prefix a JavaScript template string (the ones with backticks
+instead of quotes) with its import name (e.g. `aql`) and pass in variables
+like you would with a regular template string. The string will automatically
+be converted into an object with `query` and `bindVars` attributes which you
+can pass directly to `db.query` to execute. If you pass in a collection it
+will be automatically recognized as a collection reference
+and handled accordingly.
+
+The `aql` template tag can also be used inside other `aql` template strings,
+allowing arbitrary nesting. Bind parameters of nested queries will be merged
+automatically.
+
+**Examples**
+
+```js
+const filterValue = 23;
+const mydata = db.collection("mydata");
+const result = await db.query(aql`
+  FOR d IN ${mydata}
+  FILTER d.num > ${filterValue}
+  RETURN d
+`);
+
+// nested queries
+
+const color = "green";
+const filterByColor = aql`FILTER d.color == ${color}'`;
+const result2 = await db.query(aql`
+  FOR d IN ${mydata}
+  ${filterByColor}
+  RETURN d
+`);
+```
+
+## aql.literal
+
+`aql.literal(value): AqlLiteral`
+
+The `aql.literal` helper can be used to mark strings to be inlined into an AQL
+query when using the `aql` template tag, rather than being treated as a bind
+parameter.
+
+{% hint 'danger' %}
+Any value passed to `aql.literal` will be treated as part of the AQL query.
+To avoid becoming vulnerable to AQL injection attacks you should always prefer
+nested `aql` queries if possible.
+{% endhint %}
+
+**Arguments**
+
+- **value**: `string`
+
+  An arbitrary string that will be treated as a literal AQL fragment when used
+  in an `aql` template.
+
+**Examples**
+
+```js
+const filterGreen = aql.literal('FILTER d.color == "green"');
+const result = await db.query(aql`
+  FOR d IN ${mydata}
+  ${filterGreen}
+  RETURN d
+`);
+```
+
+## aql.join
+
+`aql.join(values)`
+
+The `aql.join` helper takes an array of queries generated using the `aql` tag
+and combines them into a single query. The optional second argument will be
+used as literal string to combine the queries.
+
+**Arguments**
+
+- **values**: `Array`
+
+  An array of arbitrary values, typically AQL query objects or AQL literals.
+
+- **sep**: `string` (Default: `" "`)
+
+  String that will be used in between the values.
+
+**Examples**
+
+```js
+// Basic usage
+const parts = [aql`FILTER`, aql`x`, aql`%`, aql`2`];
+const joined = aql.join(parts); // aql`FILTER x % 2`
+
+// Merge without the extra space
+const parts = [aql`FIL`, aql`TER`];
+const joined = aql.join(parts, ""); // aql`FILTER`;
+
+// Real world example: translate keys into document lookups
+const users = db.collection("users");
+const keys = ["abc123", "def456"];
+const docs = keys.map(key => aql`DOCUMENT(${users}, ${key})`);
+const aqlArray = aql`[${aql.join(docs, ", ")}]`;
+const result = await db.query(aql`
+  FOR d IN ${aqlArray}
+  RETURN d
+`);
+// Query:
+//   FOR d IN [DOCUMENT(@@value0, @value1), DOCUMENT(@@value0, @value2)]
+//   RETURN d
+// Bind parameters:
+//   @value0: "users"
+//   value1: "abc123"
+//   value2: "def456"
+
+// Alternative without `aql.join`
+const users = db.collection("users");
+const keys = ["abc123", "def456"];
+const result = await db.query(aql`
+  FOR key IN ${keys}
+  LET d = DOCUMENT(${users}, key)
+  RETURN d
+`);
+// Query:
+//   FOR key IN @value0
+//   LET d = DOCUMENT(@@value1, key)
+//   RETURN d
+// Bind parameters:
+//   value0: ["abc123", "def456"]
+//   @value1: "users"
+```

docs/Drivers/JS/Reference/Database/Queries.md

@@ -1,7 +1,9 @@
 # Queries
 
-This function implements the
-[HTTP API for single round-trip AQL queries](https://docs.arangodb.com/latest/HTTP/AqlQueryCursor/QueryResults.html).
+These functions implements the
+[HTTP API for single round-trip AQL queries](https://docs.arangodb.com/latest/HTTP/AqlQueryCursor/QueryResults.html)
+as well as the
+[HTTP API for managing queries](https://docs.arangodb.com/latest/HTTP/AqlQuery/index.html).
 
 For collection-specific queries see [Simple Queries](../Collection/SimpleQueries.md).
 
@@ -14,10 +16,13 @@ Performs a database query using the given _query_ and _bindVars_, then returns a
 
 **Arguments**
 
-- **query**: `string`
+- **query**: `string | AqlQuery | AqlLiteral`
 
-  An AQL query string or a [query builder](https://npmjs.org/package/aqb)
-  instance.
+  An AQL query as a string or
+  [AQL query object](../Aql.md#aql) or
+  [AQL literal](../Aql.md#aqlliteral).
+  If the query is an AQL query object, the second argument is treated as the
+  _opts_ argument instead of _bindVars_.
 
 - **bindVars**: `Object` (optional)
 
@@ -139,3 +144,105 @@ const query = aql`
 `;
 // FILTER user.email == @value0
 ```
+
+## database.explain
+
+`async database.explain(query, [bindVars,] [opts]): ExplainResult`
+
+Explains a database query using the given _query_ and _bindVars_ and
+returns one or more plans.
+
+**Arguments**
+
+- **query**: `string | AqlQuery | AqlLiteral`
+
+  An AQL query as a string or
+  [AQL query object](../Aql.md#aql) or
+  [AQL literal](../Aql.md#aqlliteral).
+  If the query is an AQL query object, the second argument is treated as the
+  _opts_ argument instead of _bindVars_.
+
+- **bindVars**: `Object` (optional)
+
+  An object defining the variables to bind the query to.
+
+- **opts**: `Object` (optional)
+
+  - **optimizer**: `Object` (optional)
+
+    An object with a single property **rules**, a string array of optimizer
+    rules to be used for the query.
+
+  - **maxNumberOfPlans**: `number` (optional)
+
+    Maximum number of plans that the optimizer is allowed to generate.
+    Setting this to a low value limits the amount of work the optimizer does.
+
+  - **allPlans**: `boolean` (Default: `false`)
+
+    If set to true, all possible execution plans will be returned
+    as the _plans_ property. Otherwise only the optimal execution plan will
+    be returned as the _plan_ property.
+
+## database.parse
+
+`async database.parse(query): ParseResult`
+
+Parses the given query and returns the result.
+
+**Arguments**
+
+- **query**: `string | AqlQuery | AqlLiteral`
+
+  An AQL query as a string or
+  [AQL query object](../Aql.md#aql) or
+  [AQL literal](../Aql.md#aqlliteral).
+  If the query is an AQL query object, its bindVars (if any) will be ignored.
+
+## database.queryTracking
+
+`async database.queryTracking(): QueryTrackingProperties`
+
+Fetches the query tracking properties.
+
+## database.setQueryTracking
+
+`async database.setQueryTracking(props): void`
+
+Modifies the query tracking properties.
+
+**Arguments**
+
+- **props**: `Partial<QueryTrackingProperties>`
+
+  Query tracking properties with new values to set.
+
+## database.listRunningQueries
+
+`async database.listRunningQueries(): Array<QueryStatus>`
+
+Fetches a list of information for all currently running queries.
+
+## database.listSlowQueries
+
+`async database.listSlowQueries(): Array<SlowQueryStatus>`
+
+Fetches a list of information for all recent slow queries.
+
+## database.clearSlowQueries
+
+`async database.clearSlowQueries(): void`
+
+Clears the list of recent slow queries.
+
+## database.killQuery
+
+`async database.killQuery(queryId): void`
+
+Kills a running query with the given ID.
+
+**Arguments**
+
+- **queryId**: `string`
+
+  The ID of a currently running query.

docs/Drivers/JS/Reference/README.md

@@ -18,6 +18,7 @@
   - [Indexes](Collection/Indexes.md)
   - [Simple Queries](Collection/SimpleQueries.md)
   - [Bulk Import](Collection/BulkImport.md)
+- [AQL Helpers](Aql.md)
 - [View Manipulation](ViewManipulation.md)
 - [Cursor](Cursor.md)
 - [Graph](Graph/README.md)