The query builder allows constructing complex AQL queries with a pure JavaScript fluid API.
npm install aqb
bower install aqb
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.
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.
git clone https://github.com/arangodb/aqbjs.git
cd aqbjs
npm install
npm run dist
// 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]
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'));
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.
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.
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.
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)
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\""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.
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)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:
foofoo.barfoo[*].barfoo.bar.QUX_foo._bar._quxfoo1.bar2`foo`.barfoo.`bar`Invalid values:
1foofööfoo barfoo[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();
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
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]`
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.
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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.
Aliases: qb.in_(a, b)
Examples
qb.ref('x').in('y') => (x in y)
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)
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)
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.
Aliases:
qb.if_(condition, thenDo, elseDo)qbValue.then(thenDo).otherwise(elseDo)Examples
qb.ref('x').then('y').else('z') => (x ? y : z)
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))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
PartialStatement::for(expression).in(collection) : Statement
Alias: for_(expression).in_(collection)
Examples
_.for('doc').in('my_collection') => FOR doc IN my_collectionPartialStatement::let(varname, expression) : Statement
Alias: let_(varname, expression)
Examples
_.let('foo', 23) => `LET foo = 23PartialStatement::let(definitions) : Statement
Alias: let_(definitions)
Examples
_.let({a: 1, b: 2, c: 3}) => LET a = 1, b = 2, c = 3PartialStatement::return(expression) : Statement
Alias: return_(expression)
Examples
_.return('x') => RETURN xPartialStatement::filter(expression) : Statement
Examples
_.filter(qb.eq('a', 'b')) => FILTER a == bPartialStatement::collect(varname, expression) : CollectExpression
Examples
_.collect('x', 'y') => COLLECT x = yPartialStatement::collect(definitions) : CollectExpression
Examples
_.collect({x: 'a', y: 'b'}) => COLLECT x = a, y = bCollectExpression::into(varname) : Statement
Examples
_.into('z') => INTO zCollectExpression::into(varname).count() : Statement
Examples
_.into('z').count() => INTO z COUNTCollectExpression::keep(varname) : Statement
Examples
_.keep('z') => KEEP zPartialStatement::sort(args…) : Statement
Examples
_.sort('x', 'DESC', 'y', 'ASC') => SORT x DESC, y ASCPartialStatement::limit([offset,] count) : Statement
Examples
_.limit(20) => LIMIT 20_.limit(20, 20) => LIMIT 20, 20PartialStatement::remove(expression).in(collection) : RemoveExpression
Aliases:
remove(expression).in_(collection)remove(expression).into(collection)Examples
_.remove('x').in('y') => REMOVE x IN yRemoveExpression::returnOld(varname) : Statement
Examples
_.returnOld('z') => LET z = OLD RETURN zRemoveExpression::options(options) : Statement
Examples
_.options('opts') => OPTIONS optsPartialStatement::insert(expression).into(collection) : InsertExpression
Aliases:
insert(expression).in(collection)insert(expression).in_(collection)Examples
_.insert('x').into('y') => INSERT x INTO yInsertExpression::options(options) : Statement
Examples
_.options('opts') => OPTIONS optsInsertExpression::returnNew(varname) : Statement
Examples
_.returnNew('z') => LET z = NEW RETURN zPartialStatement::update(expression).in(collection) : UpdateExpression
Aliases:
update(expression).in_(collection)update(expression).into(collection)Examples
_.update('x').in('y') => UPDATE x IN yPartialStatement::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 zUpdateExpression::options(options) : Statement
Examples
_.options('opts') => OPTIONS optsUpdateExpression::returnNew(varname) : Statement
Examples
_.returnNew('z') => LET z = NEW RETURN zUpdateExpression::returnOld(varname) : Statement
Examples
_.returnOld('z') => LET z = OLD RETURN zPartialStatement::replace(expression).in(collection) : ReplaceExpression
Aliases:
replace(expression).in_(collection)replace(expression).into(collection)Examples
_.replace('x').in('y') => REPLACE x IN yPartialStatement::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 zReplaceExpression::options(options) : Statement
Examples
_.options('opts') => OPTIONS optsReplaceExpression::returnOld(varname) : Statement
Examples
_.returnNew('z') => LET z = NEW RETURN zReplaceExpression::returnNew(varname) : Statement
Examples
_.returnOld('z') => LET z = OLD RETURN zThe Apache License, Version 2.0. For more information, see the accompanying LICENSE file.
FAQs
ArangoDB AQL query builder.
We found that aqb demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
A threat actor's playbook for exploiting the npm ecosystem was exposed on the dark web, detailing how to build a blockchain-powered botnet.
Security News
NVD’s backlog surpasses 20,000 CVEs as analysis slows and NIST announces new system updates to address ongoing delays.
Security News
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.