Hawkin
/
arangodb
mirror of https://gitee.com/bigwinds/arangodb
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Doc - Sync-external-repo-2018-12-25 (#7854)

This commit is contained in:
Omar_A 2018-12-27 11:17:11 +01:00 committed by sleto-it
parent 4db6390054
commit 5bf0eb4fea
11 changed files with 536 additions and 241 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

151
Documentation/Books/Drivers/JS/Reference/Aql.md Normal file
View File

@ -0,0 +1,151 @@
<!-- don't edit here, it's from https://@github.com/arangodb/arangojs.git / docs/Drivers/ -->
# 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"
```

2
Documentation/Books/Drivers/JS/Reference/Cursor.md
View File

@ -32,7 +32,7 @@ remaining result list.
**Examples**
```js
const cursor = await db._query('FOR x IN 1..5 RETURN x');
const cursor = await db.query('FOR x IN 1..5 RETURN x');
const result = await cursor.all()
// result is an array containing the entire query result
assert.deepEqual(result, [1, 2, 3, 4, 5]);

130
Documentation/Books/Drivers/JS/Reference/Database/Queries.md
View File

@ -1,8 +1,10 @@
<!-- don't edit here, it's from https://@github.com/arangodb/arangojs.git / docs/Drivers/ -->
# Queries
This function implements the
[HTTP API for single round-trip AQL queries](../../../..//HTTP/AqlQueryCursor/QueryResults.html).
These functions implements the
[HTTP API for single round-trip AQL queries](../../../..//HTTP/AqlQueryCursor/QueryResults.html)
as well as the
[HTTP API for managing queries](../../../..//HTTP/AqlQuery/index.html).
For collection-specific queries see [Simple Queries](../Collection/SimpleQueries.md).
@ -15,10 +17,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)
@ -48,6 +53,12 @@ Dirty reads are only available when targeting ArangoDB 3.4 or later,
see [Compatibility](../../GettingStarted/README.md#compatibility).
{% endhint %}
Additionally _opts.timeout_ can be set to a non-negative number to force the
request to be cancelled after that amount of milliseconds. Note that this will
simply close the connection and not result in the actual query being cancelled
in ArangoDB, the query will still be executed to completion and continue to
consume resources in the database or cluster.
If _query_ is an object with _query_ and _bindVars_ properties, those will be
used as the values of the respective arguments instead.
@ -68,10 +79,9 @@ const cursor = await db.query(aql`
// -- or --
// Old-school JS with explicit bindVars:
db.query(
"FOR u IN _users FILTER u.authData.active == @active RETURN u.user",
{ active: true }
).then(function(cursor) {
db.query("FOR u IN _users FILTER u.authData.active == @active RETURN u.user", {
active: true
}).then(function(cursor) {
// cursor is a cursor for the query result
});
```
@ -135,3 +145,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.

14
Documentation/Books/Drivers/JS/Reference/Database/README.md
View File

@ -49,11 +49,23 @@ If _config_ is a string, it will be interpreted as _config.url_.
your certificates to the _agentOptions_, e.g.:
```js
...
agentOptions: {
ca: [
fs.readFileSync(".ssl/sub.class1.server.ca.pem"),
fs.readFileSync(".ssl/ca.pem")
];
]
}
```
Although this is **strongly discouraged**, it's also possible to disable
HTTPS certificate validation entirely, but note this has
**extremely dangerous** security implications:
```js
...
agentOptions: {
rejectUnauthorized: false
}
```

1
Documentation/Books/Drivers/JS/Reference/README.md
View File

@ -19,6 +19,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)

142
Documentation/Books/Drivers/JS/Reference/Route.md
View File

@ -13,11 +13,11 @@ route) that can be used to perform arbitrary HTTP requests.
**Arguments**
* **path**: `string` (optional)
- **path**: `string` (optional)
The relative URL of the route.
* **headers**: `Object` (optional)
- **headers**: `Object` (optional)
Default headers that should be sent with each request to the route.
@ -40,12 +40,12 @@ Performs a GET request to the given URL and returns the server response.
**Arguments**
* **path**: `string` (optional)
- **path**: `string` (optional)
The route-relative URL for the request. If omitted, the request will be made
to the base URL of the route.
* **qs**: `string` (optional)
- **qs**: `string` (optional)
The query string for the request. If _qs_ is an object, it will be translated
to a query string.
@ -54,20 +54,20 @@ Performs a GET request to the given URL and returns the server response.
```js
const db = new Database();
const route = db.route('my-foxx-service');
const route = db.route("my-foxx-service");
const response = await route.get();
// response.body is the response body of calling
// GET _db/_system/my-foxx-service
// -- or --
const response = await route.get('users');
const response = await route.get("users");
// response.body is the response body of calling
// GET _db/_system/my-foxx-service/users
// -- or --
const response = await route.get('users', {group: 'admin'});
const response = await route.get("users", { group: "admin" });
// response.body is the response body of calling
// GET _db/_system/my-foxx-service/users?group=admin
```
@ -80,16 +80,16 @@ Performs a POST request to the given URL and returns the server response.
**Arguments**
* **path**: `string` (optional)
- **path**: `string` (optional)
The route-relative URL for the request. If omitted, the request will be made
to the base URL of the route.
* **body**: `string` (optional)
- **body**: `string` (optional)
The response body. If _body_ is an object, it will be encoded as JSON.
* **qs**: `string` (optional)
- **qs**: `string` (optional)
The query string for the request. If _qs_ is an object, it will be translated
to a query string.
@ -98,22 +98,22 @@ Performs a POST request to the given URL and returns the server response.
```js
const db = new Database();
const route = db.route('my-foxx-service');
const response = await route.post()
const route = db.route("my-foxx-service");
const response = await route.post();
// response.body is the response body of calling
// POST _db/_system/my-foxx-service
// -- or --
const response = await route.post('users')
const response = await route.post("users");
// response.body is the response body of calling
// POST _db/_system/my-foxx-service/users
// -- or --
const response = await route.post('users', {
username: 'admin',
password: 'hunter2'
const response = await route.post("users", {
username: "admin",
password: "hunter2"
});
// response.body is the response body of calling
// POST _db/_system/my-foxx-service/users
@ -121,10 +121,14 @@ const response = await route.post('users', {
// -- or --
const response = await route.post('users', {
username: 'admin',
password: 'hunter2'
}, {admin: true});
const response = await route.post(
"users",
{
username: "admin",
password: "hunter2"
},
{ admin: true }
);
// response.body is the response body of calling
// POST _db/_system/my-foxx-service/users?admin=true
// with JSON request body {"username": "admin", "password": "hunter2"}
@ -138,16 +142,16 @@ Performs a PUT request to the given URL and returns the server response.
**Arguments**
* **path**: `string` (optional)
- **path**: `string` (optional)
The route-relative URL for the request. If omitted, the request will be made
to the base URL of the route.
* **body**: `string` (optional)
- **body**: `string` (optional)
The response body. If _body_ is an object, it will be encoded as JSON.
* **qs**: `string` (optional)
- **qs**: `string` (optional)
The query string for the request. If _qs_ is an object, it will be translated
to a query string.
@ -156,22 +160,22 @@ Performs a PUT request to the given URL and returns the server response.
```js
const db = new Database();
const route = db.route('my-foxx-service');
const route = db.route("my-foxx-service");
const response = await route.put();
// response.body is the response body of calling
// PUT _db/_system/my-foxx-service
// -- or --
const response = await route.put('users/admin');
const response = await route.put("users/admin");
// response.body is the response body of calling
// PUT _db/_system/my-foxx-service/users
// -- or --
const response = await route.put('users/admin', {
username: 'admin',
password: 'hunter2'
const response = await route.put("users/admin", {
username: "admin",
password: "hunter2"
});
// response.body is the response body of calling
// PUT _db/_system/my-foxx-service/users/admin
@ -179,10 +183,14 @@ const response = await route.put('users/admin', {
// -- or --
const response = await route.put('users/admin', {
username: 'admin',
password: 'hunter2'
}, {admin: true});
const response = await route.put(
"users/admin",
{
username: "admin",
password: "hunter2"
},
{ admin: true }
);
// response.body is the response body of calling
// PUT _db/_system/my-foxx-service/users/admin?admin=true
// with JSON request body {"username": "admin", "password": "hunter2"}
@ -196,16 +204,16 @@ Performs a PATCH request to the given URL and returns the server response.
**Arguments**
* **path**: `string` (optional)
- **path**: `string` (optional)
The route-relative URL for the request. If omitted, the request will be made
to the base URL of the route.
* **body**: `string` (optional)
- **body**: `string` (optional)
The response body. If _body_ is an object, it will be encoded as JSON.
* **qs**: `string` (optional)
- **qs**: `string` (optional)
The query string for the request. If _qs_ is an object, it will be translated
to a query string.
@ -214,21 +222,21 @@ Performs a PATCH request to the given URL and returns the server response.
```js
const db = new Database();
const route = db.route('my-foxx-service');
const route = db.route("my-foxx-service");
const response = await route.patch();
// response.body is the response body of calling
// PATCH _db/_system/my-foxx-service
// -- or --
const response = await route.patch('users/admin');
const response = await route.patch("users/admin");
// response.body is the response body of calling
// PATCH _db/_system/my-foxx-service/users
// -- or --
const response = await route.patch('users/admin', {
password: 'hunter2'
const response = await route.patch("users/admin", {
password: "hunter2"
});
// response.body is the response body of calling
// PATCH _db/_system/my-foxx-service/users/admin
@ -236,9 +244,13 @@ const response = await route.patch('users/admin', {
// -- or --
const response = await route.patch('users/admin', {
password: 'hunter2'
}, {admin: true});
const response = await route.patch(
"users/admin",
{
password: "hunter2"
},
{ admin: true }
);
// response.body is the response body of calling
// PATCH _db/_system/my-foxx-service/users/admin?admin=true
// with JSON request body {"password": "hunter2"}
@ -252,12 +264,12 @@ Performs a DELETE request to the given URL and returns the server response.
**Arguments**
* **path**: `string` (optional)
- **path**: `string` (optional)
The route-relative URL for the request. If omitted, the request will be made
to the base URL of the route.
* **qs**: `string` (optional)
- **qs**: `string` (optional)
The query string for the request. If _qs_ is an object, it will be translated
to a query string.
@ -266,20 +278,20 @@ Performs a DELETE request to the given URL and returns the server response.
```js
const db = new Database();
const route = db.route('my-foxx-service');
const response = await route.delete()
const route = db.route("my-foxx-service");
const response = await route.delete();
// response.body is the response body of calling
// DELETE _db/_system/my-foxx-service
// -- or --
const response = await route.delete('users/admin')
const response = await route.delete("users/admin");
// response.body is the response body of calling
// DELETE _db/_system/my-foxx-service/users/admin
// -- or --
const response = await route.delete('users/admin', {permanent: true})
const response = await route.delete("users/admin", { permanent: true });
// response.body is the response body of calling
// DELETE _db/_system/my-foxx-service/users/admin?permanent=true
```
@ -292,12 +304,12 @@ Performs a HEAD request to the given URL and returns the server response.
**Arguments**
* **path**: `string` (optional)
- **path**: `string` (optional)
The route-relative URL for the request. If omitted, the request will be made
to the base URL of the route.
* **qs**: `string` (optional)
- **qs**: `string` (optional)
The query string for the request. If _qs_ is an object, it will be translated
to a query string.
@ -306,7 +318,7 @@ Performs a HEAD request to the given URL and returns the server response.
```js
const db = new Database();
const route = db.route('my-foxx-service');
const route = db.route("my-foxx-service");
const response = await route.head();
// response is the response object for
// HEAD _db/_system/my-foxx-service
@ -320,46 +332,52 @@ Performs an arbitrary request to the given URL and returns the server response.
**Arguments**
* **opts**: `Object` (optional)
- **opts**: `Object` (optional)
An object with any of the following properties:
* **path**: `string` (optional)
- **path**: `string` (optional)
The route-relative URL for the request. If omitted, the request will be made
to the base URL of the route.
* **absolutePath**: `boolean` (Default: `false`)
- **absolutePath**: `boolean` (Default: `false`)
Whether the _path_ is relative to the connection's base URL instead of the
route.
* **body**: `string` (optional)
- **body**: `string` (optional)
The response body. If _body_ is an object, it will be encoded as JSON.
* **qs**: `string` (optional)
- **qs**: `string` (optional)
The query string for the request. If _qs_ is an object, it will be
translated to a query string.
* **headers**: `Object` (optional)
- **headers**: `Object` (optional)
An object containing additional HTTP headers to be sent with the request.
* **method**: `string` (Default: `"GET"`)
- **method**: `string` (Default: `"GET"`)
HTTP method of this request.
- **timeout**: `number` (optional)
A non-negative amount of milliseconds after which the request will be
aborted. Note that ArangoDB may continue processing the request even
after it has timed out.
**Examples**
```js
const db = new Database();
const route = db.route('my-foxx-service');
const route = db.route("my-foxx-service");
const response = await route.request({
path: 'hello-world',
method: 'POST',
body: {hello: 'world'},
path: "hello-world",
method: "POST",
body: { hello: "world" },
qs: { admin: true }
});
// response.body is the response body of calling

24
Documentation/Books/Drivers/Java/Reference/Setup.md
View File

@ -11,16 +11,16 @@ ArangoDB arangoDB = new ArangoDB.Builder().build();
The driver is configured with some default values:
property-key | description | default value
-------------------------|-----------------------------------------|----------------
arangodb.hosts | ArangoDB hosts | 127.0.0.1:8529
arangodb.timeout | connect & request timeout (millisecond) | 0
arangodb.user | Basic Authentication User |
arangodb.password | Basic Authentication Password |
arangodb.useSsl | use SSL connection | false
arangodb.chunksize | VelocyStream Chunk content-size (bytes) | 30000
arangodb.connections.max | max number of connections | 1 VST, 20 HTTP
arangodb.protocol | used network protocol | VST
| property-key | description | default value |
| ------------------------ | --------------------------------------- | -------------- |
| arangodb.hosts | ArangoDB hosts | 127.0.0.1:8529 |
| arangodb.timeout | connect & request timeout (millisecond) | 0 |
| arangodb.user | Basic Authentication User |
| arangodb.password | Basic Authentication Password |
| arangodb.useSsl | use SSL connection | false |
| arangodb.chunksize | VelocyStream Chunk content-size (bytes) | 30000 |
| arangodb.connections.max | max number of connections | 1 VST, 20 HTTP |
| arangodb.protocol | used network protocol | VST |
To customize the configuration the parameters can be changed in the code...
@ -178,8 +178,8 @@ ArangoDB arangoDB = new ArangoDB.Builder()
## Connection time to live
Since version 4.4 the driver supports setting a TTL for connections managed
by the internal connection pool.
Since version 4.4 the driver supports setting a TTL (time to life) in milliseconds
for connections managed by the internal connection pool.
```Java
ArangoDB arango = new ArangoDB.Builder()

1
Documentation/Books/Drivers/SUMMARY.md
View File

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