node package manager

arangojs

The official ArangoDB JavaScript driver.

ArangoDB JavaScript driver

The official ArangoDB low-level JavaScript client.

The driver is being tested with ArangoDB 2.5, 2.6 and 2.7 using Node.js 0.12, 4.2 and stable. Versions outside of this range may be compatible but are not officially supported.

As of version 4.0.0 of this driver, a minified standalone browser bundle is also available.

Install

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

Basic usage example

// ES2015-style 
import arangojs, {Database, aqlQuery} from 'arangojs';
let db1 = arangojs(); // convenience short-hand 
let db2 = new Database();
let {query, bindVars} = aqlQuery`RETURN ${Date.now()}`;
 
// or plain old Node-style 
var arangojs = require('arangojs');
var db1 = arangojs();
var db2 = new arangojs.Database();
var aql = arangojs.aqlQuery(['RETURN ', ''], Date.now());
var query = aql.query;
var bindVars = aql.bindVars;

API

All asynchronous functions take an optional Node-style callback (or "errback") as the last argument with the following arguments:

  • err: an Error object if an error occurred, or null if no error occurred.
  • result: the function's result (if applicable).

For expected API errors, err will be an instance of ArangoError. For any other error responses (4xx/5xx status code), err will be an instance of the apropriate http-errors error type. If the response indicates success but the response body could not be parsed, err will be a SyntaxError. In all of these cases the error object will additionally have a response property containing the server response object.

If Promise is defined globally, asynchronous functions return a promise if no callback is provided.

If you want to use promises in environments that don't provide the global Promise constructor, use a promise polyfill like es6-promise or inject a ES6-compatible promise implementation like bluebird into the global scope.

Examples

// Node-style callbacks 
db.createDatabase('mydb', function (errinfo) {
    if (err) console.error(err.stack);
    else {
        // database created 
    }
});
 
// Using promises with ES2015 arrow functions 
db.createDatabase('mydb')
.then(info => {
    // database created 
}, err => console.error(err.stack));
 
// Using ES2016 "async/await" syntax 
try {
    let info = await db.createDatabase('mydb');
    // database created 
} catch (err) {
    console.error(err.stack);
}

new Database([config]): Database

Creates a new Database instance.

If config is a string, it will be interpreted as config.url.

