The JavaScript API is available on the server-side in the following contexts:

Running on the server-side means that the code runs directly inside of the arangod process, bypassing the HTTP API. In cluster deployments, the code is executed on a Coordinator.

The JavaScript API is also available in the ArangoDB Shell client tool:

It communicates with the server via the HTTP API.

The JavaScript API cannot be used in browsers, Node.js, or other JavaScript environments. You can use the arangojs driver instead. Note that it has a different interface.

Usage example

The key element for using the JavaScript API is the db object, which is available by default in arangosh and can be imported in server-side JavaScript code from the @arangodb module.

// Import the db object (only in server-side contexts)
let db = require("@arangodb").db;

The db object lets you access and manage databases, for example:

// Create a new database
db._useDatabase("_system");
db._createDatabase("myDB");

// Make it the current database
db._useDatabase("myDB");
print(`Database context: ${ db._name() }`);

You can also work with collections and Views using the db object. Accessing a collection returns a collection object and accessing a View returns a view object.

// Create a new collection. Returns a collection object
let coll = db._create("collection");

// Create a new arangosearch View. Returns a view object
let view = db._createView("view", "arangosearch", { links: { collection: { includeAllFields: true } } });

To obtain a reference to a collection or View again, you can use multiple ways:

coll = db._collection("collection");
view = db._view("view");
// or
coll = db.collection;
view = db.view;

You can create documents via a collection object. You can use arbitrary JavaScript code to generate data.

// Create single documents using both available methods.
// Returns an object with the document metadata (the _id, _key, and _rev attributes)
coll.save({ value: "foo" });
coll.insert({ value: "bar" });

// Create an array of objects and create multiple documents at once
let arr = [];
for (let i = 1; i < 100; i++) {
  arr.push({ value: i });
}
coll.save(arr);

Indexes can also be created via a collection object.

// Create an index for the collection
coll.ensureIndex({ type: "persistent", fields: ["value"] });

To query the data in the current database, use the db object. Executing an AQL query returns a cursor object.

// Run an AQL query. Returns a cursor object
let cursor = db._query(`FOR doc IN collection FILTER doc.value >= "bar" RETURN doc`);
cursor.toArray();

// Import the aql query helper (only in server-side contexts)
const aql = require("@arangodb").aql;

// Run an AQL query using the query helper to use variables as bind parameters
let limit = 5;
db._query(aql`FOR doc IN ${ coll } LIMIT ${ limit } RETURN doc`).toArray();

See the full reference documentation for the common objects returned by the @arangodb module for details:

JavaScript Modules

ArangoDB uses a Node.js-compatible module system. You can use the function require() in order to load a module or library. It returns the exported variables and functions of the module.

The following global variables are available in arangosh and all server-side JavaScript contexts in ArangoDB:

  • global
  • process
  • console
  • Buffer
  • __filename
  • __dirname

ArangoDB-specific modules

There is a large number of ArangoDB-specific modules using the @arangodb namespace. Some of these modules are for internal use by ArangoDB itself. You can use the following modules as an end-user:

Node-compatibility modules

ArangoDB supports a number of modules for compatibility with Node.js, including:

  • assert implements basic assertion and testing functions.

  • buffer implements a binary data type for JavaScript.

  • console is a well known logging facility to all the JavaScript developers. ArangoDB implements most of the Console API, with the exceptions of profile and count.

  • events implements an event emitter.

  • fs provides a file system API for the manipulation of paths, directories, files, links, and the construction of file streams. ArangoDB implements most Filesystem/A functions.

  • module provides direct access to the module system.

  • path implements functions dealing with filenames and paths.

  • punycode implements conversion functions for punycode encoding.

  • querystring provides utilities for dealing with query strings.

  • stream provides a streaming interface.

  • string_decoder implements logic for decoding buffers into strings.

  • url provides utilities for URL resolution and parsing.

  • util provides general utility functions like format and inspect.

Additionally ArangoDB provides partial implementations for the following modules:

  • net: only isIP, isIPv4 and isIPv6.

  • process: only env and cwd; stubs for argv, stdout.isTTY, stdout.write, nextTick.

  • timers: stubs for setImmediate, setTimeout, setInterval, clearImmediate, clearTimeout, clearInterval and ref.

  • tty: only isatty (always returns false).

  • vm: only runInThisContext.

The following Node.js modules are not available at all: