ArangoDB Query Builder

We don't recommend using this lib anymore. We've implemented an aql template handler in arangojs which should be used instead.

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

Install

With NPM

npm install aqb

ArangoDB

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.

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