Arguments

  • config: Object (optional)

    An object with the following properties:

    • url: string (Default: http://localhost:8529)

      Base URL of the ArangoDB server.

      If you want to use ArangoDB with HTTP Basic authentication, you can provide the credentials as part of the URL, e.g. http://user:pass@localhost:8529.

      The driver automatically uses HTTPS if you specify an HTTPS url.

      If you need to support self-signed HTTPS certificates, you may have to add your certificates to the agentOptions, e.g.:

      agentOptions: {
          ca: [
              fs.readFileSync('.ssl/sub.class1.server.ca.pem'),
              fs.readFileSync('.ssl/ca.pem')
          ]
      }
    • databaseName: string (Default: _system)

      Name of the active database.

    • arangoVersion: number (Default: 20300)

      Value of the x-arango-version header.

    • headers: Object (optional)

      An object with additional headers to send with every request.

    • agent: Agent (optional)

      An http Agent instance to use for connections.

      By default a new http.Agent (or https.Agent) instance will be created using the agentOptions.

      This option has no effect when using the browser version of arangojs.

    • agentOptions: Object (Default: see below)

      An object with options for the agent. This will be ignored if agent is also provided.

      Default: {maxSockets: 3, keepAlive: true, keepAliveMsecs: 1000}.

      In the browser version of arangojs this option can be used to pass additional options to the underlying calls of the xhr module. The options keepAlive and keepAliveMsecs have no effect in the browser but maxSockets will still be used to limit the amount of parallel requests made by arangojs.

    • promise: Class (optional)

      The Promise implementation to use or false to disable promises entirely.

      By default the global Promise constructor will be used if available.

These functions implement the HTTP API for manipulating databases.

database.useDatabase(databaseName): this

Updates the Database instance and its connection string to use the given databaseName, then returns itself.

Arguments

  • databaseName: string

    The name of the database to use.

Examples

var db = require('arangojs')();
db.useDatabase('test');
// The database instance now uses the database "test". 

async database.createDatabase(databaseName, [users]): Object

Creates a new database with the given databaseName.

Arguments

  • databaseName: string

    Name of the database to create.

  • users: Array<Object> (optional)

    If specified, the array must contain objects with the following properties:

    • username: string

      The username of the user to create for the database.

    • passwd: string (Default: empty)

      The password of the user.

    • active: boolean (Default: true)

      Whether the user is active.

    • extra: Object (optional)

      An object containing additional user data.

Examples

var db = require('arangojs')();
db.createDatabase('mydb', [{username: 'root'}])
.then(info => {
    // the database has been created 
});

async database.get(): Object

Fetches the database description for the active database from the server.

Examples

var db = require('arangojs')();
db.get()
.then(info => {
    // the database exists 
});

async database.listDatabases(): Array<string>

Fetches all databases from the server and returns an array of their names.

Examples

var db = require('arangojs')();
db.databases()
.then(names => {
    // databases is an array of database names 
});

async database.listUserDatabases(): Array<string>

Fetches all databases accessible to the active user from the server and returns an array of their names.

Examples

var db = require('arangojs')();
db.databases()
.then(names => {
    // databases is an array of database names 
});

async database.dropDatabase(databaseName): Object

Deletes the database with the given databaseName from the server.

var db = require('arangojs')();
db.dropDatabase('mydb')
.then(() => {
    // database "mydb" no longer exists 
})

async database.truncate([excludeSystem]): Object

Deletes all documents in all collections in the active database.

Arguments

  • excludeSystem: boolean (Default: true)

    Whether system collections should be excluded.

Examples

var db = require('arangojs')();
 
db.truncate()
.then(() => {
    // all non-system collections in this database are now empty 
});
 
// -- or -- 
 
db.truncate(false)
.then(() => {
    // I've made a huge mistake... 
});

These functions implement the HTTP API for accessing collections.

database.collection(collectionName): DocumentCollection

Returns a DocumentCollection instance for the given collection name.

Arguments

  • collectionName: string

    Name of the edge collection.

Examples

var db = require('arangojs')();
var collection = db.collection('potatos');

database.edgeCollection(collectionName): EdgeCollection

Returns an EdgeCollection instance for the given collection name.

Arguments

  • collectionName: string

    Name of the edge collection.

Examples

var db = require('arangojs')();
var collection = db.edgeCollection('potatos');

async database.listCollections([excludeSystem]): Array<Object>

Fetches all collections from the database and returns an array of collection descriptions.

Arguments

  • excludeSystem: boolean (Default: true)

    Whether system collections should be excluded from the results.

Examples

var db = require('arangojs')();
 
db.listCollections()
.then(collections => {
    // collections is an array of collection descriptions 
    // not including system collections 
});
 
// -- or -- 
 
db.listCollections(false)
.then(collections => {
    // collections is an array of collection descriptions 
    // including system collections 
});

async database.collections([excludeSystem]): Array<Collection>

Fetches all collections from the database and returns an array of DocumentCollection and EdgeCollection instances for the collections.

Arguments

  • excludeSystem: boolean (Default: true)

    Whether system collections should be excluded from the results.

Examples

var db = require('arangojs')();
 
db.listCollections()
.then(collections => {
    // collections is an array of DocumentCollection 
    // and EdgeCollection instances 
    // not including system collections 
});
 
// -- or -- 
 
db.listCollections(false)
.then(collections => {
    // collections is an array of DocumentCollection 
    // and EdgeCollection instances 
    // including system collections 
});

These functions implement the HTTP API for accessing general graphs.

database.graph(graphName): Graph

Returns a Graph instance representing the graph with the given graph name.

async database.listGraphs(): Array<Object>

Fetches all graphs from the database and returns an array of graph descriptions.

Examples

var db = require('arangojs')();
db.listGraphs()
.then(graphs => {
    // graphs is an array of graph descriptions 
});

async database.graphs(): Array<Graph>

Fetches all graphs from the database and returns an array of Graph instances for the graphs.

Examples

var db = require('arangojs')();
db.graphs()
.then(graphs => {
    // graphs is an array of Graph instances 
});

This function implements the HTTP API for transactions.

async database.transaction(collections, action, [params,] [lockTimeout]): Object

Performs a server-side transaction and returns its return value.

Arguments

  • collections: Object

    An object with the following properties:

    • read: Array<string> (optional)

      An array of names (or a single name) of collections that will be read from during the transaction.

    • write: Array<string> (optional)

      An array of names (or a single name) of collections that will be written to or read from during the transaction.

  • action: string

    A string evaluating to a JavaScript function to be executed on the server.

  • params: Array<any> (optional)

    Parameters that will be passed to the action function.

  • lockTimeout: number (optional)

    Determines how long the database will wait while attemping to gain locks on collections used by the transaction before timing out.

If collections is an array or string, it will be treated as collections.write.

Please note that while action should be a string evaluating to a well-formed JavaScript function, it's not possible to pass in a JavaScript function directly because the function needs to be evaluated on the server and will be transmitted in plain text.

For more information on transactions, see the HTTP API documentation for transactions.

Examples

var db = require('arangojs')();
var action = String(function () {
    // This code will be executed inside ArangoDB! 
    var db = require('org/arangodb').db;
    return db._query('FOR user IN _users RETURN u.user').toArray<any>();
});
db.transaction({read: '_users'}, action)
.then(result => {
    // result contains the return value of the action 
});

This function implements the HTTP API for single roundtrip AQL queries.

For collection-specific queries see simple queries.

async database.query(query, [bindVars,] [opts]): Cursor

Performs a database query using the given query and bindVars, then returns a new Cursor instance for the result list.

Arguments

  • query: string

    An AQL query string or a query builder instance.

  • bindVars: Object (optional)

    An object defining the variables to bind the query to.

  • opts: Object (optional)

    Additional options that will be passed to the query API.

If opts.count is set to true, the cursor will have a count property set to the query result count.

If query is an object with query and bindVars properties, those will be used as the values of the respective arguments instead.

Examples

var db = require('arangojs')();
var active = true;
 
// Using ES2015 string templates 
var aqlQuery = require('arangojs').aqlQuery;
db.query(aqlQuery`
    FOR u IN _users
    FILTER u.authData.active == ${active}
    RETURN u.user
`)
.then(cursor => {
    // cursor is a cursor for the query result 
});
 
// -- or -- 
 
// Using the query builder 
var qb = require('aqb');
db.query(
    qb.for('u').in('_users')
    .filter(qb.eq('u.authData.active', '@active'))
    .return('u.user'),
    {active: true}
)
.then(cursor => {
    // cursor is a cursor for the query result 
});
 
// -- or -- 
 
// Using plain arguments 
db.query(
    'FOR u IN _users'
    + ' FILTER u.authData.active == @active'
    + ' RETURN u.user',
    {active: true}
)
.then(cursor => {
    // cursor is a cursor for the query result 
});

aqlQuery(strings, ...args): Object

Template string handler for AQL queries. Converts an ES2015 template string to an object that can be passed to database.query by converting arguments to bind variables.

Any Collection instances will automatically be converted to collection bind variables.

Examples

var db = require('arangojs')();
var aqlQuery = require('arangojs').aqlQuery;
var userCollection = db.collection('_users');
var role = 'admin';
db.query(aqlQuery`
    FOR user IN ${userCollection}
    FILTER user.role == ${role}
    RETURN user
`)
.then(cursor => {
    // cursor is a cursor for the query result 
});
// -- is equivalent to -- 
db.query(
  'FOR user IN @@value0 FILTER user.role == @value1 RETURN user',
  {'@value0': userCollection.name, value1: role}
)
.then(cursor => {
    // cursor is a cursor for the query result 
});

These functions implement the HTTP API for managing AQL user functions.

async database.listFunctions(): Array<Object>

Fetches a list of all AQL user functions registered with the database.

Examples

var db = require('arangojs')();
db.listFunctions()
.then(functions => {
    // functions is a list of function descriptions 
})

async database.createFunction(name, code): Object

Creates an AQL user function with the given name and code if it does not already exist or replaces it if a function with the same name already existed.

Arguments

  • name: string

    A valid AQL function name, e.g.: "myfuncs::accounting::calculate_vat".

  • code: string

    A string evaluating to a JavaScript function (not a JavaScript function object).

Examples

var db = require('arangojs')();
var aqlQuery = require('arangojs').aqlQuery;
db.createFunction(
  'ACME::ACCOUNTING::CALCULATE_VAT',
  String(function (price) {
      return price * 0.19;
  })
)
// Use the new function in an AQL query with template handler: 
.then(() => db.query(aqlQuery`
    FOR product IN products
    RETURN MERGE(
      {vat: ACME::ACCOUNTING::CALCULATE_VAT(product.price)},
      product
    )
`))
.then(cursor => {
    // cursor is a cursor for the query result 
});

async database.dropFunction(name, [group]): Object

Deletes the AQL user function with the given name from the database.

Arguments

  • name: string

    The name of the user function to drop.

  • group: boolean (Default: false)

    If set to true, all functions with a name starting with name will be deleted; otherwise only the function with the exact name will be deleted.

Examples

var db = require('arangojs')();
db.dropFunction('ACME::ACCOUNTING::CALCULATE_VAT')
.then(() => {
    // the function no longer exists 
});

database.route([path,] [headers]): Route

Returns a new Route instance for the given path (relative to the database) that can be used to perform arbitrary HTTP requests.

Arguments

  • path: string (optional)

    The database-relative URL of the route.

  • headers: Object (optional)

    Default headers that should be sent with each request to the route.

If path is missing, the route will refer to the base URL of the database.

For more information on Route instances see the Route API below.

Examples

var db = require('arangojs')();
var myFoxxApp = db.route('my-foxx-app');
myFoxxApp.post('users', {
    username: 'admin',
    password: 'hunter2'
})
.then(response => {
    // response.body is the result of 
    // POST /_db/_system/my-foxx-app/users 
    // with JSON request body '{"username": "admin", "password": "hunter2"}' 
});

Cursor instances provide an abstraction over the HTTP API's limitations. Unless a method explicitly exhausts the cursor, the driver will only fetch as many batches from the server as necessary. Like the server-side cursors, Cursor instances are incrementally depleted as they are read from.

var db = require('arangojs')();
db.query('FOR x IN 1..100 RETURN x')
// query result list: [1, 2, 3, ..., 99, 100] 
.then(cursor => {
    cursor.next())
    .then(value => {
        value === 1;
        // remaining result list: [2, 3, 4, ..., 99, 100] 
    });
});

