ArangoDB Query Builder

The query builder allows constructing complex AQL queries with a pure JavaScript fluid API.

Install

With NPM

npm install aqb

With Bower

bower install aqb

ArangoDB

As of ArangoDB 1.3, a version of aqb comes pre-installed with ArangoDB.

var qb = require('aqb');

If you want to use a more recent version of aqb in a Foxx app, you can add it to your NPM dependencies as usual.

Browser

This CommonJS module is compatible with browserify.

If you don't want to use browserify, you can simply use the AMD-compatible browserify bundle (~30 kB minified, ~6 kB gzipped).

If you want to use this module in non-ES5 browsers like Microsoft Internet Explorer 8 and earlier, you may need to include es5-shim or a similar ES5 polyfill.

From source

git clone https://github.com/arangodb/aqbjs.git
cd aqbjs
npm install
npm run dist

Example

// 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

Auto-casting raw data

By default, the query builder will attempt to interpret raw strings as identifiers or references or other kinds of expressions. This may not always be what you want, especially when handling raw untrusted data.

As of version 1.8 you can now pass arbitrary data directly to the query builder itself and it will be translated to the equivalent AQL structure (e.g. strings will be strings, dates will be converted to JSON, arrays and objects will be translated recursively, and so on):

var doc = {
    aString: "hello",
    aDate: new Date(),
    aNumber: 23,
    anArray: [1, 2, 3, "potato"]
};
db._query(qb.insert(qb(doc)).into('my_collection'));

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.

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 a quoted string, it will be treated as a string literal.

If the value is an object with a toAQL method, the result of calling that method will be wrapped instead.

Examples

23 => "23"
"some string" => "some string"
'"some string"' => "\"some string\""

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 Object, its own value will be wrapped instead.

Any property values that are not already AQL values will be converted automatically.

Any keys that are quoted strings will be treated as string literals.

Any keys that start with the character ":" will be treated as dynamic properties and must be well-formed simple references.

Any other keys that need escaping will be quoted if necessary.

If you need to pass in raw JavaScript objects that shouldn't be converted according to these rules, you can use the qb function directly instead.

Examples

qb.obj({'some.name': 'value'}) => {"some.name": value}
qb.obj({hello: world}) => {hello: world}
qb.obj({'"hello"': world}) => {"hello": world}
qb.obj({':dynamic': 'props'}) => {[dynamic]: props}
qb.obj({': invalid': 'key'}) => throws an error (invalid is not a well-formed reference)

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
`foo`.bar
foo.`bar`

Invalid values:

1foo
föö
foo bar
foo[bar]

ArangoDB collection objects can be passed directly:

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

OR:

aqlValue.range(value2) => value1..value2

If the values are not already AQL values, they will be converted automatically.

Alias: qb.to(value1, value2)

Examples

qb(2).to(5) => 2..5

Property Access

Creates a property access expression from the given values.

qb.get(obj, key) => obj[key]

OR:

aqlObj.get(key) => obj[key]

If the values are not already AQL values, they will be converted automatically.

Examples

