10000 Doc - Backports to 3.4 - 2018-12-27 (#7859) · arangodb/arangodb@6eff183 · GitHub
[go: up one dir, main page]
Skip to content

Commit 6eff183

Browse files
sleto-itsleto-it
authored
Doc - Backports to 3.4 - 2018-12-27 (#7859)
1 parent f163149 commit 6eff183

File tree

15 files changed

+596
-263
lines changed

15 files changed

+596
-263
lines changed

‎Documentation/Books/Drivers/JS/Reference/Aql.md

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
<!-- don't edit here, it's from https://@github.com/arangodb/arangojs.git / docs/Drivers/ -->
2+
# AQL Helpers
3+
4+
These helpers are available via the `aql` export from the arangojs module:
5+
6+
```js
7+
import arangojs, { aql } from "arangojs";
8+
9+
// or CommonJS:
10+
11+
const arangojs = require("arangojs");
12+
const aql = arangojs.aql;
13+
```
14+
15+
## aql
16+
17+
`aql: AqlQuery`
18+
19+
The `aql` function is a JavaScript template string handler (or template tag).
20+
It can be used to write complex AQL queries as multi-line strings without
21+
having to worry about bindVars and the distinction between collections
22+
and regular parameters.
23+
24+
To use it just prefix a JavaScript template string (the ones with backticks
25+
instead of quotes) with its import name (e.g. `aql`) and pass in variables
26+
like you would with a regular template string. The string will automatically
27+
be converted into an object with `query` and `bindVars` attributes which you
28+
can pass directly to `db.query` to execute. If you pass in a collection it
29+
will be automatically recognized as a collection reference
30+
and handled accordingly.
31+
32+
The `aql` template tag can also be used inside other `aql` template strings,
33+
allowing arbitrary nesting. Bind parameters of nested queries will be merged
34+
automatically.
35+
36+
**Examples**
37+
38+
```js
39+
const filterValue = 23;
40+
const mydata = db.collection("mydata");
41+
const result = await db.query(aql`
42+
FOR d IN ${mydata}
43+
FILTER d.num > ${filterValue}
44+
RETURN d
45+
`);
46+
47+
// nested queries
48+
49+
const color = "green";
50+
const filterByColor = aql`FILTER d.color == ${color}'`;
51+
const result2 = await db.query(aql`
52+
FOR d IN ${mydata}
53+
${filterByColor}
54+
RETURN d
55+
`);
56+
```
57+
58+
## aql.literal
59+
60+
`aql.literal(value): AqlLiteral`
61+
62+
The `aql.literal` helper can be used to mark strings to be inlined into an AQL
63+
query when using the `aql` template tag, rather than being treated as a bind
64+
parameter.
65+
66+
{% hint 'danger' %}
67+
Any value passed to `aql.literal` will be treated as part of the AQL query.
68+
To avoid becoming vulnerable to AQL injection attacks you should always prefer
69+
nested `aql` queries if possible.
70+
{% endhint %}
71+
72+
**Arguments**
73+
74+
- **value**: `string`
75+
76+
An arbitrary string that will be treated as a literal AQL fragment when used
77+
in an `aql` template.
78+
79+
**Examples**
80+
81+
```js
82+
const filterGreen = aql.literal('FILTER d.color == "green"');
83+
const result = await db.query(aql`
84+
FOR d IN ${mydata}
85+
${filterGreen}
86+
RETURN d
87+
`);
88+
```
89+
90+
## aql.join
91+
92+
`aql.join(values)`
93+
94+
The `aql.join` helper takes an array of queries generated using the `aql` tag
95+
and combines them into a single query. The optional second argument will be
96+
used as literal string to combine the queries.
97+
98+
**Arguments**
99+
100+
- **values**: `Array`
101+
102+
An array of arbitrary values, typically AQL query objects or AQL literals.
103+
104+
- **sep**: `string` (Default: `" "`)
105+
106+
String that will be used in between the values.
107+
108+
**Examples**
109+
110+
```js
111+
// Basic usage
112+
const parts = [aql`FILTER`, aql`x`, aql`%`, aql`2`];
113+
const joined = aql.join(parts); // aql`FILTER x % 2`
114+
115+
// Merge without the extra space
116+
const parts = [aql`FIL`, aql`TER`];
117+
const joined = aql.join(parts, ""); // aql`FILTER`;
118+
119+
// Real world example: translate keys into document lookups
120+
const users = db.collection("users");
121+
const keys = ["abc123", "def456"];
122+
const docs = keys.map(key => aql`DOCUMENT(${users}, ${key})`);
123+
const aqlArray = aql`[${aql.join(docs, ", ")}]`;
124+
const result = await db.query(aql`
125+
FOR d IN ${aqlArray}
126+
RETURN d
127+
`);
128+
// Query:
129+
// FOR d IN [DOCUMENT(@@value0, @value1), DOCUMENT(@@value0, @value2)]
130+
// RETURN d
131+
// Bind parameters:
132+
// @value0: "users"
133+
// value1: "abc123"
134+
// value2: "def456"
135+
136+
// Alternative without `aql.join`
137+
const users = db.collection("users");
138+
const keys = ["abc123", "def456"];
139+
const result = await db.query(aql`
140+
FOR key IN ${keys}
141+
LET d = DOCUMENT(${users}, key)
142+
RETURN d
143+
`);
144+
// Query:
145+
// FOR key IN @value0
146+
// LET d = DOCUMENT(@@value1, key)
147+
// RETURN d
148+
// Bind parameters:
149+
// value0: ["abc123", "def456"]
150+
// @value1: "users"
151+
```

‎Documentation/Books/Drivers/JS/Reference/Cursor.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@ remaining result list.
3232
**Examples**
3333

3434
```js
35-
const cursor = await db._query('FOR x IN 1..5 RETURN x');
35+
const cursor = await db.query('FOR x IN 1..5 RETURN x');
3636
const result = await cursor.all()
3737
// result is an array containing the entire query result
3838
assert.deepEqual(result, [1, 2, 3, 4, 5]);

‎Documentation/Books/Drivers/JS/Reference/Database/Queries.md

Lines changed: 121 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,10 @@
11
<!-- don't edit here, it's from https://@github.com/arangodb/arangojs.git / docs/Drivers/ -->
22
# Queries
33

4-
This function implements the
5-
[HTTP API for single round-trip AQL queries](../../../..//HTTP/AqlQueryCursor/QueryResults.html).
4+
These functions implements the
5+
[HTTP API for single round-trip AQL queries](../../../..//HTTP/AqlQueryCursor/QueryResults.html)
6+
as well as the
7+
[HTTP API for managing queries](../../../..//HTTP/AqlQuery/index.html).
68

79
For collection-specific queries see [Simple Queries](../Collection/SimpleQueries.md).
810

@@ -15,10 +17,13 @@ Performs a database query using the given _query_ and _bindVars_, then returns a
1517

1618
**Arguments**
1719

18-
- **query**: `string`
20+
- **query**: `string | AqlQuery | AqlLiteral`
1921

20-
An AQL query string or a [query builder](https://npmjs.org/package/aqb)
21-
instance.
22+
An AQL query as a string or
23+
[AQL query object](../Aql.md#aql) or
24+
[AQL literal](../Aql.md#aqlliteral).
25+
If the query is an AQL query object, the second argument is treated as the
26+
_opts_ argument instead of _bindVars_.
2227

2328
- **bindVars**: `Object` (optional)
2429

@@ -48,6 +53,12 @@ Dirty reads are only available when targeting ArangoDB 3.4 or later,
4853
see [Compatibility](../../GettingStarted/README.md#compatibility).
4954
{% endhint %}
5055

56+
Additionally _opts.timeout_ can be set to a non-negative number to force the
57+
request to be cancelled after that amount of milliseconds. Note that this will
58+
simply close the connection and not result in the actual query being cancelled
59+
in ArangoDB, the query will still be executed to completion and continue to
60+
consume resources in the database or cluster.
61+
5162
If _query_ is an object with _query_ and _bindVars_ properties, those will be
5263
used as the values of the respective arguments instead.
5364

@@ -68,10 +79,9 @@ const cursor = await db.query(aql`
6879
// -- or --
6980

7081
// Old-school JS with explicit bindVars:
71-
db.query(
72-
"FOR u IN _users FILTER u.authData.active == @active RETURN u.user",
73-
{ active: true }
74-
).then(function(cursor) {
82+
db.query("FOR u IN _users FILTER u.authData.active == @active RETURN u.user", {
83+
active: true
84+
}).then(function(cursor) {
7585
// cursor is a cursor for the query result
7686
});
7787
```
@@ -135,3 +145,105 @@ const query = aql`
135145
`;
136146
// FILTER user.email == @value0
137147
```
148+
149+
## database.explain
150+
151+
`async database.explain(query, [bindVars,] [opts]): ExplainResult`
152+
153+
Explains a database query using the given _query_ and _bindVars_ and
154+
returns one or more plans.
155+
156+
**Arguments**
157+
158+
- **query**: `string | AqlQuery | AqlLiteral`
159+
160+
An AQL query as a string or
161+
[AQL query object](../Aql.md#aql) or
162+
[AQL literal](../Aql.md#aqlliteral).
163+
If the query is an AQL query object, the second argument is treated as the
164+
_opts_ argument instead of _bindVars_.
165+
166+
- **bindVars**: `Object` (optional)
167+
168+
An object defining the variables to bind the query to.
169+
170+
- **opts**: `Object` (optional)
171+
172+
- **optimizer**: `Object` (optional)
173+
174+
An object with a single property **rules**, a string array of optimizer
175+
rules to be used for the query.
176+
177+
- **maxNumberOfPlans**: `number` (optional)
178+
179+
Maximum number of plans that the optimizer is allowed to generate.
180+
Setting this to a low value limits the amount of work the optimizer does.
181+
182+
- **allPlans**: `boolean` (Default: `false`)
183+
184+
If set to true, all possible execution plans will be returned
185+
as the _plans_ property. Otherwise only the optimal execution plan will
186+
be returned as the _plan_ property.
187+
188+
## database.parse
189+
190+
`async database.parse(query): ParseResult`
191+
192+
Parses the given query and returns the result.
193+
194+
**Arguments**
195+
196+
- **query**: `string | AqlQuery | AqlLiteral`
197+
198+
An AQL query as a string or
199+
[AQL query object](../Aql.md#aql) or
200+
[AQL literal](../Aql.md#aqlliteral).
201+
If the query is an AQL query object, its bindVars (if any) will be ignored.
202+
203+
## database.queryTracking
204+
205+
`async database.queryTracking(): QueryTrackingProperties`
206+
207+
Fetches the query tracking properties.
208+
209+
## database.setQueryTracking
210+
211+
`async database.setQueryTracking(props): void`
212+
213+
Modifies the query tracking properties.
214+
215+
**Arguments**
216+
217+
- **props**: `Partial<QueryTrackingProperties>`
218+
219+
Query tracking properties with new values to set.
220+
221+
## database.listRunningQueries
222+
223+
`async database.listRunningQueries(): Array<QueryStatus>`
224+
225+
Fetches a list of information for all currently running queries.
226+
227+
## database.listSlowQueries
228+
229+
`async database.listSlowQueries(): Array<SlowQueryStatus>`
230+
231+
Fetches a list of information for all recent slow queries.
232+
233+
## database.clearSlowQueries
234+
235+
`async database.clearSlowQueries(): void`
236+
237+
Clears the list of recent slow queries.
238+
239+
## database.killQuery
240+
241+
`async database.killQuery(queryId): void`
242+
243+
Kills a running query with the given ID.
244+
245+
**Arguments**
246+
247+
- **queryId**: `string`
248+
249+
The ID of a currently running query.

‎Documentation/Books/Drivers/JS/Reference/Database/README.md

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -49,11 +49,23 @@ If _config_ is a string, it will be interpreted as _config.url_.
4949
your certificates to the _agentOptions_, e.g.:
5050

5151
```js
52+
...
5253
agentOptions: {
5354
ca: [
5455
fs.readFileSync(".ssl/sub.class1.server.ca.pem"),
5556
fs.readFileSync(".ssl/ca.pem")
56-
];
57+
]
58+
}
59+
```
60+
61+
Although this is **strongly discouraged**, it's also possible to disable
62+
HTTPS certificate validation entirely, but note this has
63+
**extremely dangerous** security implications:
64+
65+
```js
66+
...
67+
agentOptions: {
68+
rejectUnauthorized: false
5769
}
5870
```
5971

‎Documentation/Books/Drivers/JS/Reference/README.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@
1919
- [Indexes](Collection/Indexes.md)
2020
- [Simple Queries](Collection/SimpleQueries.md)
2121
- [Bulk Import](Collection/BulkImport.md)
22+
- [AQL Helpers](Aql.md)
2223
- [View Manipulation](ViewManipulation.md)
2324
- [Cursor](Cursor.md)
2425
- [Graph](Graph/README.md)

0 commit comments

Comments
 (0)
0