cursor.count: number

The total number of documents in the query result. This is only available if the count option was used.

async cursor.all(): Array<Object>

Exhausts the cursor, then returns an array containing all values in the cursor's remaining result list.

Examples

// query result list: [1, 2, 3, 4, 5] 
cursor.all()
.then(vals => {
    // vals is an array containing the entire query result 
    Array.isArray(vals);
    vals.length === 5;
    vals; // [1, 2, 3, 4, 5] 
    cursor.hasNext() === false;
});

async cursor.next(): Object

Advances the cursor and returns the next value in the cursor's remaining result list. If the cursor has already been exhausted, returns undefined instead.

Examples

// query result list: [1, 2, 3, 4, 5] 
cursor.next()
.then(val => {
    val === 1;
    // remaining result list: [2, 3, 4, 5] 
    return cursor.next();
})
.then(val2 => {
    val2 === 2;
    // remaining result list: [3, 4, 5] 
});

cursor.hasNext(): boolean

Returns true if the cursor has more values or false if the cursor has been exhausted.

Examples

cursor.all() // exhausts the cursor 
.then(() => {
    cursor.hasNext() === false;
});

async cursor.each(fn): any

Advances the cursor by applying the function fn to each value in the cursor's remaining result list until the cursor is exhausted or fn explicitly returns false.

Returns the last return value of fn.

Equivalent to Array.prototype.forEach (except async).

