mirror of https://gitee.com/bigwinds/arangodb
505 lines
12 KiB
Markdown
505 lines
12 KiB
Markdown
# ArangoDB Query Builder
|
|
|
|
The query builder allows constructing complex AQL queries with a pure JavaScript fluid API.
|
|
|
|
```js
|
|
// in arangosh
|
|
var db = require('org/arangodb').db;
|
|
var qb = require('aqb');
|
|
console.log(db._query(qb.for('x').in('1..5').return('x')).toArray()); // [1, 2, 3, 4, 5]
|
|
```
|
|
|
|
## API
|
|
|
|
### AQL Types
|
|
|
|
If raw JavaScript values are passed to AQL statements, they will be wrapped in a matching AQL type automatically.
|
|
|
|
JavaScript strings wrapped in quotation marks will be wrapped in AQL strings, all other JavaScript strings will be wrapped as simple references (see below) and throw an *AQLError* if they are not well-formed.
|
|
|
|
#### Boolean
|
|
|
|
Wraps the given value as an AQL Boolean literal.
|
|
|
|
`qb.bool(value)`
|
|
|
|
If the value is truthy, it will be converted to the AQL Boolean *true*, otherwise it will be converted to the AQL Boolean *false*.
|
|
|
|
If the value is already an AQL Boolean, its own value will be wrapped instead.
|
|
|
|
#### Number
|
|
|
|
Wraps the given value as an AQL Number literal.
|
|
|
|
`qb.num(value)`
|
|
|
|
If the value is not a JavaScript Number, it will be converted first.
|
|
|
|
If the value does not represent a finite number, an *AQLError* will be thrown.
|
|
|
|
If the value is already an AQL Number or AQL Integer, its own value will be wrapped instead.
|
|
|
|
#### Integer
|
|
|
|
Wraps the given value as an AQL Integer literal.
|
|
|
|
`qb.int(value)`
|
|
|
|
If the value is not a JavaScript Number, it will be converted first.
|
|
|
|
If the value does not represent a finite integer, an *AQLError* will be thrown.
|
|
|
|
If the value is already an AQL Number or AQL Integer, its own value will be wrapped instead.
|
|
|
|
*Alias:* `qb.int_(value)`
|
|
|
|
#### String
|
|
|
|
Wraps the given value as an AQL String literal.
|
|
|
|
`qb.str(value)`
|
|
|
|
If the value is not a JavaScript String, it will be converted first.
|
|
|
|
If the value is already an AQL String, its own value will be wrapped instead.
|
|
|
|
If the value is an object with a *toAQL* method, the result of calling that method will be wrapped instead.
|
|
|
|
#### List
|
|
|
|
Wraps the given value as an AQL List (Array) literal.
|
|
|
|
`qb.list(value)`
|
|
|
|
If the value is not a JavaScript Array, an *AQLError* will be thrown.
|
|
|
|
If the value is already an AQL List, its own value will be wrapped instead.
|
|
|
|
Any list elements that are not already AQL values will be converted automatically.
|
|
|
|
#### Object
|
|
|
|
Wraps the given value as an AQL Object literal.
|
|
|
|
`qb.obj(value)`
|
|
|
|
If the value is not a JavaScript Object, an *AQLError* will be thrown.
|
|
|
|
If the value is already an AQL List, its own value will be wrapped instead.
|
|
|
|
Any property values that are not already AQL values will be converted automatically.
|
|
|
|
#### Simple Reference
|
|
|
|
Wraps a given value in an AQL Simple Reference.
|
|
|
|
`qb.ref(value)`
|
|
|
|
If the value is not a JavaScript string or not a well-formed simple reference, an *AQLError* will be thrown.
|
|
|
|
If the value is an *ArangoCollection*, its *name* property will be used instead.
|
|
|
|
If the value is already an AQL Simple Reference, its value is wrapped instead.
|
|
|
|
*Examples*
|
|
|
|
Valid values:
|
|
|
|
* `foo`
|
|
* `foo.bar`
|
|
* `foo[*].bar`
|
|
* `foo.bar.QUX`
|
|
* `_foo._bar._qux`
|
|
* `foo1.bar2`
|
|
|
|
Invalid values:
|
|
|
|
* `1foo`
|
|
* `föö`
|
|
* `foo bar`
|
|
* `foo-bar`
|
|
* `foo[bar]`
|
|
|
|
ArangoDB collection objects can be passed directly:
|
|
|
|
```js
|
|
var myUserCollection = applicationContext.collection('users');
|
|
var users = db._query(qb.for('u').in(myUserCollection).return('u')).toArray();
|
|
```
|
|
|
|
### AQL Expressions
|
|
|
|
#### Range
|
|
|
|
Creates a range expression from the given values.
|
|
|
|
`qb.range(value1, value2)` -> `value1..value2`
|
|
|
|
If the values are not already AQL values, they will be converted automatically.
|
|
|
|
#### Property Access
|
|
|
|
Creates a property access expression from the given values.
|
|
|
|
`qb.get(obj, key)` -> `obj[key]`
|
|
|
|
If the values are not already AQL values, they will be converted automatically.
|
|
|
|
#### Raw Expression
|
|
|
|
Wraps a given value in a raw AQL expression.
|
|
|
|
`qb.expr(value)`
|
|
|
|
If the value is already an AQL Raw Expression, its value is wrapped instead.
|
|
|
|
**Warning:** Whenever possible, you should use one of the other methods or a combination thereof instead of using a raw expression. Raw expressions allow passing arbitrary strings into your AQL and thus will open you to AQL injection attacks if you are passing in untrusted user input.
|
|
|
|
### AQL Operations
|
|
|
|
#### Boolean And
|
|
|
|
Creates an "and" operation from the given values.
|
|
|
|
`qb.and(a, b)` -> `(a && b)`
|
|
|
|
If the values are not already AQL values, they will be converted automatically.
|
|
|
|
This function can take any number of arguments.
|
|
|
|
*Examples*
|
|
|
|
`qb.and(a, b, c, d, e, f)` -> `(a && b && c && d && e && f)`
|
|
|
|
#### Boolean Or
|
|
|
|
Creates an "or" operation from the given values.
|
|
|
|
`qb.or(a, b)` -> `(a || b)`
|
|
|
|
If the values are not already AQL values, they will be converted automatically.
|
|
|
|
This function can take any number of arguments.
|
|
|
|
*Examples*
|
|
|
|
`qb.or(a, b, c, d, e, f)` -> `(a || b || c || d || e || f)`
|
|
|
|
#### Addition
|
|
|
|
Creates an addition operation from the given values.
|
|
|
|
`qb.add(a, b)` -> `(a + b)`
|
|
|
|
If the values are not already AQL values, they will be converted automatically.
|
|
|
|
This function can take any number of arguments.
|
|
|
|
*Alias:* `qb.plus(a, b)`
|
|
|
|
*Examples*
|
|
|
|
`qb.add(a, b, c, d, e, f)` -> `(a + b + c + d + e + f)`
|
|
|
|
#### Subtraction
|
|
|
|
Creates a subtraction operation from the given values.
|
|
|
|
`qb.sub(a, b)` -> `(a - b)`
|
|
|
|
If the values are not already AQL values, they will be converted automatically.
|
|
|
|
This function can take any number of arguments.
|
|
|
|
*Alias:* `qb.minus(a, b)`
|
|
|
|
*Examples*
|
|
|
|
`qb.sub(a, b, c, d, e, f)` -> `(a - b - c - d - e - f)`
|
|
|
|
#### Multiplication
|
|
|
|
Creates a multiplication operation from the given values.
|
|
|
|
`qb.mul(a, b)` -> `(a * b)`
|
|
|
|
If the values are not already AQL values, they will be converted automatically.
|
|
|
|
This function can take any number of arguments.
|
|
|
|
*Alias:* `qb.times(a, b)`
|
|
|
|
*Examples*
|
|
|
|
`qb.mul(a, b, c, d, e, f)` -> `(a * b * c * d * e * f)`
|
|
|
|
#### Division
|
|
|
|
Creates a division operation from the given values.
|
|
|
|
`qb.div(a, b)` -> `(a / b)`
|
|
|
|
If the values are not already AQL values, they will be converted automatically.
|
|
|
|
This function can take any number of arguments.
|
|
|
|
*Examples*
|
|
|
|
`qb.div(a, b, c, d, e, f)` -> `(a / b / c / d / e / f)`
|
|
|
|
#### Modulus
|
|
|
|
Creates a modulus operation from the given values.
|
|
|
|
`qb.mod(a, b)` -> `(a % b)`
|
|
|
|
If the values are not already AQL values, they will be converted automatically.
|
|
|
|
This function can take any number of arguments.
|
|
|
|
*Examples*
|
|
|
|
`qb.mod(a, b, c, d, e, f)` -> `(a % b % c % d % e % f)`
|
|
|
|
#### Equality
|
|
|
|
Creates an equality comparison from the given values.
|
|
|
|
`qb.eq(a, b)` -> `(a == b)`
|
|
|
|
If the values are not already AQL values, they will be converted automatically.
|
|
|
|
#### Inequality
|
|
|
|
Creates an inequality comparison from the given values.
|
|
|
|
`qb.neq(a, b)` -> `(a != b)`
|
|
|
|
If the values are not already AQL values, they will be converted automatically.
|
|
|
|
#### Greater Than
|
|
|
|
Creates a greater-than comparison from the given values.
|
|
|
|
`qb.gt(a, b)` -> `(a > b)`
|
|
|
|
If the values are not already AQL values, they will be converted automatically.
|
|
|
|
#### Greater Than Or Equal To
|
|
|
|
Creates a greater-than-or-equal-to comparison from the given values.
|
|
|
|
`qb.gte(a, b)` -> `(a >= b)`
|
|
|
|
If the values are not already AQL values, they will be converted automatically.
|
|
|
|
#### Less Than
|
|
|
|
Creates a less-than comparison from the given values.
|
|
|
|
`qb.lt(a, b)` -> `(a < b)`
|
|
|
|
If the values are not already AQL values, they will be converted automatically.
|
|
|
|
#### Less Than Or Equal To
|
|
|
|
Creates a less-than-or-equal-to comparison from the given values.
|
|
|
|
`qb.lte(a, b)` -> `(a <= b)`
|
|
|
|
If the values are not already AQL values, they will be converted automatically.
|
|
|
|
#### Contains
|
|
|
|
Creates an "in" comparison from the given values.
|
|
|
|
`qb.in(a, b)` -> `(a in b)`
|
|
|
|
If the values are not already AQL values, they will be converted automatically.
|
|
|
|
*Aliases:* `qb.in_(a, b)`
|
|
|
|
#### Negation
|
|
|
|
Creates a negation from the given value.
|
|
|
|
`qb.not(a)` -> `!(a)`
|
|
|
|
If the value is not already an AQL value, it will be converted automatically.
|
|
|
|
#### Negative Value
|
|
|
|
Creates a negative value expression from the given value.
|
|
|
|
`qb.neg(a)` -> `-(a)`
|
|
|
|
If the value is not already an AQL value, it will be converted automatically.
|
|
|
|
#### Ternary (if / else)
|
|
|
|
Creates a ternary expression from the given values.
|
|
|
|
`qb.if(condition, then, otherwise)` -> `(condition ? then : otherwise)`
|
|
|
|
If the values are not already AQL values, they will be converted automatically.
|
|
|
|
*Aliases:* `qb.if_(condition, then, otherwise)`
|
|
|
|
#### Function Call
|
|
|
|
Creates a function call for the given name and arguments.
|
|
|
|
`qb.fn(name)(args…)`
|
|
|
|
If the values are not already AQL values, they will be converted automatically.
|
|
|
|
For built-in functions, methods with the relevant function name are already provided by the query builder.
|
|
|
|
*Examples*
|
|
|
|
* `qb.fn('MY::USER::FUNC')(1, 2, 3)` -> `MY::USER::FUNC(1, 2, 3)`
|
|
* `qb.fn('hello')()` -> `hello()`
|
|
* `qb.RANDOM()` -> `RANDOM()`
|
|
* `qb.FLOOR(qb.div(5, 2))` -> `FLOOR((5 / 2))`
|
|
|
|
### AQL Statements
|
|
|
|
In addition to the methods documented above, the query builder provides all methods of *PartialStatement* objects.
|
|
|
|
AQL *Statement* objects have a method *toAQL()* which returns their AQL representation as a JavaScript string.
|
|
|
|
*Examples*
|
|
|
|
```
|
|
qb.for('doc').in('my_collection').return('doc._key').toAQL()
|
|
// -> FOR doc IN my_collection RETURN doc._key
|
|
```
|
|
|
|
#### FOR expression IN collection
|
|
|
|
`PartialStatement::for(expression).in(collection) : Statement`
|
|
|
|
*Alias:* `for_(expression).in_(collection)`
|
|
|
|
#### LET varname = expression
|
|
|
|
`PartialStatement::let(varname, expression) : Statement`
|
|
|
|
*Alias:* `let_(varname, expression)`
|
|
|
|
#### LET var1 = expr1, var2 = expr2, …, varn = exprn
|
|
|
|
`PartialStatement::let(definitions) : Statement`
|
|
|
|
*Alias:* `let_(definitions)`
|
|
|
|
#### FILTER expression
|
|
|
|
`PartialStatement::filter(expression) : Statement`
|
|
|
|
#### COLLECT varname = expression
|
|
|
|
`PartialStatement::collect(varname, expression) : Statement`
|
|
|
|
#### COLLECT varname1 = expression INTO varname2
|
|
|
|
`PartialStatement::collect(varname1, expression).into(varname2) : Statement`
|
|
|
|
#### COLLECT var1 = expr1, var2 = expr2, …, varn = exprn
|
|
|
|
`PartialStatement::collect(definitions) : Statement`
|
|
|
|
#### COLLECT var1 = expr1, var2 = expr2, …, varn = exprn INTO varname
|
|
|
|
`PartialStatement::collect(definitions).into(varname) : Statement`
|
|
|
|
#### SORT args…
|
|
|
|
`PartialStatement::sort(args…) : Statement`
|
|
|
|
#### LIMIT offset, count
|
|
|
|
`PartialStatement::limit([offset,] count) : Statement`
|
|
|
|
#### RETURN expression
|
|
|
|
`PartialStatement::return(expression) : Statement`
|
|
|
|
*Alias:* `return_(expression)`
|
|
|
|
#### REMOVE expression IN collection
|
|
|
|
`PartialStatement::remove(expression).in(collection) : RemoveExpression`
|
|
|
|
*Aliases:*
|
|
|
|
* `remove(expression).in_(collection)`
|
|
* `remove(expression).into(collection)`
|
|
|
|
#### REMOVE … OPTIONS options
|
|
|
|
`RemoveExpression::options(options) : Statement`
|
|
|
|
#### INSERT expression INTO collection
|
|
|
|
`PartialStatement::insert(expression).into(collection) : InsertExpression`
|
|
|
|
*Aliases:*
|
|
|
|
* `insert(expression).in(collection)`
|
|
* `insert(expression).in_(collection)`
|
|
|
|
#### INSERT … OPTIONS options
|
|
|
|
`InsertExpression::options(options) : Statement`
|
|
|
|
#### UPDATE expression1 WITH expression2 IN collection
|
|
|
|
`PartialStatement::update(expression1).with(expression2).in(collection) : UpdateExpression`
|
|
|
|
*Aliases:*
|
|
|
|
* `update(expression1).with(expression2).in_(collection)`
|
|
* `update(expression1).with(expression2).into(collection)`
|
|
* `update(expression1).with_(expression2).in(collection)`
|
|
* `update(expression1).with_(expression2).in_(collection)`
|
|
* `update(expression1).with_(expression2).into(collection)`
|
|
|
|
#### UPDATE expression IN collection
|
|
|
|
`PartialStatement::update(expression).in(collection) : UpdateExpression`
|
|
|
|
*Aliases:*
|
|
|
|
* `update(expression).in_(collection)`
|
|
* `update(expression).into(collection)`
|
|
|
|
#### UPDATE … OPTIONS options
|
|
|
|
`UpdateExpression::options(options) : Statement`
|
|
|
|
#### REPLACE expression1 WITH expression2 IN collection
|
|
|
|
`PartialStatement::replace(expression1).with(expression2).in(collection) : ReplaceExpression`
|
|
|
|
*Aliases:*
|
|
|
|
* `replace(expression1).with(expression2).in_(collection)`
|
|
* `replace(expression1).with(expression2).into(collection)`
|
|
* `replace(expression1).with_(expression2).in(collection)`
|
|
* `replace(expression1).with_(expression2).in_(collection)`
|
|
* `replace(expression1).with_(expression2).into(collection)`
|
|
|
|
#### REPLACE expression IN collection
|
|
|
|
`PartialStatement::replace(expression).in(collection) : ReplaceExpression`
|
|
|
|
*Aliases:*
|
|
|
|
* `replace(expression).in_(collection)`
|
|
* `replace(expression).into(collection)`
|
|
|
|
#### REPLACE … OPTIONS options
|
|
|
|
`ReplaceExpression::options(options) : Statement`
|