qb.ref('x').get('y') =>x[y]`

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)

OR:

aqlValue.and(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.ref('x').and('y') => (x && y)

Boolean Or

Creates an "or" operation from the given values.

qb.or(a, b) => (a || b)

OR:

aqlValue.or(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.ref('x').or('y') => (x || y)

Addition

Creates an addition operation from the given values.

qb.add(a, b) => (a + b)

OR:

aqlValue.add(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.ref('x').plus('y') => (x + y)

Subtraction

Creates a subtraction operation from the given values.

qb.sub(a, b) => (a - b)

OR:

aqlValue.sub(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.ref('x').minus('y') => (x - y)

Multiplication

Creates a multiplication operation from the given values.

qb.mul(a, b) => (a * b)

OR:

aqlValue.mul(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.ref('x').times('y') => (x * y)

Division

Creates a division operation from the given values.

qb.div(a, b) => (a / b)

OR:

aqlValue.div(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.ref('x').div('y') => (x / y)

Modulus

Creates a modulus operation from the given values.

qb.mod(a, b) => (a % b)

OR:

aqlValue.mod(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.ref('x').mod('y') => (x % y)

Equality

Creates an equality comparison from the given values.

qb.eq(a, b) => (a == b)

OR:

qbValue.eq(b) => (a == b)

If the values are not already AQL values, they will be converted automatically.

Examples

qb.ref('x').eq('y') => (x == y)

Inequality

Creates an inequality comparison from the given values.

qb.neq(a, b) => (a != b)

OR:

qbValue.neq(b) => (a != b)

If the values are not already AQL values, they will be converted automatically.

Examples

qb.ref('x').neq('y') => (x != y)

Greater Than

Creates a greater-than comparison from the given values.

qb.gt(a, b) => (a > b)

qbValue.gt(b) => (a > b)

If the values are not already AQL values, they will be converted automatically.

Examples

qb.ref('x').gt('y') => (x > y)

Greater Than Or Equal To

Creates a greater-than-or-equal-to comparison from the given values.

qb.gte(a, b) => (a >= b)

qbValue.gte(b) => (a >= b)

If the values are not already AQL values, they will be converted automatically.

Examples

qb.ref('x').gte('y') => (x >= y)

Less Than

Creates a less-than comparison from the given values.

qb.lt(a, b) => (a < b)

qbValue.lt(b) => (a < b)

If the values are not already AQL values, they will be converted automatically.

Examples

qb.ref('x').lt('y') => (x < y)

Less Than Or Equal To

Creates a less-than-or-equal-to comparison from the given values.

qb.lte(a, b) => (a <= b)

qbValue.lte(b) => (a <= b)

If the values are not already AQL values, they will be converted automatically.

Examples

qb.ref('x').lte('y') => (x <= y)

Contains

Creates an "in" comparison from the given values.

qb.in(a, b) => (a in b)

OR:

qbValue.in(b) => (a in b)

If the values are not already AQL values, they will be converted automatically.

Examples

qb.ref('x').in('y') => (x in y)

Negation

Creates a negation from the given value.

qb.not(a) => !(a)

OR:

qbValue.not() => !(a)

If the value is not already an AQL value, it will be converted automatically.

Examples

qb.not('x') => !(x)

Negative Value

Creates a negative value expression from the given value.

qb.neg(a) => -(a)

OR:

qbValue.neg() => -(a)

If the value is not already an AQL value, it will be converted automatically.

Examples

qb.neg('x') => -(x)

Ternary (if / else)

Creates a ternary expression from the given values.

qb.if(condition, thenDo, elseDo) => (condition ? thenDo : elseDo)

OR:

qbValue.then(thenDo).else(elseDo) => (condition ? thenDo : elseDo)

If the values are not already AQL values, they will be converted automatically.

Alias: qbValue.then(thenDo).otherwise(elseDo)

Examples

qb.ref('x').then('y').else('z') => (x ? y : z)

Function Call

Creates a functon 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) : PartialStatement

Examples

_.for('doc').in('my_collection') => FOR doc IN my_collection

LET varname = expression

PartialStatement::let(varname, expression) : PartialStatement

Examples

_.let('foo', 23) => LET foo = 23

LET var1 = expr1, var2 = expr2, …, varn = exprn

PartialStatement::let(definitions) : PartialStatement

Examples

_.let({a: 1, b: 2, c: 3}) => LET a = 1, b = 2, c = 3

RETURN expression

PartialStatement::return(expression) : ReturnExpression

Examples

_.return('x') => RETURN x
_.return({x: 'x'}) => RETURN {x: x}

RETURN DISTINCT expression

PartialStatement::returnDistinct(expression) : ReturnExpression

Examples

_.returnDistinct('x') => RETURN DISTINCT x

FILTER expression

PartialStatement::filter(expression) : PartialStatement

Examples

_.filter(qb.eq('a', 'b')) => FILTER a == b

COLLECT …

COLLECT WITH COUNT INTO varname

PartialStatement::collectWithCountInto(varname) : CollectExpression

Examples

_.collectWithCountInto('x') => COLLECT WITH COUNT INTO x

COLLECT varname = expression

PartialStatement::collect(varname, expression) : CollectExpression

Examples

_.collect('x', 'y') => COLLECT x = y

COLLECT var1 = expr1, var2 = expr2, …, varn = exprn

PartialStatement::collect(definitions) : CollectExpression

Examples

_.collect({x: 'a', y: 'b'}) => COLLECT x = a, y = b

… WITH COUNT INTO varname

CollectExpression::withCountInto(varname) : CollectExpression

Examples

_.withCountInto('x') => WITH COUNT INTO x

… INTO varname

CollectExpression::into(varname) : CollectExpression

Examples

_.into('z') => INTO z

… KEEP ...vars

CollectExpression::keep(...vars) : CollectExpression

Examples

_.into('z').keep('a', 'b') => INTO z KEEP a, b

… INTO varname = expression

CollectExpression::into(varname, expression) : CollectExpression

Examples

_.into('x', 'y') => INTO x = y

… OPTIONS options

CollectExpression::options(options) : CollectExpression

Examples

_.options('opts') => OPTIONS opts

… SORT ...args

PartialStatement::sort(...args) : PartialStatement

Examples

_.sort('x', 'DESC', 'y', 'ASC') => SORT x DESC, y ASC

… LIMIT offset, count

PartialStatement::limit([offset,] count) : PartialStatement

Examples

_.limit(20) => LIMIT 20
_.limit(20, 20) => LIMIT 20, 20

REMOVE …

REMOVE expression IN collection

PartialStatement::remove(expression).in(collection) : RemoveExpression

Alias: remove(expression).into(collection)

Examples

_.remove('x').in('y') => REMOVE x IN y

… LET varname = OLD RETURN varname

RemoveExpression::returnOld(varname) : ReturnExpression

Examples

_.returnOld('z') => LET z = OLD RETURN z

… OPTIONS options

RemoveExpression::options(options) : RemoveExpression

Examples

_.options('opts') => OPTIONS opts

UPSERT …

UPSERT expression1 INSERT expression2 REPLACE expression3 IN collection

PartialStatement::upsert(expression1).insert(expression2).replace(expression3).in(collection) : UpsertExpression

Alias: ….into(collection)

Examples

_.upsert('x').insert('y').replace('z').in('c') => UPSERT x INSERT y REPLACE z IN c

UPSERT expression1 INSERT expression2 UPDATE expression3 IN collection

PartialStatement::upsert(expression1).insert(expression2).update(expression3).in(collection) : UpsertExpression

Alias: ….into(collection)

Examples

_.upsert('x').insert('y').update('z').in('c') => UPSERT x INSERT y UPDATE z IN c

… OPTIONS options

UpsertExpression::options(options) : UpsertExpression

Examples

_.options('opts') => OPTIONS opts

INSERT …

INSERT expression INTO collection

PartialStatement::insert(expression).into(collection) : InsertExpression

Alias: insert(expression).in(collection)

Examples

_.insert('x').into('y') => INSERT x INTO y

… OPTIONS options

InsertExpression::options(options) : InsertExpression

Examples

_.options('opts') => OPTIONS opts

… LET varname = NEW RETURN varname

InsertExpression::returnNew(varname) : ReturnExpression

Examples

_.returnNew('z') => LET z = NEW RETURN z

UPDATE …

UPDATE expression IN collection

PartialStatement::update(expression).in(collection) : UpdateExpression

Alias: update(expression).into(collection)

Examples

_.update('x').in('y') => UPDATE x IN y

UPDATE expression1 WITH expression2 IN collection

PartialStatement::update(expression1).with(expression2).in(collection) : UpdateExpression

Alias: update(expression1).with(expression2).into(collection)

Examples

_.update('x').with('y').in('z') => UPDATE x WITH y IN z

… OPTIONS options

UpdateExpression::options(options) : UpdateExpression

Examples

_.options('opts') => OPTIONS opts

… LET varname = NEW RETURN varname

UpdateExpression::returnNew(varname) : ReturnExpression

Examples

_.returnNew('z') => LET z = NEW RETURN z

… LET varname = OLD RETURN varname

UpdateExpression::returnOld(varname) : ReturnExpression

Examples

_.returnOld('z') => LET z = OLD RETURN z

REPLACE …

REPLACE expression IN collection

PartialStatement::replace(expression).in(collection) : ReplaceExpression

Alias: replace(expression).into(collection)

Examples

_.replace('x').in('y') => REPLACE x IN y

REPLACE expression1 WITH expression2 IN collection

PartialStatement::replace(expression1).with(expression2).in(collection) : ReplaceExpression

Alias: replace(expression1).with(expression2).into(collection)

Examples

_.replace('x').with('y').in('z') => REPLACE x WITH y IN z

… OPTIONS options

ReplaceExpression::options(options) : ReplaceExpression

Examples

_.options('opts') => OPTIONS opts

… LET varname = NEW RETURN varname

ReplaceExpression::returnOld(varname) : ReturnExpression

Examples

_.returnNew('z') => LET z = NEW RETURN z

… LET varname = OLD RETURN varname

ReplaceExpression::returnNew(varname) : ReturnExpression

Examples

_.returnOld('z') => LET z = OLD RETURN z

License

The Apache License, Version 2.0. For more information, see the accompanying LICENSE file.