Arguments

  • fn: Function

    A function that will be invoked for each value in the cursor's remaining result list until it explicitly returns false or the cursor is exhausted.

    The function receives the following arguments:

    • value: any

      The value in the cursor's remaining result list.

    • index: number

      The index of the value in the cursor's remaining result list.

    • cursor: Cursor

      The cursor itself.

Examples

var results = [];
function doStuff(value) {
    var VALUE = value.toUpperCase();
    results.push(VALUE);
    return VALUE;
}
// query result list: ['a', 'b', 'c'] 
cursor.each(doStuff)
.then(last => {
    String(results) === 'A,B,C';
    cursor.hasNext() === false;
    last === 'C';
});

async cursor.every(fn): boolean

Advances the cursor by applying the function fn to each value in the cursor's remaining result list until the cursor is exhausted or fn returns a value that evaluates to false.

Returns false if fn returned a value that evalutes to false, or true otherwise.

Equivalent to Array.prototype.every (except async).

Arguments

  • fn: Function

    A function that will be invoked for each value in the cursor's remaining result list until it returns a value that evaluates to false or the cursor is exhausted.

    The function receives the following arguments:

    • value: any

      The value in the cursor's remaining result list.

    • index: number

      The index of the value in the cursor's remaining result list.

    • cursor: Cursor

      The cursor itself.

function even(value) {
    return value % 2 === 0;
}
// query result list: [0, 2, 4, 5, 6] 
cursor.every(even)
.then(result => {
    result === false; // 5 is not even 
    cursor.hasNext() === true;
    cursor.next()
    .then(value => {
        value === 6; // next value after 5 
    });
});

async cursor.some(fn): boolean

Advances the cursor by applying the function fn to each value in the cursor's remaining result list until the cursor is exhausted or fn returns a value that evaluates to true.

Returns true if fn returned a value that evalutes to true, or false otherwise.

Equivalent to Array.prototype.some (except async).

Examples

function even(value) {
    return value % 2 === 0;
}
// query result list: [1, 3, 4, 5] 
cursor.some(even)
.then(result => {
    result === true; // 4 is even 
    cursor.hasNext() === true;
    cursor.next()
    .then(value => {
        value === 5; // next value after 4 
    });
});

cursor.map(fn): Array<any>

Advances the cursor by applying the function fn to each value in the cursor's remaining result list until the cursor is exhausted.

Returns an array of the return values of fn.

Equivalent to Array.prototype.map (except async).

Arguments

  • fn: Function

    A function that will be invoked for each value in the cursor's remaining result list until the cursor is exhausted.

    The function receives the following arguments:

    • value: any

      The value in the cursor's remaining result list.

    • index: number

      The index of the value in the cursor's remaining result list.

    • cursor: Cursor

      The cursor itself.

Examples

function square(value) {
    return value * value;
}
// query result list: [1, 2, 3, 4, 5] 
cursor.map(square)
.then(result => {
    result.length === 5;
    result; // [1, 4, 9, 16, 25] 
    cursor.hasNext() === false;
});

cursor.reduce(fn, [accu]): any

Exhausts the cursor by reducing the values in the cursor's remaining result list with the given function fn. If accu is not provided, the first value in the cursor's remaining result list will be used instead (the function will not be invoked for that value).

Equivalent to Array.prototype.reduce (except async).

Arguments

  • fn: Function

    A function that will be invoked for each value in the cursor's remaining result list until the cursor is exhausted.

    The function receives the following arguments:

    • accu: any

      The return value of the previous call to fn. If this is the first call, accu will be set to the accu value passed to reduce or the first value in the cursor's remaining result list.

    • value: any

      The value in the cursor's remaining result list.

    • index: number

      The index of the value in the cursor's remaining result list.

    • cursor: Cursor

      The cursor itself.

Examples

function add(ab) {
    return a + b;
}
// query result list: [1, 2, 3, 4, 5] 
 
var baseline = 1000;
cursor.reduce(add, baseline)
.then(result => {
    result === (baseline + 1 + 2 + 3 + 4 + 5);
    cursor.hasNext() === false;
});
 
// -- or -- 
 
cursor.reduce(add)
.then(result => {
    result === (1 + 2 + 3 + 4 + 5);
    cursor.hasNext() === false;
});
 

Route instances provide access for arbitrary HTTP requests. This allows easy access to Foxx apps and other HTTP APIs not covered by the driver itself.

route.route([path], [headers]): Route

Returns a new Route instance for the given path (relative to the current route) that can be used to perform arbitrary HTTP requests.

Arguments

  • path: string (optional)

    The relative URL of the route.

  • headers: Object (optional)

    Default headers that should be sent with each request to the route.

If path is missing, the route will refer to the base URL of the database.

Examples

var db = require('arangojs')();
var route = db.route('my-foxx-app');
var users = route.route('users');
// equivalent to db.route('my-foxx-app/users') 

async route.get([path,] [qs]): Response

Performs a GET request to the given URL and returns the server response.

Arguments

  • path: string (optional)

    The route-relative URL for the request. If omitted, the request will be made to the base URL of the route.

  • qs: string (optional)

    The query string for the request. If qs is an object, it will be translated to a query string.

Examples

var db = require('arangojs')();
var route = db.route('my-foxx-app');
route.get()
.then(response => {
    // response.body is the response body of calling 
    // GET _db/_system/my-foxx-app 
});
 
// -- or -- 
 
route.get('users')
.then(response => {
    // response.body is the response body of calling 
    // GET _db/_system/my-foxx-app/users 
});
 
