aqb
    DefinitelyTyped icon, indicating that this package has TypeScript declarations provided by the separate @types/aqb package

    2.1.0 • Public • Published

    ArangoDB Query Builder

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

    license - APACHE-2.0 Dependencies

    NPM status

    Build status Coverage Status Codacy rating

    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)

    OR

    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)

    OR

    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)

    OR

    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)

    OR

    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.

    Install

    npm i aqb

    DownloadsWeekly Downloads

    151

    Version

    2.1.0

    License

    APACHE-2.0

    Last publish

    Collaborators

    • pluma
    • jsteemann