ArangoDB JavaScript driver
The official ArangoDB low-level JavaScript client.
Note: if you are looking for the ArangoDB JavaScript API in
Foxx (or the arangosh
interactive shell) please
check the
ArangoDB documentation
instead; specifically the db
object exported by the @arangodb
module. The
JavaScript driver is only meant to be used when accessing ArangoDB from
outside the database.
Compatibility
ArangoJS is compatible with ArangoDB 3.0 and later. For using ArangoJS with
2.8 or earlier see the upgrade note below. ArangoJS is tested against the two
most-recent releases of ArangoDB 3 (currently 3.0 and 3.1) as well as the most
recent version of 2.8 and the latest development version.
The yarn/npm distribution of ArangoJS is compatible with Node.js versions 7
(latest), 6 (LTS) and 4 (Maintenance). Node.js version support follows
the official Node.js long-term support schedule.
The bower distribution of ArangoJS is compatible with most modern browsers.
Versions outside this range may be compatible but are not actively supported.
Upgrade note: If you want to use arangojs with ArangoDB 2.8 or earlier
remember to set the appropriate arangoVersion
option (e.g. 20800
for version
2.8.0). The current default value is 30000
(indicating compatibility with
version 3.0.0 and newer). The driver will behave differently depending on this
value when using APIs that have changed between these versions.
Versions
The version number of this driver does not correspond with supported ArangoDB
versions!
This driver uses semantic versioning:
- A change in the bugfix version (e.g. X.Y.0 -> X.Y.1) indicates internal
changes and should always be safe to upgrade.
- A change in the minor version (e.g. X.1.Z -> X.2.0) indicates additions and
backwards-compatible changes that should not affect your code.
- A change in the major version (e.g. 1.Y.Z -> 2.0.0) indicates breaking
changes that require changes in your code to upgrade.
If you are getting weird errors or functions seem to be missing, make sure you
are using the latest version of the driver and following documentation written
for a compatible version. If you are following a tutorial written for an older
version of arangojs, you can install that version using the <name>@<version>
syntax:
yarn add arangojs@4
npm install --save arangojs@4
You can find the documentation for each version by clicking on the corresponding
date on the left in
the list of version tags.
Testing
Run the tests using the yarn test
or npm test
commands:
yarn test
npm test
By default the tests will be run against a server listening on
http://root:@localhost:8529
(i.e. using username root
with no password). To
override this, you can set the environment variable TEST_ARANGODB_URL
to
something different:
TEST_ARANGODB_URL=http://root:@myserver.local:8530 yarn test
TEST_ARANGODB_URL=http://root:@myserver.local:8530 npm test
Install
With Yarn, NPM or Bower
yarn add arangojs
npm install --save arangojs
bower install arangojs
From source
git clone https://github.com/arangodb/arangojs.git
cd arangojs
npm install
npm run dist
Basic usage example
import {Database, aql} from 'arangojs';
const db = new Database();
const now = Date.now();
try {
const cursor = await db.query(aql`RETURN ${now}`);
const result = await cursor.next();
} catch (err) {
}
var arangojs = require('arangojs');
var db = new arangojs.Database();
var now = Date.now();
db.query({
query: 'RETURN @arg0',
bindVars: {arg0: now}
}, function (err, cursor) {
if (err) {
} else {
cursor.next(function (err, result) {
})
}
});
const host = process.env.ARANGODB_HOST;
const port = process.env.ARANGODB_PORT;
const database = process.env.ARANGODB_DB;
const username = process.env.ARANGODB_USERNAME;
const password = process.env.ARANGODB_PASSWORD;
const db = new Database({
url: `http://${username}:${password}@${host}:${port}`,
databaseName: database
});
const db = new Database({
url: `http://${username}:${password}@${host}:${port}/_db/${database}`,
databaseName: false
});
const db = new Database(`http://${host}:${port}`);
db.useDatabase(database);
db.useBasicAuth(username, password);
const db = new Database({
arangoVersion: 20800
});
For AQL please check out the aql
template tag for writing parametrized
AQL queries without making your code vulnerable to injection attacks.
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 with an
errorNum as defined in the ArangoDB documentation.
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
try {
const info = await db.createDatabase('mydb');
} catch (err) {
console.error(err.stack);
}
db.createDatabase('mydb')
.then(
info => {
},
err => console.error(err.stack)
);
db.createDatabase('mydb', function (err, info) {
if (err) console.error(err.stack);
else {
}
});
Note: the examples in the remainder of this documentation use async/await
and other modern language features like multi-line strings and template tags.
When developing for an environment without support for these language features,
just use node-style callbacks or promises instead as in the above example.
Table of Contents
Database API
new Database
new Database([config]): Database
Creates a new Database instance.
If config is a string, it will be interpreted as config.url.
Arguments
Manipulating databases
These functions implement the
HTTP API for manipulating databases.
database.useDatabase
database.useDatabase(databaseName): this
Updates the Database instance and its connection string to use the given
databaseName, then returns itself.
Arguments
Examples
const db = new Database();
db.useDatabase("test");
database.useBasicAuth
database.useBasicAuth(username, password): this
Updates the Database instance's authorization
header to use Basic
authentication with the given username and password, then returns itself.
Arguments
-
username: string
(Default: "root"
)
The username to authenticate with.
-
password: string
(Default: ""
)
The password to authenticate with.
Examples
const db = new Database();
db.useDatabase("test");
db.useBasicAuth("admin", "hunter2");
database.useBearerAuth
database.useBearerAuth(token): this
Updates the Database instance's authorization
header to use Bearer
authentication with the given authentication token, then returns itself.
Arguments
Examples
const db = new Database();
db.useBearerAuth("keyboardcat");
database.createDatabase
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
const db = new Database();
const info = await db.createDatabase('mydb', [{username: 'root'}]);
database.get
async database.get(): Object
Fetches the database description for the active database from the server.
Examples
const db = new Database();
const info = await db.get();
database.listDatabases
async database.listDatabases(): Array<string>
Fetches all databases from the server and returns an array of their names.
Examples
const db = new Database();
const names = await db.listDatabases();
database.listUserDatabases
async database.listUserDatabases(): Array<string>
Fetches all databases accessible to the active user from the server and returns
an array of their names.
Examples
const db = new Database();
const names = await db.listUserDatabases();
database.dropDatabase
async database.dropDatabase(databaseName): Object
Deletes the database with the given databaseName from the server.
const db = new Database();
await db.dropDatabase('mydb');
database.truncate
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. Note that this option will be
ignored because truncating system collections is not supported anymore for
some system collections.
Examples
const db = new Database();
await db.truncate();
Accessing collections
These functions implement the
HTTP API for accessing collections.
database.collection
database.collection(collectionName): DocumentCollection
Returns a DocumentCollection instance for the given collection name.
Arguments
Examples
const db = new Database();
const collection = db.collection("potatos");
database.edgeCollection
database.edgeCollection(collectionName): EdgeCollection
Returns an EdgeCollection instance for the given collection name.
Arguments
Examples
const db = new Database();
const collection = db.edgeCollection("potatos");
database.listCollections
async database.listCollections([excludeSystem]): Array<Object>
Fetches all collections from the database and returns an array of collection
descriptions.
Arguments
Examples
const db = new Database();
const collections = await db.listCollections();
const collections = await db.listCollections(false);
database.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
Examples
const db = new Database();
const collections = await db.listCollections()
const collections = await db.listCollections(false)
Accessing graphs
These functions implement the
HTTP API for accessing general graphs.
database.graph
database.graph(graphName): Graph
Returns a Graph instance representing the graph with the given graph name.
database.listGraphs
async database.listGraphs(): Array<Object>
Fetches all graphs from the database and returns an array of graph descriptions.
Examples
const db = new Database();
const graphs = await db.listGraphs();
database.graphs
async database.graphs(): Array<Graph>
Fetches all graphs from the database and returns an array of Graph instances
for the graphs.
Examples
const db = new Database();
const graphs = await db.graphs();
Transactions
This function implements the
HTTP API for transactions.
database.transaction
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.
Note: For accessing the database from within ArangoDB, see
the documentation for the @arangodb
module in ArangoDB.
-
params: Object
(optional)
Available as variable params
when the action function is being executed on
server. Check the example below.
-
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
const db = new Database();
const action = String(function (params) {
const db = require('@arangodb').db;
return db._query(aql`
FOR user IN _users
FILTER user.age > ${params.age}
RETURN u.user
`).toArray();
});
const result = await db.transaction(
{read: '_users'},
action,
{age: 12}
);
Queries
This function implements the
HTTP API for single roundtrip AQL queries.
For collection-specific queries see simple queries.
database.query
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
const db = new Database();
const active = true;
const cursor = await db.query(aql`
FOR u IN _users
FILTER u.authData.active == ${active}
RETURN u.user
`);
db.query(
'FOR u IN _users ' +
'FILTER u.authData.active == @active ' +
'RETURN u.user',
{active: true}
).then(function (cursor) {
});
aql
aql(strings, ...args): Object
Template string handler (aka template tag) for AQL queries. Converts a template
string to an object that can be passed to database.query
by converting
arguments to bind variables.
Note: If you want to pass a collection name as a bind variable, you need to
pass a Collection instance (e.g. what you get by passing the collection name
to db.collection
) instead. If you see the error "array expected as operand to FOR loop"
, you're likely passing a collection name instead of a collection
instance.
Examples
const userCollection = db.collection("_users");
const role = "admin";
const query = aql`
FOR user IN ${userCollection}
FILTER user.role == ${role}
RETURN user
`;
const query = {
query: "FOR user IN @@value0 FILTER user.role == @value1 RETURN user",
bindVars: { "@value0": userCollection.name, value1: role }
};
Note how the aql template tag automatically handles collection references
(@@value0
instead of @value0
) for us so you don't have to worry about
counting at-symbols.
Because the aql template tag creates actual bindVars instead of inlining values
directly, it also avoids injection attacks via malicious parameters:
const email = '" || (FOR x IN secrets REMOVE x IN secrets) || "';
const query = `
FOR user IN users
FILTER user.email == "${email}"
RETURN user
`;
const query = aql`
FOR user IN users
FILTER user.email == ${email}
RETURN user
`;
Managing AQL user functions
These functions implement the
HTTP API for managing AQL user functions.
database.listFunctions
async database.listFunctions(): Array<Object>
Fetches a list of all AQL user functions registered with the database.
Examples
const db = new Database();
const functions = db.listFunctions();
database.createFunction
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
const db = new Database();
await db.createFunction(
'ACME::ACCOUNTING::CALCULATE_VAT',
String(function (price) {
return price * 0.19;
})
);
const cursor = await db.query(aql`
FOR product IN products
RETURN MERGE(
{vat: ACME::ACCOUNTING::CALCULATE_VAT(product.price)},
product
)
`);
database.dropFunction
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
const db = new Database();
await db.dropFunction('ACME::ACCOUNTING::CALCULATE_VAT');
Managing Foxx services
database.listServices
async database.listServices([excludeSystem]): Array<Object>
Fetches a list of all installed service.
Arguments
Examples
const services = await db.listServices();
const services = await db.listServices(false);
database.installService
async database.installService(mount, source, [options]): Object
Installs a new service.
Arguments
-
mount: string
The service's mount point, relative to the database.
-
source: Buffer | Readable | File | string
The service bundle to install.
-
options: Object
(optional)
An object with any of the following properties:
-
configuration: Object
(optional)
An object mapping configuration option names to values.
-
dependencies: Object
(optional)
An object mapping dependency aliases to mount points.
-
development: boolean
(Default: false
)
Whether the service should be installed in development mode.
-
legacy: boolean
(Default: false
)
Whether the service should be installed in legacy compatibility mode.
This overrides the engines
option in the service manifest (if any).
-
setup: boolean
(Default: true
)
Whether the setup script should be executed.
Examples
const source = fs.createReadStream('./my-foxx-service.zip');
const info = await db.installService('/hello', source);
const source = fs.readFileSync('./my-foxx-service.zip');
const info = await db.installService('/hello', source);
const element = document.getElementById('my-file-input');
const source = element.files[0];
const info = await db.installService('/hello', source);
database.replaceService
async database.replaceService(mount, source, [options]): Object
Replaces an existing service with a new service by completely removing the old
service and installing a new service at the same mount point.
Arguments
-
mount: string
The service's mount point, relative to the database.
-
source: Buffer | Readable | File | string
The service bundle to replace the existing service with.
-
options: Object
(optional)
An object with any of the following properties:
-
configuration: Object
(optional)
An object mapping configuration option names to values.
This configuration will replace the existing configuration.
-
dependencies: Object
(optional)
An object mapping dependency aliases to mount points.
These dependencies will replace the existing dependencies.
-
development: boolean
(Default: false
)
Whether the new service should be installed in development mode.
-
legacy: boolean
(Default: false
)
Whether the new service should be installed in legacy compatibility mode.
This overrides the engines
option in the service manifest (if any).
-
teardown: boolean
(Default: true
)
Whether the teardown script of the old service should be executed.
-
setup: boolean
(Default: true
)
Whether the setup script of the new service should be executed.
Examples
const source = fs.createReadStream('./my-foxx-service.zip');
const info = await db.replaceService('/hello', source);
const source = fs.readFileSync('./my-foxx-service.zip');
const info = await db.replaceService('/hello', source);
const element = document.getElementById('my-file-input');
const source = element.files[0];
const info = await db.replaceService('/hello', source);
database.upgradeService
async database.upgradeService(mount, source, [options]): Object
Replaces an existing service with a new service while retaining the old
service's configuration and dependencies.
Arguments
-
mount: string
The service's mount point, relative to the database.
-
source: Buffer | Readable | File | string
The service bundle to replace the existing service with.
-
options: Object
(optional)
An object with any of the following properties:
-
configuration: Object
(optional)
An object mapping configuration option names to values.
This configuration will be merged into the existing configuration.
-
dependencies: Object
(optional)
An object mapping dependency aliases to mount points.
These dependencies will be merged into the existing dependencies.
-
development: boolean
(Default: false
)
Whether the new service should be installed in development mode.
-
legacy: boolean
(Default: false
)
Whether the new service should be installed in legacy compatibility mode.
This overrides the engines
option in the service manifest (if any).
-
teardown: boolean
(Default: false
)
Whether the teardown script of the old service should be executed.
-
setup: boolean
(Default: true
)
Whether the setup script of the new service should be executed.
Examples
const source = fs.createReadStream('./my-foxx-service.zip');
const info = await db.upgradeService('/hello', source);
const source = fs.readFileSync('./my-foxx-service.zip');
const info = await db.upgradeService('/hello', source);
const element = document.getElementById('my-file-input');
const source = element.files[0];
const info = await db.upgradeService('/hello', source);
database.uninstallService
async database.uninstallService(mount, [options]): void
Completely removes a service from the database.
Arguments
-
mount: string
The service's mount point, relative to the database.
-
options: Object
(optional)
An object with any of the following properties:
Examples
await db.uninstallService('/my-service');
database.getService
async database.getService(mount): Object
Retrieves information about a mounted service.
Arguments
Examples
const info = await db.getService('/my-service');
database.getServiceConfiguration
async database.getServiceConfiguration(mount, [minimal]): Object
Retrieves an object with information about the service's configuration options
and their current values.
Arguments
-
mount: string
The service's mount point, relative to the database.
-
minimal: boolean
(Default: false
)
Only return the current values.
Examples
const config = await db.getServiceConfiguration('/my-service');
database.replaceServiceConfiguration
async database.replaceServiceConfiguration(mount, configuration, [minimal]): Object
Replaces the configuration of the given service.
Arguments
-
mount: string
The service's mount point, relative to the database.
-
configuration: Object
An object mapping configuration option names to values.
-
minimal: boolean
(Default: false
)
Only return the current values and warnings (if any).
Note: when using ArangoDB 3.2.8 or older, enabling this option avoids
triggering a second request to the database.
Examples
const config = {currency: 'USD', locale: 'en-US'};
const info = await db.replaceServiceConfiguration('/my-service', config);
database.updateServiceConfiguration
async database.updateServiceConfiguration(mount, configuration, [minimal]): Object
Updates the configuration of the given service my merging the new values into
the existing ones.
Arguments
-
mount: string
The service's mount point, relative to the database.
-
configuration: Object
An object mapping configuration option names to values.
-
minimal: boolean
(Default: false
)
Only return the current values and warnings (if any).
Note: when using ArangoDB 3.2.8 or older, enabling this option avoids
triggering a second request to the database.
Examples
const config = {locale: 'en-US'};
const info = await db.updateServiceConfiguration('/my-service', config);
database.getServiceDependencies
async database.getServiceDependencies(mount, [minimal]): Object
Retrieves an object with information about the service's dependencies and their
current mount points.
Arguments
-
mount: string
The service's mount point, relative to the database.
-
minimal: boolean
(Default: false
)
Only return the current values and warnings (if any).
Examples
const deps = await db.getServiceDependencies('/my-service');
database.replaceServiceDependencies
async database.replaceServiceDependencies(mount, dependencies, [minimal]): Object
Replaces the dependencies for the given service.
Arguments
-
mount: string
The service's mount point, relative to the database.
-
dependencies: Object
An object mapping dependency aliases to mount points.
-
minimal: boolean
(Default: false
)
Only return the current values and warnings (if any).
Note: when using ArangoDB 3.2.8 or older, enabling this option avoids
triggering a second request to the database.
Examples
const deps = {mailer: '/mailer-api', auth: '/remote-auth'};
const info = await db.replaceServiceDependencies('/my-service', deps);
database.updateServiceDependencies
async database.updateServiceDependencies(mount, dependencies, [minimal]): Object
Updates the dependencies for the given service by merging the new values into
the existing ones.
Arguments
-
mount: string
The service's mount point, relative to the database.
-
dependencies: Object
An object mapping dependency aliases to mount points.
-
minimal: boolean
(Default: false
)
Only return the current values and warnings (if any).
Note: when using ArangoDB 3.2.8 or older, enabling this option avoids
triggering a second request to the database.
Examples
const deps = {mailer: '/mailer-api'};
const info = await db.updateServiceDependencies('/my-service', deps);
database.enableServiceDevelopmentMode
async database.enableServiceDevelopmentMode(mount): Object
Enables development mode for the given service.
Arguments
Examples
const info = await db.enableServiceDevelopmentMode('/my-service');
database.disableServiceDevelopmentMode
async database.disableServiceDevelopmentMode(mount): Object
Disabled development mode for the given service and commits the service state to
the database.
Arguments
Examples
const info = await db.disableServiceDevelopmentMode('/my-service');
database.listServiceScripts
async database.listServiceScripts(mount): Object
Retrieves a list of the service's scripts.
Returns an object mapping each name to a more readable representation.
Arguments
Examples
const scripts = await db.listServiceScripts('/my-service');
database.runServiceScript
async database.runServiceScript(mount, name, [scriptArg]): any
Runs a service script and returns the result.
Arguments
-
mount: string
The service's mount point, relative to the database.
-
name: string
Name of the script to execute.
-
scriptArg: any
Value that will be passed as an argument to the script.
Examples
const result = await db.runServiceScript('/my-service', 'setup');
database.runServiceTests
async database.runServiceTests(mount, [reporter]): any
Runs the tests of a given service and returns a formatted report.
Arguments
-
mount: string
The service's mount point, relative to the database
-
options: Object
(optional)
An object with any of the following properties:
-
reporter: string
(Default: default
)
The reporter to use to process the test results.
As of ArangoDB 3.2 the following reporters are supported:
- stream: an array of event objects
- suite: nested suite objects with test results
- xunit: JSONML representation of an XUnit report
- tap: an array of TAP event strings
- default: an array of test results
-
idiomatic: boolean
(Default: false
)
Whether the results should be converted to the apropriate string
representation:
- xunit reports will be formatted as XML documents
- tap reports will be formatted as TAP streams
- stream reports will be formatted as JSON-LD streams
Examples
const opts = {reporter: 'xunit', idiomatic: true};
const result = await db.runServiceTests('/my-service', opts);
database.downloadService
async database.downloadService(mount): Buffer | Blob
Retrieves a zip bundle containing the service files.
Returns a Buffer
in Node or Blob
in the browser version.
Arguments
Examples
const bundle = await db.downloadService('/my-service');
database.getServiceReadme
async database.getServiceReadme(mount): string?
Retrieves the text content of the service's README
or README.md
file.
Returns undefined
if no such file could be found.
Arguments
Examples
const readme = await db.getServiceReadme('/my-service');
database.getServiceDocumentation
async database.getServiceDocumentation(mount): Object
Retrieves a Swagger API description object for the service installed at the
given mount point.
Arguments
Examples
const spec = await db.getServiceDocumentation('/my-service');
database.commitLocalServiceState
async database.commitLocalServiceState([replace]): void
Writes all locally available services to the database and updates any service
bundles missing in the database.
Arguments
-
replace: boolean
(Default: false
)
Also commit outdated services.
This can be used to solve some consistency problems when service bundles are
missing in the database or were deleted manually.
Examples
await db.commitLocalServiceState();
await db.commitLocalServiceState(true);
Arbitrary HTTP routes
database.route
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
const db = new Database();
const myFoxxService = db.route('my-foxx-service');
const response = await myFoxxService.post('users', {
username: 'admin',
password: 'hunter2'
});
Cursor API
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.
const db = new Database();
const cursor = await db.query('FOR x IN 1..5 RETURN x');
const value = await cursor.next();
assert.equal(value, 1);
cursor.count
cursor.count: number
The total number of documents in the query result. This is only available if the
count
option was used.
cursor.all
async cursor.all(): Array<Object>
Exhausts the cursor, then returns an array containing all values in the cursor's
remaining result list.
Examples
const cursor = await db._query('FOR x IN 1..5 RETURN x');
const result = await cursor.all()
assert.deepEqual(result, [1, 2, 3, 4, 5]);
assert.equal(cursor.hasNext(), false);
cursor.next
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
const val = await cursor.next();
assert.equal(val, 1);
const val2 = await cursor.next();
assert.equal(val2, 2);
cursor.hasNext
cursor.hasNext(): boolean
Returns true
if the cursor has more values or false
if the cursor has been
exhausted.
Examples
await cursor.all();
assert.equal(cursor.hasNext(), false);
cursor.each
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
Examples
const results = [];
function doStuff(value) {
const VALUE = value.toUpperCase();
results.push(VALUE);
return VALUE;
}
const cursor = await db.query('FOR x IN ["a", "b", "c"] RETURN x')
const last = await cursor.each(doStuff);
assert.deepEqual(results, ['A', 'B', 'C']);
assert.equal(cursor.hasNext(), false);
assert.equal(last, 'C');
cursor.every
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:
const even = value => value % 2 === 0;
const cursor = await db.query('FOR x IN 2..5 RETURN x');
const result = await cursor.every(even);
assert.equal(result, false);
assert.equal(cursor.hasNext(), true);
const value = await cursor.next();
assert.equal(value, 4);
cursor.some
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
const even = value => value % 2 === 0;
const cursor = await db.query('FOR x IN 1..5 RETURN x');
const result = await cursor.some(even);
assert.equal(result, true);
assert.equal(cursor.hasNext(), true);
const value = await cursor.next();
assert.equal(value, 3);
cursor.map
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).
Note: This creates an array of all return values. It is probably a bad idea
to do this for very large query result sets.
Arguments
Examples
const square = value => value * value;
const cursor = await db.query('FOR x IN 1..5 RETURN x');
const result = await cursor.map(square);
assert.equal(result.length, 5);
assert.deepEqual(result, [1, 4, 9, 16, 25]);
assert.equal(cursor.hasNext(), false);
cursor.reduce
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
Examples
const add = (a, b) => a + b;
const baseline = 1000;
const cursor = await db.query('FOR x IN 1..5 RETURN x');
const result = await cursor.reduce(add, baseline)
assert.equal(result, baseline + 1 + 2 + 3 + 4 + 5);
assert.equal(cursor.hasNext(), false);
const result = await cursor.reduce(add);
assert.equal(result, 1 + 2 + 3 + 4 + 5);
assert.equal(cursor.hasNext(), false);
Route API
Route instances provide access for arbitrary HTTP requests. This allows easy
access to Foxx services and other HTTP APIs not covered by the driver itself.
route.route
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
const db = new Database();
const route = db.route("my-foxx-service");
const users = route.route("users");
route.get
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
const db = new Database();
const route = db.route('my-foxx-service');
const response = await route.get();
const response = await route.get('users');
const response = await route.get('users', {group: 'admin'});
route.post
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
const db = new Database();
const route = db.route('my-foxx-service');
const response = await route.post()
const response = await route.post('users')
const response = await route.post('users', {
username: 'admin',
password: 'hunter2'
});
const response = await route.post('users', {
username: 'admin',
password: 'hunter2'
}, {admin: true});
route.put
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
const db = new Database();
const route = db.route('my-foxx-service');
const response = await route.put();
const response = await route.put('users/admin');
const response = await route.put('users/admin', {
username: 'admin',
password: 'hunter2'
});
const response = await route.put('users/admin', {
username: 'admin',
password: 'hunter2'
}, {admin: true});
route.patch
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
const db = new Database();
const route = db.route('my-foxx-service');
const response = await route.patch();
const response = await route.patch('users/admin');
const response = await route.patch('users/admin', {
password: 'hunter2'
});
const response = await route.patch('users/admin', {
password: 'hunter2'
}, {admin: true});
route.delete
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
const db = new Database();
const route = db.route('my-foxx-service');
const response = await route.delete()
const response = await route.delete('users/admin')
const response = await route.delete('users/admin', {permanent: true})
route.head
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
const db = new Database();
const route = db.route('my-foxx-service');
const response = await route.head();
route.request
async route.request([opts]): Response
Performs an arbitrary request to the given URL and returns the server response.
Arguments
Examples
const db = new Database();
const route = db.route('my-foxx-service');
const response = await route.request({
path: 'hello-world',
method: 'POST',
body: {hello: 'world'},
qs: {admin: true}
});
Collection API
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.
Getting information about the collection
See
the HTTP API documentation
for details.
collection.get
async collection.get(): Object
Retrieves general information about the collection.
Examples
const db = new Database();
const collection = db.collection('some-collection');
const data = await collection.get();
collection.properties
async collection.properties(): Object
Retrieves the collection's properties.
Examples
const db = new Database();
const collection = db.collection('some-collection');
const data = await collection.properties();
collection.count
async collection.count(): Object
Retrieves information about the number of documents in a collection.
Examples
const db = new Database();
const collection = db.collection('some-collection');
const data = await collection.count();
collection.figures
async collection.figures(): Object
Retrieves statistics for a collection.
Examples
const db = new Database();
const collection = db.collection('some-collection');
const data = await collection.figures();
collection.revision
async collection.revision(): Object
Retrieves the collection revision ID.
Examples
const db = new Database();
const collection = db.collection('some-collection');
const data = await collection.revision();
collection.checksum
async collection.checksum([opts]): Object
Retrieves the collection checksum.
Arguments
Examples
const db = new Database();
const collection = db.collection('some-collection');
const data = await collection.checksum();
Manipulating the collection
These functions implement
the HTTP API for modifying collections.
collection.create
async collection.create([properties]): Object
Creates a collection with the given properties for this collection's name,
then returns the server response.
Arguments
Examples
const db = new Database();
const collection = db.collection('potatos');
await collection.create()
const collection = db.edgeCollection('friends');
await collection.create({
waitForSync: true
});
collection.load
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
const db = new Database();
const collection = db.collection('some-collection');
await collection.load(false)
collection.unload
async collection.unload(): Object
Tells the server to remove the collection from memory.
Examples
const db = new Database();
const collection = db.collection('some-collection');
await collection.unload()
collection.setProperties
async collection.setProperties(properties): Object
Replaces the properties of the collection.
Arguments
Examples
const db = new Database();
const collection = db.collection('some-collection');
const result = await collection.setProperties({waitForSync: true})
assert.equal(result.waitForSync, true);
collection.rename
async collection.rename(name): Object
Renames the collection. The Collection instance will automatically update its
name when the rename succeeds.
Examples
const db = new Database();
const collection = db.collection('some-collection');
const result = await collection.rename('new-collection-name')
assert.equal(result.name, 'new-collection-name');
assert.equal(collection.name, result.name);
collection.rotate
async collection.rotate(): Object
Rotates the journal of the collection.
Examples
const db = new Database();
const collection = db.collection('some-collection');
const data = await collection.rotate();
collection.truncate
async collection.truncate(): Object
Deletes all documents in the collection in the database.
Examples
const db = new Database();
const collection = db.collection('some-collection');
await collection.truncate();
collection.drop
async collection.drop([properties]): Object
Deletes the collection from the database.
Arguments
-
properties: Object
(optional)
An object with the following properties:
-
isSystem: Boolean
(Default: false
)
Whether the collection should be dropped even if it is a system collection.
This parameter must be set to true
when dropping a system collection.
For more information on the properties object, see
the HTTP API documentation for dropping collections.
Examples
const db = new Database();
const collection = db.collection('some-collection');
await collection.drop();
Manipulating indexes
These functions implement the
HTTP API for manipulating indexes.
collection.createIndex
async collection.createIndex(details): Object
Creates an arbitrary index on the collection.
Arguments
Examples
const db = new Database();
const collection = db.collection('some-collection');
const index = await collection.createIndex({type: 'cap', size: 20});
collection.createCapConstraint
async collection.createCapConstraint(size): Object
Creates a cap constraint index on the collection.
Note: This method is not available when using the driver with ArangoDB 3.0
and higher as cap constraints are no longer supported.
Arguments
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
const db = new Database();
const collection = db.collection('some-collection');
const index = await collection.createCapConstraint(20)
assert.equal(index.size, 20);
const index = await collection.createCapConstraint({size: 20})
assert.equal(index.size, 20);
collection.createHashIndex
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
const db = new Database();
const collection = db.collection('some-collection');
const index = await collection.createHashIndex('favorite-color');
assert.deepEqual(index.fields, ['favorite-color']);
const index = await collection.createHashIndex(['favorite-color']);
assert.deepEqual(index.fields, ['favorite-color']);
collection.createSkipList
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
const db = new Database();
const collection = db.collection('some-collection');
const index = await collection.createSkipList('favorite-color')
assert.deepEqual(index.fields, ['favorite-color']);
const index = await collection.createSkipList(['favorite-color'])
assert.deepEqual(index.fields, ['favorite-color']);
collection.createGeoIndex
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
const db = new Database();
const collection = db.collection('some-collection');
const index = await collection.createGeoIndex(['latitude', 'longitude']);
assert.deepEqual(index.fields, ['longitude', 'latitude']);
const index = await collection.createGeoIndex('location', {geoJson: true});
assert.deepEqual(index.fields, ['location']);
collection.createFulltextIndex
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
const db = new Database();
const collection = db.collection('some-collection');
const index = await collection.createFulltextIndex('description');
assert.deepEqual(index.fields, ['description']);
const index = await collection.createFulltextIndex(['description']);
assert.deepEqual(index.fields, ['description']);
collection.createPersistentIndex
async collection.createPersistentIndex(fields, [opts]): Object
Creates a Persistent index on the collection. Persistent indexes are similarly
in operation to skiplist indexes, only that these indexes are in disk as opposed
to in memory. This reduces memory usage and DB startup time, with the trade-off
being that it will always be orders of magnitude slower than in-memory indexes.
Arguments
For more information on the properties of the opts object see
the HTTP API for manipulating Persistent indexes.
Examples
const db = new Database();
const collection = db.collection('some-collection');
const index = await collection.createPersistentIndex(['name', 'email']);
assert.deepEqual(index.fields, ['name', 'email']);
collection.index
async collection.index(indexHandle): Object
Fetches information about the index with the given indexHandle and returns it.
Arguments
Examples
const db = new Database();
const collection = db.collection('some-collection');
const index = await collection.createFulltextIndex('description');
const result = await collection.index(index.id);
assert.equal(result.id, index.id);
const result = await collection.index(index.id.split('/')[1]);
assert.equal(result.id, index.id);
collection.indexes
async collection.indexes(): Array<Object>
Fetches a list of all indexes on this collection.
Examples
const db = new Database();
const collection = db.collection('some-collection');
await collection.createFulltextIndex('description')
const indexes = await collection.indexes();
assert.equal(indexes.length, 1);
collection.dropIndex
async collection.dropIndex(indexHandle): Object
Deletes the index with the given indexHandle from the collection.
Arguments
Examples
const db = new Database();
const collection = db.collection('some-collection');
const index = await collection.createFulltextIndex('description');
await collection.dropIndex(index.id);
await collection.dropIndex(index.id.split('/')[1]);
Simple queries
These functions implement the
HTTP API for simple queries.
collection.all
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
collection.any
async collection.any(): Object
Fetches a document from the collection at random.
collection.first
async collection.first([opts]): Array<Object>
Performs a query to fetch the first documents in the collection. Returns an
array of the matching documents.
Note: This method is not available when using the driver with ArangoDB 3.0
and higher as the corresponding API method has been removed.
Arguments
collection.last
async collection.last([opts]): Array<Object>
Performs a query to fetch the last documents in the collection. Returns an array
of the matching documents.
Note: This method is not available when using the driver with ArangoDB 3.0
and higher as the corresponding API method has been removed.
Arguments
collection.byExample
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
collection.firstExample
async collection.firstExample(example): Object
Fetches the first document in the collection matching the given example.
Arguments
collection.removeByExample
async collection.removeByExample(example, [opts]): Object
Removes all documents in the collection matching the given example.
Arguments
collection.replaceByExample
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.
collection.updateByExample
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.
collection.lookupByKeys
async collection.lookupByKeys(keys): Array<Object>
Fetches the documents with the given keys from the collection. Returns an
array of the matching documents.
Arguments
collection.removeByKeys
async collection.removeByKeys(keys, [opts]): Object
Deletes the documents with the given keys from the collection.
Arguments
collection.fulltext
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.
Bulk importing documents
This function implements the
HTTP API for bulk imports.
collection.import
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},
{key1: value1, key2: value2},
...
]
Or it can be an array of value arrays following an array of keys.
[
['key1', 'key2'],
[value1, value2],
[value1, value2],
...
]
-
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
const db = new Database();
const collection = db.collection('users');
const result = await collection.import([
{username: 'admin', password: 'hunter2'},
{username: 'jcd', password: 'bionicman'},
{username: 'jreyes', password: 'amigo'},
{username: 'ghermann', password: 'zeitgeist'}
]);
assert.equal(result.created, 4);
const result = await collection.import([
['username', 'password'],
['admin', 'hunter2'],
['jcd', 'bionicman'],
['jreyes', 'amigo'],
['ghermann', 'zeitgeist']
]);
assert.equal(result.created, 4);
const result = await collection.import([
'["username", "password"]',
'["admin", "hunter2"]',
'["jcd", "bionicman"]',
'["jreyes", "amigo"]',
'["ghermann", "zeitgeist"]'
].join('\r\n') + '\r\n');
assert.equal(result.created, 4);
Manipulating documents
These functions implement the
HTTP API for manipulating documents.
collection.replace
async collection.replace(documentHandle, newValue, [opts]): Object
Replaces the content of the document with the given documentHandle with the
given newValue and returns an object containing the document's metadata.
Note: The policy option is not available when using the driver with
ArangoDB 3.0 as it is redundant when specifying the rev option.
Arguments
-
documentHandle: string
The handle of the document to replace. This can either be the _id
or the
_key
of a document in the collection, or a document (i.e. an object with an
_id
or _key
property).
-
newValue: Object
The new data of the document.
-
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 document has been synced to disk. Default: false
.
-
rev: string
(optional)
Only replace the document if it matches this revision.
-
policy: string
(optional)
Determines the behaviour when the revision is not matched:
- if policy is set to
"last"
, the document will be replaced regardless
of the revision. - if policy is set to
"error"
or not set, the replacement will fail with
an error.
If a string is passed instead of an options object, it will be interpreted as
the rev option.
For more information on the opts object, see
the HTTP API documentation for working with documents.
Examples
const db = new Database();
const collection = db.collection('some-collection');
const doc = {number: 1, hello: 'world'};
const doc1 = await collection.save(doc);
const doc2 = await collection.replace(doc1, {number: 2});
assert.equal(doc2._id, doc1._id);
assert.notEqual(doc2._rev, doc1._rev);
const doc3 = await collection.document(doc1);
assert.equal(doc3._id, doc1._id);
assert.equal(doc3._rev, doc2._rev);
assert.equal(doc3.number, 2);
assert.equal(doc3.hello, undefined);
collection.update
async collection.update(documentHandle, newValue, [opts]): Object
Updates (merges) the content of the document with the given documentHandle
with the given newValue and returns an object containing the document's
metadata.
Note: The policy option is not available when using the driver with
ArangoDB 3.0 as it is redundant when specifying the rev option.
Arguments
-
documentHandle: string
Handle of the document to update. This can be either the _id
or the _key
of a document in the collection, or a document (i.e. an object with an _id
or _key
property).
-
newValue: Object
The new data of the document.
-
opts: Object
(optional)
If opts is set, it must be an object with any of the following properties:
-
waitForSync: boolean
(Default: false
)
Wait until document has been synced to disk.
-
keepNull: boolean
(Default: true
)
If set to false
, properties with a value of null
indicate that a
property should be deleted.
-
mergeObjects: boolean
(Default: true
)
If set to false
, object properties that already exist in the old document
will be overwritten rather than merged. This does not affect arrays.
-
rev: string
(optional)
Only update the document if it matches this revision.
-
policy: string
(optional)
Determines the behaviour when the revision is not matched:
- if policy is set to
"last"
, the document will be replaced regardless
of the revision. - if policy is set to
"error"
or not set, the replacement will fail with
an error.
If a string is passed instead of an options object, it will be interpreted as
the rev option.
For more information on the opts object, see
the HTTP API documentation for working with documents.
Examples
const db = new Database();
const collection = db.collection('some-collection');
const doc = {number: 1, hello: 'world'};
const doc1 = await collection.save(doc);
const doc2 = await collection.update(doc1, {number: 2});
assert.equal(doc2._id, doc1._id);
assert.notEqual(doc2._rev, doc1._rev);
const doc3 = await collection.document(doc2);
assert.equal(doc3._id, doc2._id);
assert.equal(doc3._rev, doc2._rev);
assert.equal(doc3.number, 2);
assert.equal(doc3.hello, doc.hello);
collection.bulkUpdate
async collection.bulkUpdate(documents, [opts]): Object
Updates (merges) the content of the documents with the given documents and
returns an array containing the documents' metadata.
Note: This method is new in 3.0 and is available when using the driver with
ArangoDB 3.0 and higher.
Arguments
-
documents: Array<Object>
Documents to update. Each object must have either the _id
or the _key
property.
-
opts: Object
(optional)
If opts is set, it must be an object with any of the following properties:
-
waitForSync: boolean
(Default: false
)
Wait until document has been synced to disk.
-
keepNull: boolean
(Default: true
)
If set to false
, properties with a value of null
indicate that a
property should be deleted.
-
mergeObjects: boolean
(Default: true
)
If set to false
, object properties that already exist in the old document
will be overwritten rather than merged. This does not affect arrays.
-
returnOld: boolean
(Default: false
)
If set to false
, return additionally the complete previous revision of the
changed documents under the attribute old
in the result.
-
returnNew: boolean
(Default: false
)
If set to false
, return additionally the complete new documents under the
attribute new
in the result.
-
ignoreRevs: boolean
(Default: true
)
By default, or if this is set to true, the _rev attributes in the given
documents are ignored. If this is set to false, then any _rev attribute
given in a body document is taken as a precondition. The document is only
updated if the current revision is the one specified.
For more information on the opts object, see
the HTTP API documentation for working with documents.
Examples
const db = new Database();
const collection = db.collection('some-collection');
const doc1 = {number: 1, hello: 'world1'};
const info1 = await collection.save(doc1);
const doc2 = {number: 2, hello: 'world2'};
const info2 = await collection.save(doc2);
const result = await collection.bulkUpdate([
{_key: info1._key, number: 3},
{_key: info2._key, number: 4}
], {returnNew: true})
collection.remove
async collection.remove(documentHandle, [opts]): Object
Deletes the document with the given documentHandle from the collection.
Note: The policy option is not available when using the driver with
ArangoDB 3.0 as it is redundant when specifying the rev option.
Arguments
-
documentHandle: string
The handle of the document to delete. This can be either the _id
or the
_key
of a document in the collection, or a document (i.e. an object with an
_id
or _key
property).
-
opts: Object
(optional)
If opts is set, it must be an object with any of the following properties:
-
waitForSync: boolean
(Default: false
)
Wait until document has been synced to disk.
-
rev: string
(optional)
Only update the document if it matches this revision.
-
policy: string
(optional)
Determines the behaviour when the revision is not matched:
- if policy is set to
"last"
, the document will be replaced regardless
of the revision. - if policy is set to
"error"
or not set, the replacement will fail with
an error.
If a string is passed instead of an options object, it will be interpreted as
the rev option.
For more information on the opts object, see
the HTTP API documentation for working with documents.
Examples
const db = new Database();
const collection = db.collection('some-collection');
await collection.remove('some-doc');
await collection.remove('some-collection/some-doc');
collection.list
async collection.list([type]): Array<string>
Retrieves a list of references for all documents in the collection.
Arguments
DocumentCollection API
The DocumentCollection API extends the
Collection API (see above) with the following methods.
documentCollection.document
async documentCollection.document(documentHandle): Object
Retrieves the document with the given documentHandle from the collection.
Arguments
Examples
const db = new Database();
const collection = db.collection('my-docs');
try {
const doc = await collection.document('some-key');
assert.equal(doc._key, 'some-key');
assert.equal(doc._id, 'my-docs/some-key');
} catch (err) {
}
try {
const doc = await collection.document('my-docs/some-key');
assert.equal(doc._key, 'some-key');
assert.equal(doc._id, 'my-docs/some-key');
} catch (err) {
}
documentCollection.save
async documentCollection.save(data, [opts]): Object
Creates a new document with the given data and returns an object containing
the document's metadata.
Arguments
-
data: Object
The data of the new document, may include a _key
.
-
opts: Object
(optional)
If opts is set, it must be an object with any of the following properties:
-
waitForSync: boolean
(Default: false
)
Wait until document has been synced to disk.
-
returnNew: boolean
(Default: false
)
If set to true
, return additionally the complete new documents under the
attribute new
in the result.
-
silent: boolean
(Default: false
)
If set to true, an empty object will be returned as response. No meta-data
will be returned for the created document. This option can be used to save
some network traffic.
If a boolean is passed instead of an options object, it will be interpreted as
the returnNew option.
For more information on the opts object, see
the HTTP API documentation for working with documents.
Examples
const db = new Database();
const collection = db.collection('my-docs');
const data = {some: 'data'};
const info = await collection.save(data);
assert.equal(info._id, 'my-docs/' + info._key);
const doc2 = await collection.document(info)
assert.equal(doc2._id, info._id);
assert.equal(doc2._rev, info._rev);
assert.equal(doc2.some, data.some);
const db = new Database();
const collection = db.collection('my-docs');
const data = {some: 'data'};
const opts = {returnNew: true};
const doc = await collection.save(data, opts)
assert.equal(doc1._id, 'my-docs/' + doc1._key);
assert.equal(doc1.new.some, data.some);
EdgeCollection API
The EdgeCollection API extends the
Collection API (see above) with the following methods.
edgeCollection.edge
async edgeCollection.edge(documentHandle): Object
Retrieves the edge with the given documentHandle from the collection.
Arguments
Examples
const db = new Database();
const collection = db.edgeCollection('edges');
const edge = await collection.edge('some-key');
assert.equal(edge._key, 'some-key');
assert.equal(edge._id, 'edges/some-key');
const edge = await collection.edge('edges/some-key');
assert.equal(edge._key, 'some-key');
assert.equal(edge._id, 'edges/some-key');
edgeCollection.save
async edgeCollection.save(data, [fromId, toId]): Object
Creates a new edge between the documents fromId and toId with the given
data and returns an object containing the edge's metadata.
Arguments
-
data: Object
The data of the new edge. If fromId and toId are not specified, the data
needs to contain the properties _from and _to.
-
fromId: string
(optional)
The handle of the start vertex of this edge. This can be either the _id
of a
document in the database, the _key
of an edge in the collection, or a
document (i.e. an object with an _id
or _key
property).
-
toId: string
(optional)
The handle of the end vertex of this edge. This can be either the _id
of a
document in the database, the _key
of an edge in the collection, or a
document (i.e. an object with an _id
or _key
property).
Examples
const db = new Database();
const collection = db.edgeCollection('edges');
const data = {some: 'data'};
const info = await collection.save(
data,
'vertices/start-vertex',
'vertices/end-vertex'
);
assert.equal(info._id, 'edges/' + info._key);
const edge = await collection.edge(edge)
assert.equal(edge._key, info._key);
assert.equal(edge._rev, info._rev);
assert.equal(edge.some, data.some);
assert.equal(edge._from, 'vertices/start-vertex');
assert.equal(edge._to, 'vertices/end-vertex');
const info = await collection.save({
some: 'data',
_from: 'verticies/start-vertex',
_to: 'vertices/end-vertex'
});
edgeCollection.edges
async edgeCollection.edges(documentHandle): Array<Object>
Retrieves a list of all edges of the document with the given documentHandle.
Arguments
-
documentHandle: string
The handle of the document to retrieve the edges of. This can be either the
_id
of a document in the database, the _key
of an edge in the collection,
or a document (i.e. an object with an _id
or _key
property).
Examples
const db = new Database();
const collection = db.edgeCollection('edges');
await collection.import([
['_key', '_from', '_to'],
['x', 'vertices/a', 'vertices/b'],
['y', 'vertices/a', 'vertices/c'],
['z', 'vertices/d', 'vertices/a']
])
const edges = await collection.edges('vertices/a');
assert.equal(edges.length, 3);
assert.deepEqual(edges.map(edge => edge._key), ['x', 'y', 'z']);
edgeCollection.inEdges
async edgeCollection.inEdges(documentHandle): Array<Object>
Retrieves a list of all incoming edges of the document with the given
documentHandle.
Arguments
-
documentHandle: string
The handle of the document to retrieve the edges of. This can be either the
_id
of a document in the database, the _key
of an edge in the collection,
or a document (i.e. an object with an _id
or _key
property).
Examples
const db = new Database();
const collection = db.edgeCollection('edges');
await collection.import([
['_key', '_from', '_to'],
['x', 'vertices/a', 'vertices/b'],
['y', 'vertices/a', 'vertices/c'],
['z', 'vertices/d', 'vertices/a']
]);
const edges = await collection.inEdges('vertices/a');
assert.equal(edges.length, 1);
assert.equal(edges[0]._key, 'z');
edgeCollection.outEdges
async edgeCollection.outEdges(documentHandle): Array<Object>
Retrieves a list of all outgoing edges of the document with the given
documentHandle.
Arguments
-
documentHandle: string
The handle of the document to retrieve the edges of. This can be either the
_id
of a document in the database, the _key
of an edge in the collection,
or a document (i.e. an object with an _id
or _key
property).
Examples
const db = new Database();
const collection = db.edgeCollection('edges');
await collection.import([
['_key', '_from', '_to'],
['x', 'vertices/a', 'vertices/b'],
['y', 'vertices/a', 'vertices/c'],
['z', 'vertices/d', 'vertices/a']
]);
const edges = await collection.outEdges('vertices/a');
assert.equal(edges.length, 2);
assert.deepEqual(edges.map(edge => edge._key), ['x', 'y']);
edgeCollection.traversal
async edgeCollection.traversal(startVertex, opts): Object
Performs a traversal starting from the given startVertex and following edges
contained in this edge collection.
Arguments
-
startVertex: string
The handle of the start vertex. This can be either the _id
of a document in
the database, the _key
of an edge in the collection, or a document (i.e. an
object with an _id
or _key
property).
-
opts: Object
See
the HTTP API documentation
for details on the additional arguments.
Please note that while opts.filter, opts.visitor, opts.init,
opts.expander and opts.sort should be strings evaluating to well-formed
JavaScript code, it's not possible to pass in JavaScript functions directly
because the code needs to be evaluated on the server and will be transmitted
in plain text.
Examples
const db = new Database();
const collection = db.edgeCollection('edges');
await collection.import([
['_key', '_from', '_to'],
['x', 'vertices/a', 'vertices/b'],
['y', 'vertices/b', 'vertices/c'],
['z', 'vertices/c', 'vertices/d']
]);
const result = await collection.traversal('vertices/a', {
direction: 'outbound',
visitor: 'result.vertices.push(vertex._key);',
init: 'result.vertices = [];'
});
assert.deepEqual(result.vertices, ['a', 'b', 'c', 'd']);
Graph API
These functions implement the
HTTP API for manipulating graphs.
graph.get
async graph.get(): Object
Retrieves general information about the graph.
Examples
const db = new Database();
const graph = db.graph('some-graph');
const data = await graph.get();
graph.create
async graph.create(properties): Object
Creates a graph with the given properties for this graph's name, then returns
the server response.
Arguments
Examples
const db = new Database();
const graph = db.graph('some-graph');
const info = await graph.create({
edgeDefinitions: [{
collection: 'edges',
from: ['start-vertices'],
to: ['end-vertices']
}]
});
graph.drop
async graph.drop([dropCollections]): Object
Deletes the graph from the database.
Arguments
-
dropCollections: boolean
(optional)
If set to true
, the collections associated with the graph will also be
deleted.
Examples
const db = new Database();
const graph = db.graph('some-graph');
await graph.drop();
Manipulating vertices
graph.vertexCollection
graph.vertexCollection(collectionName): GraphVertexCollection
Returns a new GraphVertexCollection instance
with the given name for this graph.
Arguments
Examples
const db = new Database();
const graph = db.graph("some-graph");
const collection = graph.vertexCollection("vertices");
assert.equal(collection.name, "vertices");
graph.addVertexCollection
async graph.addVertexCollection(collectionName): Object
Adds the collection with the given collectionName to the graph's vertex
collections.
Arguments
Examples
const db = new Database();
const graph = db.graph('some-graph');
await graph.addVertexCollection('vertices');
graph.removeVertexCollection
async graph.removeVertexCollection(collectionName, [dropCollection]): Object
Removes the vertex collection with the given collectionName from the graph.
Arguments
-
collectionName: string
Name of the vertex collection to remove from the graph.
-
dropCollection: boolean
(optional)
If set to true
, the collection will also be deleted from the database.
Examples
const db = new Database();
const graph = db.graph('some-graph');
await graph.removeVertexCollection('vertices')
await graph.removeVertexCollection('vertices', true)
Manipulating edges
graph.edgeCollection
graph.edgeCollection(collectionName): GraphEdgeCollection
Returns a new GraphEdgeCollection instance with
the given name bound to this graph.
Arguments
Examples
const db = new Database();
const graph = db.graph("some-graph");
const collection = graph.edgeCollection("edges");
assert.equal(collection.name, "edges");
graph.addEdgeDefinition
async graph.addEdgeDefinition(definition): Object
Adds the given edge definition definition to the graph.
Arguments
Examples
const db = new Database();
const graph = db.graph('some-graph');
await graph.addEdgeDefinition({
collection: 'edges',
from: ['vertices'],
to: ['vertices']
});
graph.replaceEdgeDefinition
async graph.replaceEdgeDefinition(collectionName, definition): Object
Replaces the edge definition for the edge collection named collectionName with
the given definition.
Arguments
Examples
const db = new Database();
const graph = db.graph('some-graph');
await graph.replaceEdgeDefinition('edges', {
collection: 'edges',
from: ['vertices'],
to: ['more-vertices']
});
graph.removeEdgeDefinition
async graph.removeEdgeDefinition(definitionName, [dropCollection]): Object
Removes the edge definition with the given definitionName form the graph.
Arguments
-
definitionName: string
Name of the edge definition to remove from the graph.
-
dropCollection: boolean
(optional)
If set to true
, the edge collection associated with the definition will also
be deleted from the database.
Examples
const db = new Database();
const graph = db.graph('some-graph');
await graph.removeEdgeDefinition('edges')
await graph.removeEdgeDefinition('edges', true)
graph.traversal
async graph.traversal(startVertex, opts): Object
Performs a traversal starting from the given startVertex and following edges
contained in any of the edge collections of this graph.
Arguments
-
startVertex: string
The handle of the start vertex. This can be either the _id
of a document in
the graph or a document (i.e. an object with an _id
property).
-
opts: Object
See
the HTTP API documentation
for details on the additional arguments.
Please note that while opts.filter, opts.visitor, opts.init,
opts.expander and opts.sort should be strings evaluating to well-formed
JavaScript functions, it's not possible to pass in JavaScript functions
directly because the functions need to be evaluated on the server and will be
transmitted in plain text.
Examples
const db = new Database();
const graph = db.graph('some-graph');
const collection = graph.edgeCollection('edges');
await collection.import([
['_key', '_from', '_to'],
['x', 'vertices/a', 'vertices/b'],
['y', 'vertices/b', 'vertices/c'],
['z', 'vertices/c', 'vertices/d']
])
const result = await graph.traversal('vertices/a', {
direction: 'outbound',
visitor: 'result.vertices.push(vertex._key);',
init: 'result.vertices = [];'
});
assert.deepEqual(result.vertices, ['a', 'b', 'c', 'd']);
GraphVertexCollection API
The GraphVertexCollection API extends the
Collection API (see above) with the following methods.
graphVertexCollection.remove
async graphVertexCollection.remove(documentHandle): Object
Deletes the vertex with the given documentHandle from the collection.
Arguments
Examples
const graph = db.graph('some-graph');
const collection = graph.vertexCollection('vertices');
await collection.remove('some-key')
await collection.remove('vertices/some-key')
graphVertexCollection.vertex
async graphVertexCollection.vertex(documentHandle): Object
Retrieves the vertex with the given documentHandle from the collection.
Arguments
Examples
const graph = db.graph('some-graph');
const collection = graph.vertexCollection('vertices');
const doc = await collection.vertex('some-key');
assert.equal(doc._key, 'some-key');
assert.equal(doc._id, 'vertices/some-key');
const doc = await collection.vertex('vertices/some-key');
assert.equal(doc._key, 'some-key');
assert.equal(doc._id, 'vertices/some-key');
graphVertexCollection.save
async graphVertexCollection.save(data): Object
Creates a new vertex with the given data.
Arguments
-
data: Object
The data of the vertex.
Examples
const db = new Database();
const graph = db.graph('some-graph');
const collection = graph.vertexCollection('vertices');
const doc = await collection.save({some: 'data'});
assert.equal(doc._id, 'vertices/' + doc._key);
assert.equal(doc.some, 'data');
GraphEdgeCollection API
The GraphEdgeCollection API extends the Collection API (see above) with the
following methods.
graphEdgeCollection.remove
async graphEdgeCollection.remove(documentHandle): Object
Deletes the edge with the given documentHandle from the collection.
Arguments
Examples
const graph = db.graph('some-graph');
const collection = graph.edgeCollection('edges');
await collection.remove('some-key')
await collection.remove('edges/some-key')
graphEdgeCollection.edge
async graphEdgeCollection.edge(documentHandle): Object
Retrieves the edge with the given documentHandle from the collection.
Arguments
Examples
const graph = db.graph('some-graph');
const collection = graph.edgeCollection('edges');
const edge = await collection.edge('some-key');
assert.equal(edge._key, 'some-key');
assert.equal(edge._id, 'edges/some-key');
const edge = await collection.edge('edges/some-key');
assert.equal(edge._key, 'some-key');
assert.equal(edge._id, 'edges/some-key');
graphEdgeCollection.save
async graphEdgeCollection.save(data, [fromId, toId]): Object
Creates a new edge between the vertices fromId and toId with the given
data.
Arguments
-
data: Object
The data of the new edge. If fromId and toId are not specified, the data
needs to contain the properties _from and _to.
-
fromId: string
(optional)
The handle of the start vertex of this edge. This can be either the _id
of a
document in the database, the _key
of an edge in the collection, or a
document (i.e. an object with an _id
or _key
property).
-
toId: string
(optional)
The handle of the end vertex of this edge. This can be either the _id
of a
document in the database, the _key
of an edge in the collection, or a
document (i.e. an object with an _id
or _key
property).
Examples
const db = new Database();
const graph = db.graph('some-graph');
const collection = graph.edgeCollection('edges');
const edge = await collection.save(
{some: 'data'},
'vertices/start-vertex',
'vertices/end-vertex'
);
assert.equal(edge._id, 'edges/' + edge._key);
assert.equal(edge.some, 'data');
assert.equal(edge._from, 'vertices/start-vertex');
assert.equal(edge._to, 'vertices/end-vertex');
graphEdgeCollection.edges
async graphEdgeCollection.edges(documentHandle): Array<Object>
Retrieves a list of all edges of the document with the given documentHandle.
Arguments
-
documentHandle: string
The handle of the document to retrieve the edges of. This can be either the
_id
of a document in the database, the _key
of an edge in the collection,
or a document (i.e. an object with an _id
or _key
property).
Examples
const db = new Database();
const graph = db.graph('some-graph');
const collection = graph.edgeCollection('edges');
await collection.import([
['_key', '_from', '_to'],
['x', 'vertices/a', 'vertices/b'],
['y', 'vertices/a', 'vertices/c'],
['z', 'vertices/d', 'vertices/a']
]);
const edges = await collection.edges('vertices/a');
assert.equal(edges.length, 3);
assert.deepEqual(edges.map(edge => edge._key), ['x', 'y', 'z']);
graphEdgeCollection.inEdges
async graphEdgeCollection.inEdges(documentHandle): Array<Object>
Retrieves a list of all incoming edges of the document with the given
documentHandle.
Arguments
-
documentHandle: string
The handle of the document to retrieve the edges of. This can be either the
_id
of a document in the database, the _key
of an edge in the collection,
or a document (i.e. an object with an _id
or _key
property).
Examples
const db = new Database();
const graph = db.graph('some-graph');
const collection = graph.edgeCollection('edges');
await collection.import([
['_key', '_from', '_to'],
['x', 'vertices/a', 'vertices/b'],
['y', 'vertices/a', 'vertices/c'],
['z', 'vertices/d', 'vertices/a']
]);
const edges = await collection.inEdges('vertices/a');
assert.equal(edges.length, 1);
assert.equal(edges[0]._key, 'z');
graphEdgeCollection.outEdges
async graphEdgeCollection.outEdges(documentHandle): Array<Object>
Retrieves a list of all outgoing edges of the document with the given
documentHandle.
Arguments
-
documentHandle: string
The handle of the document to retrieve the edges of. This can be either the
_id
of a document in the database, the _key
of an edge in the collection,
or a document (i.e. an object with an _id
or _key
property).
Examples
const db = new Database();
const graph = db.graph('some-graph');
const collection = graph.edgeCollection('edges');
await collection.import([
['_key', '_from', '_to'],
['x', 'vertices/a', 'vertices/b'],
['y', 'vertices/a', 'vertices/c'],
['z', 'vertices/d', 'vertices/a']
]);
const edges = await collection.outEdges('vertices/a');
assert.equal(edges.length, 2);
assert.deepEqual(edges.map(edge => edge._key), ['x', 'y']);
graphEdgeCollection.traversal
async graphEdgeCollection.traversal(startVertex, opts): Object
Performs a traversal starting from the given startVertex and following edges
contained in this edge collection.
Arguments
-
startVertex: string
The handle of the start vertex. This can be either the _id
of a document in
the database, the _key
of an edge in the collection, or a document (i.e. an
object with an _id
or _key
property).
-
opts: Object
See
the HTTP API documentation
for details on the additional arguments.
Please note that while opts.filter, opts.visitor, opts.init,
opts.expander and opts.sort should be strings evaluating to well-formed
JavaScript code, it's not possible to pass in JavaScript functions directly
because the code needs to be evaluated on the server and will be transmitted
in plain text.
Examples
const db = new Database();
const graph = db.graph('some-graph');
const collection = graph.edgeCollection('edges');
await collection.import([
['_key', '_from', '_to'],
['x', 'vertices/a', 'vertices/b'],
['y', 'vertices/b', 'vertices/c'],
['z', 'vertices/c', 'vertices/d']
]);
const result = await collection.traversal('vertices/a', {
direction: 'outbound',
visitor: 'result.vertices.push(vertex._key);',
init: 'result.vertices = [];'
});
assert.deepEqual(result.vertices, ['a', 'b', 'c', 'd']);
License
The Apache License, Version 2.0. For more information, see the accompanying
LICENSE file.