// -- or -- 
 
route.get('users', {group: 'admin'})
.then(response => {
    // response.body is the response body of calling 
    // GET _db/_system/my-foxx-app/users?group=admin 
});

async route.post([path,] [body, [qs]]): Response

Performs a POST request to the given URL and returns the server response.

Arguments

  • path: string (optional)

    The route-relative URL for the request. If omitted, the request will be made to the base URL of the route.

  • body: string (optional)

    The response body. If body is an object, it will be encoded as JSON.

  • qs: string (optional)

    The query string for the request. If qs is an object, it will be translated to a query string.

Examples

var db = require('arangojs')();
var route = db.route('my-foxx-app');
route.post()
.then(response => {
    // response.body is the response body of calling 
    // POST _db/_system/my-foxx-app 
});
 
// -- or -- 
 
route.post('users')
.then(response => {
    // response.body is the response body of calling 
    // POST _db/_system/my-foxx-app/users 
});
 
// -- or -- 
 
route.post('users', {
    username: 'admin',
    password: 'hunter2'
})
.then(response => {
    // response.body is the response body of calling 
    // POST _db/_system/my-foxx-app/users 
    // with JSON request body {"username": "admin", "password": "hunter2"} 
});
 
// -- or -- 
 
route.post('users', {
    username: 'admin',
    password: 'hunter2'
}, {admin: true})
.then(response => {
    // response.body is the response body of calling 
    // POST _db/_system/my-foxx-app/users?admin=true 
    // with JSON request body {"username": "admin", "password": "hunter2"} 
});

async route.put([path,] [body, [qs]]): Response

Performs a PUT request to the given URL and returns the server response.

Arguments

  • path: string (optional)

    The route-relative URL for the request. If omitted, the request will be made to the base URL of the route.

  • body: string (optional)

    The response body. If body is an object, it will be encoded as JSON.

  • qs: string (optional)

    The query string for the request. If qs is an object, it will be translated to a query string.

Examples

var db = require('arangojs')();
var route = db.route('my-foxx-app');
route.put()
.then(response => {
    // response.body is the response body of calling 
    // PUT _db/_system/my-foxx-app 
});
 
// -- or -- 
 
route.put('users/admin')
.then(response => {
    // response.body is the response body of calling 
    // PUT _db/_system/my-foxx-app/users 
});
 
// -- or -- 
 
route.put('users/admin', {
    username: 'admin',
    password: 'hunter2'
})
.then(response => {
    // response.body is the response body of calling 
    // PUT _db/_system/my-foxx-app/users/admin 
    // with JSON request body {"username": "admin", "password": "hunter2"} 
});
 
// -- or -- 
 
route.put('users/admin', {
    username: 'admin',
    password: 'hunter2'
}, {admin: true})
.then(response => {
    // response.body is the response body of calling 
    // PUT _db/_system/my-foxx-app/users/admin?admin=true 
    // with JSON request body {"username": "admin", "password": "hunter2"} 
});

async route.patch([path,] [body, [qs]]): Response

Performs a PATCH request to the given URL and returns the server response.

Arguments

  • path: string (optional)

    The route-relative URL for the request. If omitted, the request will be made to the base URL of the route.

  • body: string (optional)

    The response body. If body is an object, it will be encoded as JSON.

  • qs: string (optional)

    The query string for the request. If qs is an object, it will be translated to a query string.

Examples

var db = require('arangojs')();
var route = db.route('my-foxx-app');
route.patch()
.then(response => {
    // response.body is the response body of calling 
    // PATCH _db/_system/my-foxx-app 
});
 
// -- or -- 
 
route.patch('users/admin')
.then(response => {
    // response.body is the response body of calling 
    // PATCH _db/_system/my-foxx-app/users 
});
 
// -- or -- 
 
route.patch('users/admin', {
    password: 'hunter2'
})
.then(response => {
    // response.body is the response body of calling 
    // PATCH _db/_system/my-foxx-app/users/admin 
    // with JSON request body {"password": "hunter2"} 
});
 
// -- or -- 
 
route.patch('users/admin', {
    password: 'hunter2'
}, {admin: true})
.then(response => {
    // response.body is the response body of calling 
    // PATCH _db/_system/my-foxx-app/users/admin?admin=true 
    // with JSON request body {"password": "hunter2"} 
});

async route.delete([path,] [qs]): Response

Performs a DELETE request to the given URL and returns the server response.

Arguments

  • path: string (optional)

    The route-relative URL for the request. If omitted, the request will be made to the base URL of the route.

  • qs: string (optional)

    The query string for the request. If qs is an object, it will be translated to a query string.

Examples

var db = require('arangojs')();
var route = db.route('my-foxx-app');
route.delete()
.then(response => {
    // response.body is the response body of calling 
    // DELETE _db/_system/my-foxx-app 
});
 
// -- or -- 
 
route.delete('users/admin')
.then(response => {
    // response.body is the response body of calling 
    // DELETE _db/_system/my-foxx-app/users/admin 
});
 
// -- or -- 
 
route.delete('users/admin', {permanent: true})
.then(response => {
    // response.body is the response body of calling 
    // DELETE _db/_system/my-foxx-app/users/admin?permanent=true 
});

async route.head([path,] [qs]): Response

Performs a HEAD request to the given URL and returns the server response.

Arguments

  • path: string (optional)

    The route-relative URL for the request. If omitted, the request will be made to the base URL of the route.

  • qs: string (optional)

    The query string for the request. If qs is an object, it will be translated to a query string.

