aqb

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.

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

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)

Examples

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

LET varname = expression

PartialStatement::let(varname, expression) : Statement

Alias: let_(varname, expression)

Examples

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

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

PartialStatement::let(definitions) : Statement

Alias: let_(definitions)

Examples

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

RETURN expression

PartialStatement::return(expression) : Statement

Alias: return_(expression)

Examples

• _.return('x') => RETURN x

FILTER expression

PartialStatement::filter(expression) : Statement

Examples

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

COLLECT …

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

… INTO varname

CollectExpression::into(varname) : Statement

Examples

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

… INTO varname COUNT

CollectExpression::into(varname).count() : Statement

Examples

• _.into('z').count() => INTO z COUNT

… KEEP varname

CollectExpression::keep(varname) : Statement

Examples

• _.keep('z') => KEEP z

… SORT args…

PartialStatement::sort(args…) : Statement

Examples

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

… LIMIT offset, count

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

Examples

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

REMOVE …

REMOVE expression IN collection

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

Aliases:

• remove(expression).in_(collection)
• remove(expression).into(collection)

Examples

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

… LET varname = OLD RETURN varname

RemoveExpression::returnOld(varname) : Statement

Examples

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

… OPTIONS options

RemoveExpression::options(options) : Statement

Examples

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

INSERT …

INSERT expression INTO collection

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

Aliases:

• insert(expression).in(collection)
• insert(expression).in_(collection)

Examples

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

… OPTIONS options

InsertExpression::options(options) : Statement

Examples

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

… LET varname = NEW RETURN varname

InsertExpression::returnNew(varname) : Statement

Examples

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

UPDATE …

UPDATE expression IN collection

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

Aliases:

• update(expression).in_(collection)
• 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

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)

Examples

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

… OPTIONS options

UpdateExpression::options(options) : Statement

Examples

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

… LET varname = NEW RETURN varname

UpdateExpression::returnNew(varname) : Statement

Examples

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

… LET varname = OLD RETURN varname

UpdateExpression::returnOld(varname) : Statement

Examples

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

REPLACE …

REPLACE expression IN collection

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

Aliases:

• replace(expression).in_(collection)
• 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

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)

Examples

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

… OPTIONS options

ReplaceExpression::options(options) : Statement

Examples

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

… LET varname = NEW RETURN varname

ReplaceExpression::returnOld(varname) : Statement

Examples

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

… LET varname = OLD RETURN varname

ReplaceExpression::returnNew(varname) : Statement

Examples

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

License

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