Examples

var db = require('arangojs')();
var route = db.route('my-foxx-app');
route.head()
.then(response => {
    // response is the response object for 
    // HEAD _db/_system/my-foxx-app 
});

async route.request([opts]): Response

Performs an arbitrary request to the given URL and returns the server response.

Arguments

  • opts: Object (optional)

    An object with any of the following properties:

    • path: string (optional)

      The route-relative URL for the request. If omitted, the request will be made to the base URL of the route.

    • absolutePath: boolean (Default: false)

      Whether the path is relative to the connection's base URL instead of the route.

    • body: string (optional)

      The response body. If body is an object, it will be encoded as JSON.

    • qs: string (optional)

      The query string for the request. If qs is an object, it will be translated to a query string.

    • headers: Object (optional)

      An object containing additional HTTP headers to be sent with the request.

    • method: string (Default: "GET")

      HTTP method of this request.

Examples

var db = require('arangojs')();
var route = db.route('my-foxx-app');
route.request({
    path: 'hello-world',
    method: 'POST',
    body: {hello: 'world'},
    qs: {admin: true}
})
.then(response => {
    // response.body is the response body of calling 
    // POST _db/_system/my-foxx-app/hello-world?admin=true 
    // with JSON request body '{"hello": "world"}' 
});

These functions implement the HTTP API for manipulating collections.

The Collection API is implemented by all Collection instances, regardless of their specific type. I.e. it represents a shared subset between instances of DocumentCollection, EdgeCollection, GraphVertexCollection and GraphEdgeCollection.

See the HTTP API documentation for details.

async collection.get(): Object

Retrieves general information about the collection.

Examples

var db = require('arangojs')();
var collection = db.collection('some-collection');
collection.get()
.then(data => {
    // data contains general information about the collection 
});

async collection.properties(): Object

Retrieves the collection's properties.

Examples

var db = require('arangojs')();
var collection = db.collection('some-collection');
collection.properties()
.then(data => {
    // data contains the collection's properties 
});

async collection.count(): Object

Retrieves information about the number of documents in a collection.

Examples

var db = require('arangojs')();
var collection = db.collection('some-collection');
collection.count()
.then(data => {
    // data contains the collection's count 
});

async collection.figures(): Object

Retrieves statistics for a collection.

Examples

var db = require('arangojs')();
var collection = db.collection('some-collection');
collection.figures()
.then(data => {
    // data contains the collection's figures 
});

async collection.revision(): Object

Retrieves the collection revision ID.

Examples

var db = require('arangojs')();
var collection = db.collection('some-collection');
collection.revision()
.then(data => {
    // data contains the collection's revision 
});

async collection.checksum([opts]): Object

Retrieves the collection checksum.

Arguments

Examples

var db = require('arangojs')();
var collection = db.collection('some-collection');
collection.checksum()
.then(data => {
    // data contains the collection's checksum 
});

These functions implement the HTTP API for modifying collections.

async collection.create([properties]): Object

Creates a collection with the given properties for this collection's name, then returns the server response.

Arguments

Examples

var db = require('arangojs')();
collection = db.collection('potatos');
collection.create()
.then(() => {
    // the document collection "potatos" now exists 
});
 
// -- or -- 
 
var collection = var collection = db.edgeCollection('friends');
collection.create({
    waitForSync: true // always sync document changes to disk 
})
.then(() => {
    // the edge collection "friends" now exists 
});

async collection.load([count]): Object

Tells the server to load the collection into memory.

Arguments

  • count: boolean (Default: true)

    If set to false, the return value will not include the number of documents in the collection (which may speed up the process).

Examples

var db = require('arangojs')();
var collection = db.collection('some-collection');
collection.load(false)
.then(() => {
    // the collection has now been loaded into memory 
});

async collection.unload(): Object

Tells the server to remove the collection from memory.

Examples

var db = require('arangojs')();
var collection = db.collection('some-collection');
collection.unload()
.then(() => {
    // the collection has now been unloaded from memory 
});

async collection.setProperties(properties): Object

Replaces the properties of the collection.

Arguments

Examples

var db = require('arangojs')();
var collection = db.collection('some-collection');
collection.setProperties({waitForSync: true})
.then(result => {
    result.waitForSync === true;
    // the collection will now wait for data being written to disk 
    // whenever a document is changed 
});

async collection.rename(name): Object

Renames the collection. The Collection instance will automatically update its name when the rename succeeds.

Examples

var db = require('arangojs')();
var collection = db.collection('some-collection');
collection.rename('new-collection-name')
.then(result => {
    result.name === 'new-collection-name';
    collection.name === result.name;
    // result contains additional information about the collection 
});

async collection.rotate(): Object

Rotates the journal of the collection.

Examples

var db = require('arangojs')();
var collection = db.collection('some-collection');
collection.rotate()
.then(data => {
    // data.result will be true if rotation succeeded 
});

async collection.truncate(): Object

Deletes all documents in the collection in the database.

Examples

var db = require('arangojs')();
var collection = db.collection('some-collection');
collection.truncate()
.then(() => {
    // the collection "some-collection" is now empty 
});

async collection.drop(): Object

Deletes the collection from the database.

Examples

var db = require('arangojs')();
var collection = db.collection('some-collection');
collection.drop()
.then(() => {
    // the collection "some-collection" no longer exists 
});

These functions implement the HTTP API for manipulating indexes.

async collection.createIndex(details): Object

Creates an arbitrary index on the collection.

Arguments

Examples

var db = require('arangojs')();
var collection = db.collection('some-collection');
collection.createIndex({type: 'cap', size: 20})
.then(index => {
    index.id; // the index's handle 
    // the index has been created 
});

async collection.createCapConstraint(size): Object

Creates a cap constraint index on the collection.

Arguments

  • size: Object

    An object with any of the following properties:

    • size: number (optional)

      The maximum number of documents in the collection.

    • byteSize: number (optional)

      The maximum size of active document data in the collection (in bytes).

If size is a number, it will be interpreted as size.size.

For more information on the properties of the size object see the HTTP API for creating cap constraints.

Examples

var db = require('arangojs')();
var collection = db.collection('some-collection');
 
collection.createCapCollection(20)
.then(index => {
    index.id; // the index's handle 
    index.size === 20;
    // the index has been created 
});
 
// -- or -- 
 
collection.createCapCollection({size: 20})
.then(index => {
    index.id; // the index's handle 
    index.size === 20;
    // the index has been created 
});

async collection.createHashIndex(fields, [opts]): Object

Creates a hash index on the collection.

Arguments

  • fields: Array<string>

    An array of names of document fields on which to create the index. If the value is a string, it will be wrapped in an array automatically.

  • opts: Object (optional)

    Additional options for this index. If the value is a boolean, it will be interpreted as opts.unique.

For more information on hash indexes, see the HTTP API for hash indexes.

Examples

var db = require('arangojs')();
var collection = db.collection('some-collection');
 
collection.createHashIndex('favorite-color')
.then(index => {
    index.id; // the index's handle 
    index.fields; // ['favorite-color'] 
    // the index has been created 
});
 
// -- or -- 
 
collection.createHashIndex(['favorite-color'])
.then(index => {
    index.id; // the index's handle 
    index.fields; // ['favorite-color'] 
    // the index has been created 
});

async collection.createSkipList(fields, [opts]): Object

Creates a skiplist index on the collection.

Arguments

  • fields: Array<string>

    An array of names of document fields on which to create the index. If the value is a string, it will be wrapped in an array automatically.

  • opts: Object (optional)

    Additional options for this index. If the value is a boolean, it will be interpreted as opts.unique.

For more information on skiplist indexes, see the HTTP API for skiplist indexes.

Examples

var db = require('arangojs')();
var collection = db.collection('some-collection');
 
collection.createSkipList('favorite-color')
.then(index => {
    index.id; // the index's handle 
    index.fields; // ['favorite-color'] 
    // the index has been created 
});
 
// -- or -- 
 
collection.createSkipList(['favorite-color'])
.then(index => {
    index.id; // the index's handle 
    index.fields; // ['favorite-color'] 
    // the index has been created 
});

async collection.createGeoIndex(fields, [opts]): Object

Creates a geo-spatial index on the collection.

Arguments

  • fields: Array<string>

    An array of names of document fields on which to create the index. Currently, geo indexes must cover exactly one field. If the value is a string, it will be wrapped in an array automatically.

  • opts: Object (optional)

    An object containing additional properties of the index.

For more information on the properties of the opts object see the HTTP API for manipulating geo indexes.

Examples

var db = require('arangojs')();
var collection = db.collection('some-collection');
 
collection.createGeoIndex(['longitude', 'latitude'])
.then(index => {
    index.id; // the index's handle 
    index.fields; // ['longitude', 'latitude'] 
    // the index has been created 
});
 
// -- or -- 
 
collection.createGeoIndex('location', {geoJson: true})
.then(index => {
    index.id; // the index's handle 
    index.fields; // ['location'] 
    // the index has been created 
});

async collection.createFulltextIndex(fields, [minLength]): Object

Creates a fulltext index on the collection.

Arguments

  • fields: Array<string>

    An array of names of document fields on which to create the index. Currently, fulltext indexes must cover exactly one field. If the value is a string, it will be wrapped in an array automatically.

  • minLength (optional):

    Minimum character length of words to index. Uses a server-specific default value if not specified.

For more information on fulltext indexes, see the HTTP API for fulltext indexes.

Examples

var db = require('arangojs')();
var collection = db.collection('some-collection');
 
collection.createFulltextIndex('description')
.then(index => {
    index.id; // the index's handle 
    index.fields; // ['description'] 
    // the index has been created 
});
 
// -- or -- 
 
collection.createFulltextIndex(['description'])
.then(index => {
    index.id; // the index's handle 
    index.fields; // ['description'] 
    // the index has been created 
});

async collection.index(indexHandle): Object

Fetches information about the index with the given indexHandle and returns it.

Arguments

  • indexHandle: string

    The handle of the index to look up. This can either be a fully-qualified identifier or the collection-specific key of the index. If the value is an object, its id property will be used instead.

Examples

var db = require('arangojs')();
var collection = db.collection('some-collection');
collection.createFulltextIndex('description')
.then(index => {
    collection.index(index.id)
    .then(result => {
        result.id === index.id;
        // result contains the properties of the index 
    });
 
    // -- or -- 
 
    collection.index(index.id.split('/')[1])
    .then(result => {
        result.id === index.id;
        // result contains the properties of the index 
    });
});

async collection.indexes(): Array<Object>

Fetches a list of all indexes on this collection.

Examples

var db = require('arangojs')();
var collection = db.collection('some-collection');
collection.createFulltextIndex('description')
.then(() => collection.indexes())
.then(indexes => {
    indexes.length === 1;
    // indexes contains information about the index 
});

async collection.dropIndex(indexHandle): Object

Deletes the index with the given indexHandle from the collection.

Arguments

  • indexHandle: string

    The handle of the index to delete. This can either be a fully-qualified identifier or the collection-specific key of the index. If the value is an object, its id property will be used instead.

Examples

var db = require('arangojs')();
var collection = db.collection('some-collection');
collection.createFulltextIndex('description')
.then(index => {
    collection.dropIndex(index.id)
    .then(() => {
        // the index has been removed from the collection 
    });
 
    // -- or -- 
 
    collection.dropIndex(index.id.split('/')[1])
    .then(() => {
        // the index has been removed from the collection 
    });
});

These functions implement the HTTP API for simple queries.

async collection.all([opts]): Cursor

Performs a query to fetch all documents in the collection. Returns a new Cursor instance for the query results.

Arguments

async collection.any(): Object

Fetches a document from the collection at random.

async collection.first([opts]): Array<Object>

Performs a query to fetch the first documents in the collection. Returns an array of the matching documents.

Arguments

async collection.last([opts]): Array<Object>

Performs a query to fetch the last documents in the collection. Returns an array of the matching documents.

Arguments

async collection.byExample(example, [opts]): Cursor

Performs a query to fetch all documents in the collection matching the given example. Returns a new Cursor instance for the query results.

Arguments

async collection.firstExample(example): Object

Fetches the first document in the collection matching the given example.

Arguments

  • example: Object

    An object representing an example for documents to be matched against.

async collection.removeByExample(example, [opts]): Object

Removes all documents in the collection matching the given example.

Arguments

async collection.replaceByExample(example, newValue, [opts]): Object

Replaces all documents in the collection matching the given example with the given newValue.

Arguments

  • example: Object

    An object representing an example for documents to be matched against.

  • newValue: Object

    The new value to replace matching documents with.

  • opts: Object (optional)

    For information on the possible options see the HTTP API for replacing documents by example.

async collection.updateByExample(example, newValue, [opts]): Object

Updates (patches) all documents in the collection matching the given example with the given newValue.

Arguments

  • example: Object

    An object representing an example for documents to be matched against.

  • newValue: Object

    The new value to update matching documents with.

  • opts: Object (optional)

    For information on the possible options see the HTTP API for updating documents by example.

async collection.lookupByKeys(keys): Array<Object>

Fetches the documents with the given keys from the collection. Returns an array of the matching documents.

Arguments

  • keys: Array

    An array of document keys to look up.

async collection.removeByKeys(keys, [opts]): Object

Deletes the documents with the given keys from the collection.

Arguments

async collection.fulltext(fieldName, query, [opts]): Cursor

Performs a fulltext query in the given fieldName on the collection.

Arguments

  • fieldName: String

    Name of the field to search on documents in the collection.

  • query: String

    Fulltext query string to search for.

  • opts: Object (optional)

    For information on the possible options see the HTTP API for fulltext queries.

This function implements the HTTP API for bulk imports.

async collection.import(data, [opts]): Object

Bulk imports the given data into the collection.

Arguments

  • data: Array<Array<any>> | Array<Object>

    The data to import. This can be an array of documents:

    [
      {key1: value1, key2: value2}, // document 1 
      {key1: value1, key2: value2}, // document 2 
      ...
    ]

    Or it can be an array of value arrays following an array of keys.

    [
      ['key1', 'key2'], // key names 
      [value1, value2], // document 1 
      [value1, value2], // document 2 
      ...
    ]
  • opts: Object (optional) If opts is set, it must be an object with any of the following properties:

    • waitForSync: boolean (Default: false)

      Wait until the documents have been synced to disk.

    • details: boolean (Default: false)

      Whether the response should contain additional details about documents that could not be imported.false*.

    • type: string (Default: "auto")

      Indicates which format the data uses. Can be "documents", "array" or "auto".

If data is a JavaScript array, it will be transmitted as a line-delimited JSON stream. If opts.type is set to "array", it will be transmitted as regular JSON instead. If data is a string, it will be transmitted as it is without any processing.

For more information on the opts object, see the HTTP API documentation for bulk imports.

Examples

var db = require('arangojs')();
var collection = db.collection('users');
 
collection.import(
    [// document stream 
        {username: 'admin', password: 'hunter2'},
        {username: 'jcd', password: 'bionicman'},
        {username: 'jreyes', password: 'amigo'},
        {username: 'ghermann', password: 'zeitgeist'}
    ]
)
.then(result => {
    result.created === 4;
});
 
// -- or -- 
 
collection.import(
    [// array stream with header 
        ['username', 'password'], // keys 
        ['admin', 'hunter2'], // row 1 
        ['jcd', 'bionicman'], // row 2 
        ['jreyes', 'amigo'],
        ['ghermann', 'zeitgeist']
    ]
)
.then(result => {
    result.created === 4;
});
 
// -- or -- 
 
collection.import(
    // raw line-delimited JSON array stream with header 
    '["username", "password"]\r\n' +
    '["admin", "hunter2"]\r\n' +
    '["jcd", "bionicman"]\r\n' +
    '["jreyes", "amigo"]\r\n' +
    '["ghermann", "zeitgeist"]\r\n'
)
.then(result => {
    result.created === 4;
});

These functions implement the HTTP API for manipulating documents.

async collection.replace(documentHandle, newValue, [opts]): Object

Replaces the content of the document with the given documentHandle with the gi