The official ArangoDB low-level JavaScript clients.
npm install arangojsgit clone https://github.com/arangodb/arangojs.git
cd arangojs
npm install
npm run distAll asynchronous functions take an optional node-style callback (or "errback") 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.
As of version 3.5, if the global Promise constructor is defined when an asynchronous function is called, the function will also return a promise. When using both node-style callbacks and promises, the node-style callback will be invoked before the promise's fulfillment/rejection handlers.
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.
The type annotations in this documentation generally follow the definitions used in the Flow type checker with the following additions:
- optional arguments or groups of optional arguments that can be omitted entirely are surrounded by square brackets, e.g.
[these: A, are: B, optional: C]. - the following type definitions are used throughout the documentation:
type Callback = (err: ?Error, result: ?any) => anytype Document = { _key: string, _id: ?string, _rev: ?string, [attr: string]: any }type Index = { id: string, [attr: string]: any }type Promise<T> = { then: (onFulfilled: (T) => A, onRejected: (Error) => B) => Promise<A | B>, [attr: string]: any }- the type of the
resultargument passed to callbacks is always identical to the type of the equivalent promise'sonFulfilledargument and is therefore not explicitly specified in the type signatures. I.e. if the return type is specified asPromise<X>the exact callback type is implied to be(err: ?Error, result: ?X) => any.
new Database([config: Object]): Database
Synchronous. Creates a new database.
Parameter
- config (optional): an object with the following properties:
- url (optional): base URL of the ArangoDB server. Default:
http://localhost:8529. - databaseName (optional): name of the active database. Default:
_system. - arangoVersion (optional): value of the
x-arango-versionheader. Default:20300. - headers (optional): an object with headers to send with every request.
- agent (optional): an http Agent instance to use for connections. This has no effect in the browser. Default: a new
http.Agentinstance configured with the agentOptions. - agentOptions (optional): an object with options for the agent. This will be ignored if agent is also provided and has no effect in the browser. Default:
{maxSockets: 3, keepAlive: true, keepAliveMsecs: 1000}. - promise (optional): the
Promiseimplementation to use orfalseto disable promises entirely (for performance). Default: the globalPromiseconstructor will be used if available when a promise is needed.
If config is a string, it will be interpreted as config.url.
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')]
}If you want to use ArangoDB with HTTP Basic authentication, you can provide the credentials as part of the config.url string, e.g. http://user:pass@localhost:8529.
These functions implement the HTTP API for manipulating collections.
database.createCollection(properties: Object, [callback: Callback]): Promise<DocumentCollection | EdgeCollection>
Creates a collection from the given properties, then passes a new Collection instance to the callback.
For more information on the properties object, see the HTTP API documentation for creating collections.
If properties is a string, it will be interpreted as properties.name.
Examples
var db = require('arangojs')();
db.createCollection('my-data', function (err, collection) {
if (err) return console.error(err);
// collection is a DocumentCollection instance
// see the Collection API and DocumentCollection API below for details
});
// -- or --
db.createCollection({
name: 'my-data',
type: 2 // i.e. document collection (the default)
}, function (err, collection) {
if (err) return console.error(err);
// collection is a DocumentCollection instance
// see the Collection API and DocumentCollection API below for details
});database.createEdgeCollection(properties: Object, [callback: Callback]): Promise<EdgeCollection>
Creates an edge collection from the given properties, then passes a new EdgeCollection instance to the callback.
For more information on the properties object, see the HTTP API documentation for creating collections.
If properties is a string, it will be interpreted as properties.name.
The collection type will be set to 3 (i.e. edge collection) regardless of the value of properties.type.
Examples
var db = require('arangojs')();
db.createEdgeCollection('friends', function (err, edgeCollection) {
if (err) return console.error(err);
// edgeCollection is an EdgeCollection instance
// see the Collection API and EdgeCollection API below for details
});database.collection(collectionName: string, [autoCreate: boolean,] [callback: Callback]): Promise<DocumentCollection | EdgeCollection>
Fetches the collection with the given collectionName from the database, then passes a new Collection instance to the callback.
If autoCreate is set to true, a collection with the given name will be created if it doesn't already exist.
var db = require('arangojs')();
db.collection('potatos', function (err, collection) {
if (err) {
// Collection did not exist
console.error(err);
return;
}
// collection exists
});database.edgeCollection(collectionName: string, [autoCreate: boolean,] [callback: Callback]): Promise<EdgeCollection>
Fetches the edge collection with the given collectionName from the database, then passes a new EdgeCollection instance to the callback.
If autoCreate is set to true, an edge collection with the given name will be created if it doesn't already exist.
If a collection with the given name exists but isn't an edge collection, an apropriate error will be passed instead.
var db = require('arangojs')();
db.edgeCollection('potatos', function (err, collection) {
if (err) {
// Collection did not exist
console.error(err);
return;
}
// collection exists
});database.collections([callback: Callback]): Promise<Array<Collection>>
Fetches all non-system collections from the database and passes an array of new Collection instances to the callback.
Examples
var db = require('arangojs')();
db.collections(function (err, collections) {
if (err) return console.error(err);
// collections is an array of Collection instances
// not including system collections
});database.allCollections([callback: Callback]): Promise<Array<Collection>>
Fetches all collections (including system collections) from the database and passes an array of new Collection instances to the callback.
Examples
var db = require('arangojs')();
db.allCollections(function (err, collections) {
if (err) return console.error(err);
// collections is an array of Collection instances
// including system collections
});database.dropCollection(collectionName: string, [callback: Callback]): Promise<any>
Deletes the collection with the given collectionName from the database.
Examples
var db = require('arangojs')();
db.dropCollection('friends', function (err) {
if (err) return console.error(err);
// collection "friends" no longer exists
});database.truncate([callback: Callback]): Promise<any>
Deletes all documents in all non-system collections in the active database.
Examples
var db = require('arangojs')();
db.truncate(function (err) {
if (err) return console.error(err);
// all non-system collections in this database are now empty
});database.truncateAll([callback: Callback]): Promise<any>
Deletes all documents in all collections (including system collections) in the active database.
Examples
var db = require('arangojs')();
db.truncateAll(function (err) {
if (err) return console.error(err);
// all collections (including system collections) in this db are now empty
// "I've made a huge mistake..."
});These functions implement the HTTP API for manipulating general graphs.
database.createGraph(properties: Object, [callback: Callback]): Promise<Graph>
Creates a graph with the given properties, then passes a new Graph instance to the callback.
For more information on the properties object, see the HTTP API documentation for creating graphs.
Examples
var db = require('arangojs')();
// this assumes collections `edges`, `start-vertices` and `end-vertices` exist
db.createGraph({
name: 'some-graph',
edgeDefinitions: [
{
collection: 'edges',
from: [
'start-vertices'
],
to: [
'end-vertices'
]
}
]
}, function (err, graph) {
if (err) return console.error(err);
// graph is a Graph instance
// for more information see the Graph API below
});database.graph(graphName: string, [autoCreate: boolean,] [callback: Callback]): Promise<Graph>
Fetches the graph with the given graphName from the database, then passes a new Graph instance to the callback.
If autoCreate is set to true, a graph with the given name will be created if it doesn't already exist.
Examples
var db = require('arangojs')();
db.graph('some-graph', function (err, graph) {
if (err) return console.error(err);
// graph exists
});database.graphs([callback: Callback]): Promise<Array<Graph>>
Fetches all graphs from the database and passes an array of new Graph instances to the callback.
Examples
var db = require('arangojs')();
db.graphs(function (err, graphs) {
if (err) return console.error(err);
// graphs is an array of Graph instances
});database.dropGraph(graphName: string, [dropCollections: boolean,] [callback: Callback]): Promise<any>
Deletes the graph with the given graphName from the database.
If dropCollections is set to true, the collections associated with the graphs will also be deleted.
Examples
var db = require('arangojs')();
db.dropGraph('some-graph', function (err) {
if (err) return console.error(err);
// graph "some-graph" no longer exists
});These functions implement the HTTP API for manipulating databases.
database.createDatabase(databaseName: string, [users: Array<Object>], [callback: Callback]): Promise<Database>
Creates a new database with the given databaseName, then passes a new Database instance to the callback.
If users is specified, it must be an array of objects with the following attributes:
- username: the username of the user to create for the database.
- passwd (optional): the password of the user. Default: empty.
- active (optional): whether the user is active. Default:
true. - extra (optional): an object containing additional user data.
Examples
var db = require('arangojs')();
db.createDatabase('mydb', [{username: 'root'}], function (err, database) {
if (err) return console.error(err);
// database is a Database instance
});database.database(databaseName: string, [autoCreate: boolean,] [callback: Callback]): Promise<Database>
Fetches the database with the given databaseName from the server, then passes a new Database instance to the callback.
If autoCreate is set to true, a database with the given name will be created if it doesn't already exist.
Examples
var db = require('arangojs')();
db.database('mydb', function (err, database) {
if (err) return console.error(err);
// mydb exists
});database.databases([callback: Callback]): Promise<Array<Database>>
Fetches all databases from the server and passes an array of new Database instances to the callback.
Examples
var db = require('arangojs')();
db.databases(function (err, databases) {
if (err) return console.error(err);
// databases is an array of Database instances
});database.dropDatabase(databaseName: string, [callback: Callback]): Promise<any>
Deletes the database with the given databaseName from the server.
var db = require('arangojs')();
db.dropDatabase('mydb', function (err) {
if (err) return console.error(err);
// database "mydb" no longer exists
})This function implements the HTTP API for transactions.
database.transaction(collections: Object | Array<string> | string, action: string, [params: Array<any>,] [lockTimeout: number,] [callback: Callback]): Promise<any>
Performs a server-side transaction and passes the action's return value to the callback.
Parameter
- collections: an object with the following properties:
- read: an array of names (or a single name) of collections that will be read from during the transaction.
- write: an array of names (or a single name) of collections that will be written to or read from during the transaction.
- action: a string evaluating to a JavaScript function to be executed on the server.
- params (optional): parameters that will be passed to the function.
- lockTimeout (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 used 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 collections = {read: '_users'};
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();
});
db.transaction(collections, action, function (err, result) {
if (err) return console.error(err);
// result contains the return value of the action
});This function implements the HTTP API for AQL queries.
For collection-specific queries see fulltext queries and geo-spatial queries.
database.query(query: string | QueryBuilder, [bindVars: Object,] [callback: Callback]): Promise<Cursor>
Performs a database query using the given query and bindVars, then passes a new Cursor instance for the result list to the callback.
Parameter
- query: an AQL query string or a query builder instance.
- bindVars (optional): an object with the variables to bind the query to.
For more information on Cursor instances see the Cursor API below.
Examples
var qb = require('aqb');
var db = require('arangojs')();
db.query(
qb.for('u').in('_users')
.filter(qb.eq('u.authData.active', '@active'))
.return('u.user'),
{active: true},
function (err, cursor) {
if (err) return console.error(err);
// cursor is a cursor for the query result
}
);
// -- or --
db.query(
'FOR u IN _users FILTER u.authData.active == @active RETURN u.user',
{active: true},
function (err, cursor) {
if (err) return console.error(err);
// cursor is a cursor for the query result
}
);These functions implement the HTTP API for managing AQL user functions.
database.createFunction(name: string, code: string, [callback: Callback]): Promise<any>
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.
Parameter
- name: a valid AQL function name, e.g.:
"myfuncs::accounting::calculate_vat". - code: a string evaluating to a JavaScript function (not a JavaScript function object).
Examples
var qb = require('aqb');
var db = require('arangojs')();
var vat_fn_name = 'myfuncs::acounting::calculate_vat';
var vat_fn_code = string(function (price) {
return price * 0.19;
});
db.createFunction(vat_fn_name, vat_fn_code, function (err) {
if (err) return console.error(err);
// Use the new function in an AQL query with the query builder:
db.query(
qb.for('product').in('products')
.return(qb.MERGE(
{
vat: qb.fn(vat_fn_name)('product.price')
},
'product'
)),
function (err, result) {
// ...
}
);
});database.functions([callback: Callback]): Promise<Array<Object>>
Fetches a list of all AQL user functions registered with the database.
Examples
var db = require('arangojs')();
db.functions(function (err, functions) {
if (err) return console.error(err);
// functions is a list of function definitions
})database.dropFunction(name: string, [group: boolean,] [callback: Callback]): Promise<any>
Deletes the AQL user function with the given name from the database.
Parameter
- name: the name of the user function to drop.
- group (optional): 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. Default:false.
Examples
var db = require('arangojs')();
db.dropFunction('myfuncs::acounting::calculate_vat', function (err) {
if (err) return console.error(err);
// the function no longer exists
});database.route([path: string, [headers: Object]]): Route
Synchronous. Returns a new Route instance for the given path (relative to the database) that can be used to perform arbitrary HTTP requests.
Parameter
- path (optional): relative URL of the route.
- headers (optional): default headers that should be send 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'
}, function (err, result) {
if (err) return console.error(err);
// result 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. Unlike the server-side cursors, Cursor instances can also be rewinded.
var db = require('arangojs')();
db.query(someQuery, function (err, cursor) {
if (err) return console.error(err);
// cursor represents the query results
});cursor.all([callback: Callback]): Promise<Array<any>>
Rewinds and exhausts the cursor and passes an array containing all values returned by the query.
Examples
// query result: [1, 2, 3, 4, 5]
cursor.all(function (err, vals) {
if (err) return console.error(err);
// vals is an array containing the entire query result
vals.length === 5;
vals; // [1, 2, 3, 4, 5]
cursor.hasNext() === false;
});cursor.next([callback: Callback]): Promise<any>
Advances the cursor and passes the next value returned by the query. If the cursor has already been exhausted, passes undefined instead.
Examples
// query result: [1, 2, 3, 4, 5]
cursor.next(function (err, val) {
if (err) return console.error(err);
val === 1;
cursor.next(function (err, val2) {
if (err) return console.error(err);
val2 === 2;
});
});cursor.hasNext(): boolean
Synchronous. Returns true if the cursor has more values or false if the cursor has been exhausted. Synchronous.
Examples
cursor.all(function (err) { // exhausts the cursor
if (err) return console.error(err);
cursor.hasNext() === false;
});cursor.each(fn: (value: any, index: number, cursor: Cursor) => any, [callback: Callback]): Promise<void>
Rewinds and exhausts the cursor by applying the function fn to each value returned by the query, then invokes the callback with no result value.
Equivalent to Array.prototype.forEach.
var counter = 0;
function count() {
counter += 1;
return counter;
}
// query result: [1, 2, 3, 4, 5]
cursor.each(count, function (err, result) {
if (err) return console.error(err);
counter === result;
result === 5;
cursor.hasNext() === false;
});cursor.every(fn: (value: any, index: number, cursor: Cursor) => boolean, [callback: Callback]): Promise<boolean>
Rewinds and advances the cursor by applying the function fn to each value returned by the query until the cursor is exhausted or fn returns a value that evaluates to false.
Passes the return value of the last call to fn to the callback.
Equivalent to Array.prototype.every.
function even(value) {
return value % 2 === 0;
}
// query result: [0, 2, 4, 5, 6]
cursor.every(even, function (err, result) {
if (err) return console.error(err);
result === false; // 5 is not even
cursor.hasNext() === true;
cursor.next(function (err, value) {
if (err) return console.error(err);
value === 6; // next value after 5
});
});cursor.some(fn: (value: any, index: number, cursor: Cursor) => boolean, [callback: Callback]): Promise<boolean>
Rewinds and advances the cursor by applying the function fn to each value returned by the query until the cursor is exhausted or fn returns a value that evaluates to true.
Passes the return value of the last call to fn to the callback.
Equivalent to Array.prototype.some.
Examples
function even(value) {
return value % 2 === 0;
}
// query result: [1, 3, 4, 5]
cursor.some(even, function (err, result) {
if (err) return console.error(err);
result === true; // 4 is even
cursor.hasNext() === true;
cursor.next(function (err, value) {
if (err) return console.error(err);
value === 5; // next value after 4
});
});cursor.map(fn: (value: any, index: number, cursor: Cursor) => any, [callback: Callback]): Promise<Array<any>>
Rewinds and exhausts the cursor by applying the function fn to each value returned by the query, then invokes the callback with an array of the return values.
Equivalent to Array.prototype.map.
Examples
function square(value) {
return value * value;
}
// query result: [1, 2, 3, 4, 5]
cursor.map(square, function (err, result) {
if (err) return console.error(err);
result.length === 5;
result; // [1, 4, 9, 16, 25]
cursor.hasNext() === false;
});cursor.reduce(fn: (prev: any, accu: any, index: number, cursor: Cursor) => T, [accu: T,] [callback: Callback]): Promise<T>
Rewinds and exhausts the cursor by reducing the values returned by the query with the given function fn. If accu is not provided, the first value returned by the query will be used instead (the function will not be invoked for that value).
Equivalent to Array.prototype.reduce.
Examples
function add(a, b) {
return a + b;
}
// query result: [1, 2, 3, 4, 5]
var baseline = 1000;
cursor.reduce(add, baseline, function (err, result) {
if (err) return console.error(err);
result === (baseline + 1 + 2 + 3 + 4 + 5);
cursor.hasNext() === false;
});
// -- or --
cursor.reduce(add, function (err, result) {
if (err) return console.error(err);
result === (1 + 2 + 3 + 4 + 5);
cursor.hasNext() === false;
});cursor.rewind(): cursor
Synchronous. Rewinds the cursor. Returns the cursor.
Examples
// query result: [1, 2, 3, 4, 5]
cursor.all(function (err, result) {
if (err) return console.error(err);
result; // [1, 2, 3, 4, 5]
cursor.hasNext() === false;
cursor.rewind();
cursor.hasNext() === true;
cursor.next(function (err, value) {
if (err) return console.error(err);
value === 1;
});
});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: string, [headers: Object]]): Route
Synchronous. Creates a new Route instance representing the path relative to the current route. Optionally headers can be an object with headers which will be extended with the current route's headers and the connection's headers.
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')route.get([path: string,] [qs: string,] [callback: Callback]): Promise<Response>
route.get([path: string,] [qs: Object,] [callback: Callback]): Promise<Response>
Performs a GET request to the given URL and passes the server response to the given callback.
Parameter
- path (optional): the route-relative URL for the request.
- qs (optional): the query string for the request.
If path is missing, the request will be made to the base URL of the route.
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(function (err, result) {
if (err) return console.error(err);
// result is the response body of calling
// GET _db/_system/my-foxx-app
});
// -- or --
route.get('users', function (err, result) {
if (err) return console.error(err);
// result is the response body of calling
// GET _db/_system/my-foxx-app/users
});
// -- or --
route.get('users', {group: 'admin'}, function (err, result) {
if (err) return console.error(err);
// result is the response body of calling
// GET _db/_system/my-foxx-app/users?group=admin
});route.post([path: string,] [body: string | Object, [qs: string | Object,]] [callback: Callback]): Promise<Response>
Performs a POST request to the given URL and passes the server response to the given callback.
Parameter
- path (optional): the route-relative URL for the request.
- body (optional): the request body for the request.
- qs (optional): the query string for the request.
If path is missing, the request will be made to the base URL of the route.
If body is an object, it will be converted to JSON.
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(function (err, result) {
if (err) return console.error(err);
// result is the response body of calling
// POST _db/_system/my-foxx-app
});
// -- or --
route.post('users', function (err, result) {
if (err) return console.error(err);
// result is the response body of calling
// POST _db/_system/my-foxx-app/users
});
// -- or --
route.post('users', {
username: 'admin',
password: 'hunter2'
}, function (err, result) {
if (err) return console.error(err);
// result 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}, function (err, result) {
if (err) return console.error(err);
// result is the response body of calling
// POST _db/_system/my-foxx-app/users?admin=true
// with JSON request body {"username": "admin", "password": "hunter2"}
});route.put([path: string,] [body: string | Object, [qs: string | Object,]] [callback: Callback]): Promise<Response>
Performs a PUT request to the given URL and passes the server response to the given callback.
Parameter
- path (optional): the route-relative URL for the request.
- body (optional): the request body for the request.
- qs (optional): the query string for the request.
If path is missing, the request will be made to the base URL of the route.
If body is an object, it will be converted to JSON.
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(function (err, result) {
if (err) return console.error(err);
// result is the response body of calling
// PUT _db/_system/my-foxx-app
});
// -- or --
route.put('users/admin', function (err, result) {
if (err) return console.error(err);
// result is the response body of calling
// PUT _db/_system/my-foxx-app/users
});
// -- or --
route.put('users/admin', {
username: 'admin',
password: 'hunter2'
}, function (err, result) {
if (err) return console.error(err);
// result 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}, function (err, result) {
if (err) return console.error(err);
// result is the response body of calling
// PUT _db/_system/my-foxx-app/users/admin?admin=true
// with JSON request body {"username": "admin", "password": "hunter2"}
});route.patch([path: string,] [body: string | Object, [qs: string | Object,]] [callback: Callback]): Promise<Response>
Performs a PATCH request to the given URL and passes the server response to the given callback.
Parameter
- path (optional): the route-relative URL for the request.
- body (optional): the request body for the request.
- qs (optional): the query string for the request.
If path is missing, the request will be made to the base URL of the route.
If body is an object, it will be converted to JSON.
If qs is an object, it will be translated to a query string.
var db = require('arangojs')();
var route = db.route('my-foxx-app');
route.patch(function (err, result) {
if (err) return console.error(err);
// result is the response body of calling
// PATCH _db/_system/my-foxx-app
});
// -- or --
route.patch('users/admin', function (err, result) {
if (err) return console.error(err);
// result is the response body of calling
// PATCH _db/_system/my-foxx-app/users
});
// -- or --
route.patch('users/admin', {
password: 'hunter2'
}, function (err, result) {
if (err) return console.error(err);
// result 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}, function (err, result) {
if (err) return console.error(err);
// result is the response body of calling
// PATCH _db/_system/my-foxx-app/users/admin?admin=true
// with JSON request body {"password": "hunter2"}
});route.delete([path: string,] [qs: string | Object,] [callback: Callback]): Promise<Response>
Performs a DELETE request to the given URL and passes the server response to the given callback.
Parameter
- path (optional): the route-relative URL for the request.
- qs (optional): the query string for the request.
If path is missing, the request will be made to the base URL of the route.
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(function (err, result) {
if (err) return console.error(err);
// result is the response body of calling
// DELETE _db/_system/my-foxx-app
});
// -- or --
route.delete('users/admin', function (err, result) {
if (err) return console.error(err);
// result is the response body of calling
// DELETE _db/_system/my-foxx-app/users/admin
});
// -- or --
route.delete('users/admin', {permanent: true}, function (err, result) {
if (err) return console.error(err);
// result is the response body of calling
// DELETE _db/_system/my-foxx-app/users/admin?permanent=true
});route.head([path: string,] [qs: string | Object,] [callback: Callback]): Promise<Response>
Performs a HEAD request to the given URL and passes the server response to the given callback.
Parameter
- path (optional): the route-relative URL for the request.
- qs (optional): the query string for the request.
If path is missing, the request will be made to the base URL of the route.
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(function (err, result, response) {
if (err) return console.error(err);
// result is empty (no response body)
// response is the response object for
// HEAD _db/_system/my-foxx-app
});route.request(opts: Object, [callback: Callback]): Promise<Response>
Performs an arbitrary request to the given URL and passes the server response to the given callback.
Parameter
- opts: an object with the following properties:
- path: the route-relative URL for the request.
- absolutePath (optional): whether the path is relative to the connection's base URL instead of the route. Default:
false. - body (optional): the request body.
- qs (optional): the query string.
- headers (optional): an object containing additional HTTP headers to send with the request.
- method (optional): HTTP method to use. Default:
"GET".
If opts.path is missing, the request will be made to the base URL of the route.
If opts.body is an object, it will be converted to JSON.
If opts.qs is an object, it will be translated to a query string.
var db = require('arangojs')();
var route = db.route('my-foxx-app');
route.request({
path: 'hello-world',
method: 'POST',
body: {hello: 'world'},
qs: {admin: true}
}, function (err, result) {
if (err) return console.error(err);
// result 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.
collection.properties([callback: Callback]): Promise<any>
Retrieves the collection's properties.
Examples
var db = require('arangojs')();
db.collection('some-collection', function (err, collection) {
if (err) return console.error(err);
collection.properties(function (err, props) {
if (err) return console.error(err);
// props contains the collection's properties
});
});collection.count([callback: Callback]): Promise<any>
Retrieves the number of documents in a collection.
Examples
var db = require('arangojs')();
db.collection('some-collection', function (err, collection) {
if (err) return console.error(err);
collection.count(function (err, count) {
if (err) return console.error(err);
// count contains the collection's count
});
});collection.figures([callback: Callback]): Promise<any>
Retrieves statistics for a collection.
Examples
var db = require('arangojs')();
db.collection('some-collection', function (err, collection) {
if (err) return console.error(err);
collection.figures(function (err, figures) {
if (err) return console.error(err);
// figures contains the collection's figures
});
});collection.revision([callback: Callback]): Promise<any>
Retrieves the collection revision ID.
Examples
var db = require('arangojs')();
db.collection('some-collection', function (err, collection) {
if (err) return console.error(err);
collection.revision(function (err, revision) {
if (err) return console.error(err);
// revision contains the collection's revision
});
});collection.checksum([opts: Object,] [callback: Callback]): Promise<any>
Retrieves the collection checksum.
For information on the possible options see the HTTP API for getting collection information.
Examples
var db = require('arangojs')();
db.collection('some-collection', function (err, collection) {
if (err) return console.error(err);
collection.checksum(function (err, checksum) {
if (err) return console.error(err);
// checksum contains the collection's checksum
});
});These functions implement the HTTP API for modifying collections.
collection.load([count: boolean,] [callback: Callback]): Promise<any>
Tells the server to load the collection into memory.
If count is 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')();
db.collection('some-collection', function (err, collection) {
if (err) return console.error(err);
collection.load(false, function (err) {
if (err) return console.error(err);
// the collection has now been loaded into memory
});
});collection.unload([callback: Callback]): Promise<any>
Tells the server to remove the collection from memory.
Examples
var db = require('arangojs')();
db.collection('some-collection', function (err, collection) {
if (err) return console.error(err);
collection.unload(function (err) {
if (err) return console.error(err);
// the collection has now been unloaded from memory
});
});collection.setProperties(properties: Object, [callback: Callback]): Promise<any>
Replaces the properties of the collection.
For information on the properties argument see the HTTP API for modifying collections.
Examples
var db = require('arangojs')();
db.collection('some-collection', function (err, collection) {
if (err) return console.error(err);
collection.setProperties({waitForSync: true}, function (err, result) {
if (err) return console.error(err);
result.waitForSync === true;
// the collection will now wait for data being written to disk
// whenever a document is changed
});
});collection.rename(name: string, [callback: Callback]): Promise<any>
Renames the collection. The Collection instance will automatically update its name according to the server response.
Examples
var db = require('arangojs')();
db.collection('some-collection', function (err, collection) {
if (err) return console.error(err);
collection.rename('new-collection-name', function (err, result) {
if (err) return console.error(err);
result.name === 'new-collection-name';
collection.name === result.name;
// result contains additional information about the collection
});
});collection.rotate([callback: Callback]): Promise<any>
Rotates the journal of the collection.
Examples
var db = require('arangojs')();
db.collection('some-collection', function (err, collection) {
if (err) return console.error(err);
collection.rotate(function (err, result) {
if (err) return console.error(err);
// result.result will be true if rotation succeeded
});
});collection.truncate([callback: Callback]): Promise<any>
Deletes all documents in the collection in the database.
Examples
var db = require('arangojs')();
db.collection('some-collection', function (err, collection) {
if (err) return console.error(err);
collection.truncate(function (err) {
if (err) return console.error(err);
// the collection "some-collection" is now empty
});
});collection.drop([callback: Callback]): Promise<any>
Deletes the collection from the database.
Equivalent to database.dropCollection(collection.name, [callback: Callback]).: Promise
Examples
var db = require('arangojs')();
db.collection('some-collection', function (err, collection) {
if (err) return console.error(err);
collection.drop(function (err) {
if (err) return console.error(err);
// the collection "some-collection" no longer exists
});
});These functions implement the HTTP API for manipulating indexes.
collection.createIndex(details: Object, [callback: Callback]): Promise<Index>
Creates an arbitrary index on the collection.
For information on the possible properties of the details object, see the HTTP API for manipulating indexes.
Examples
var db = require('arangojs')();
var collection = db.createCollection('some-collection', function (err, collection) {
if (err) return console.error(err);
collection.createIndex({
type: 'cap',
size: 20
}, function (err, index) {
if (err) return console.error(err);
index.id; // the index's handle
// the index has been created
});
});collection.createCapConstraint(size: Object | number, [callback: Callback]): Promise<Index>
Creates a cap constraint index on the collection.
Parameter
- size: an object with any of the following properties:
- size: the maximum number of documents in the collection.
- byteSize: 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')();
db.createCollection('some-collection', function (err, collection) {
if (err) return console.error(err);
collection.createCapCollection(20, function (err, index) {
if (err) return console.error(err);
index.id; // the index's handle
index.size === 20;
// the index has been created
});
// -- or --
collection.createCapCollection({size: 20}, function (err, index) {
if (err) return console.error(err);
index.id; // the index's handle
index.size === 20;
// the index has been created
});
});collection.createHashIndex(fields: Array<string> | string, [unique: boolean,] [callback: Callback]): Promise<Index>
Creates a hash index on the collection.
Parameter
- fields: an array of document fields on which to create the index.
- unique (optional): whether to constrain the fields to unique values. Default:
false.
If fields is a string, it will be wrapped in an array automatically.
For more information on hash indexes, see the HTTP API for hash indexes.
Examples
var db = require('arangojs')();
db.createCollection('some-collection', function (err, collection) {
if (err) return console.error(err);
collection.createHashIndex('favorite-color', function (err, index) {
if (err) return console.error(err);
index.id; // the index's handle
index.fields; // ['favorite-color']
// the index has been created
});
// -- or --
collection.createHashIndex(['favorite-color'], function (err, index) {
if (err) return console.error(err);
index.id; // the index's handle
index.fields; // ['favorite-color']
// the index has been created
});
});collection.createSkipList(fields: Array<string> | string, [unique: boolean,] [callback: Callback]): Promise<Index>
Creates a skiplist index on the collection.
Parameter
- fields: an array of document fields on which to create the index.
- unique (optional): whether to constrain the fields to unique values. Default:
false.
If fields is a string, it will be wrapped in an array automatically.
For more information on skiplist indexes, see the HTTP API for skiplist indexes.
Examples
var db = require('arangojs')();
db.createCollection('some-collection', function (err, collection) {
if (err) return console.error(err);
collection.createSkipList('favorite-color', function (err, index) {
if (err) return console.error(err);
index.id; // the index's handle
index.fields; // ['favorite-color']
// the index has been created
});
// -- or --
collection.createSkipList(['favorite-color'], function (err, index) {
if (err) return console.error(err);
index.id; // the index's handle
index.fields; // ['favorite-color']
// the index has been created
});
});collection.createGeoIndex(fields: Array<string> | string, [opts: Object,] [callback: Callback]): Promise<Index>
Creates a geo-spatial index on the collection.
Parameter
- fields: an array of document fields on which to create the index. Currently, fulltext indexes must cover exactly one field.
- opts (optional): an object containing additional properties of the index.
If fields is a string, it will be wrapped in an array automatically.
For more information on the properties of the opts object see the HTTP API for manipulating geo indexes.
Examples
var db = require('arangojs')();
db.createCollection('some-collection', function (err, collection) {
if (err) return console.error(err);
collection.createGeoIndex(['longitude', 'latitude'], function (err, index) {
if (err) return console.error(err);
index.id; // the index's handle
index.fields; // ['longitude', 'latitude']
// the index has been created
});
// -- or --
collection.createGeoIndex('location', {geoJson: true}, function (err, index) {
if (err) return console.error(err);
index.id; // the index's handle
index.fields; // ['location']
// the index has been created
});
});collection.createFulltextIndex(fields: Array<string> | string, [minLength: number,] [callback: Callback]): Promise<Index>
Creates a fulltext index on the collection.
Parameter
- fields: an array of document fields on which to create the index. Currently, fulltext indexes must cover exactly one field.
- minLength (optional): minimum character length of words to index. Uses a server-specific default value if not specified.
If fields is a string, it will be wrapped in an array automatically.
For more information on fulltext indexes, see the HTTP API for fulltext indexes.
Examples
var db = require('arangojs')();
db.createCollection('some-collection', function (err, collection) {
if (err) return console.error(err);
collection.createFulltextIndex('description', function (err, index) {
if (err) return console.error(err);
index.id; // the index's handle
index.fields; // ['description']
// the index has been created
});
// -- or --
collection.createFulltextIndex(['description'], function (err, index) {
if (err) return console.error(err);
index.id; // the index's handle
index.fields; // ['description']
// the index has been created
});
});collection.index(indexHandle: string | Index, [callback: Callback]): Promise<Index>
Fetches information about the index with the given indexHandle and passes it to the given callback.
The value of indexHandle can either be a fully-qualified index.id or the collection-specific key of the index.
Examples
var db = require('arangojs')();
db.createCollection('some-collection', function (err, collection) {
if (err) return console.error(err);
collection.createFulltextIndex('description', function (err, index) {
if (err) return console.error(err);
collection.index(index.id, function (err, result) {
if (err) return console.error(err);
result.id === index.id;
// result contains the properties of the index
});
// -- or --
collection.index(index.id.split('/')[1], function (err, result) {
if (err) return console.error(err);
result.id === index.id;
// result contains the properties of the index
});
});
});collection.indexes([callback: Callback]): Promise<Array<Index>>
Fetches a list of all indexes on this collection.
Examples
var db = require('arangojs')();
db.createCollection('some-collection', function (err, collection) {
if (err) return console.error(err);
collection.createFulltextIndex('description', function (err) {
if (err) return console.error(err);
collection.indexes(function (err, indexes) {
if (err) return console.error(err);
indexes.length === 1;
// indexes contains information about the index
});
});
});collection.dropIndex(indexHandle: string | Index, [callback: Callback]): Promise<any>
Deletes the index with the given indexHandle from the collection.
The value of indexHandle can either be a fully-qualified index.id or the collection-specific key of the index.
Examples
var db = require('arangojs')();
db.createCollection('some-collection', function (err, collection) {
if (err) return console.error(err);
collection.createFulltextIndex('description', function (err, index) {
if (err) return console.error(err);
collection.dropIndex(index.id, function (err) {
if (err) return console.error(err);
// the index has been removed from the collection
});
// -- or --
collection.dropIndex(index.id.split('/')[1], function (err) {
if (err) return console.error(err);
// the index has been removed from the collection
});
});
});This function implements the HTTP API for fulltext queries.
Note that a collection must have fulltext indexes in order to perform fulltext queries on it.
collection.fulltext(fieldName: string, query: string, [opts: Object,] [callback: Callback]): Promise<Cursor>
Performs a fulltext query searching for query in the given fieldName of all documents in this collection.
Parameter
- fieldName: the name of the field to search.
- query: a fulltext query string.
- opts (optional): an object containing additional options for the query.
For more information on the properties of the opts object see the HTTP API for fulltext queries.
For more information on Cursor instances see the Cursor API above.
Examples
var db = require('arangojs')();
db.collection('some-collection', function (err, collection) {
if (err) return console.error(err);
collection.createFulltextIndex('description', function (err) {
if (err) return console.error(err);
collection.fulltext('description', 'hello', function (err, cursor) {
if (err) return console.error(err);
// cursor is a Cursor instance for the query results
});
});
});These functions implement the HTTP API for geo-spatial queries.
Note that a collection must have geo-spatial indexes in order to perform geo-spatial queries on it.
collection.near(latitude: number, longitude: number, [opts: Object,] [callback: Callback]): Promise<Cursor>
Performs a geo-spatial query for documents near the given location.
Parameter
- latitude: latitude of the target location.
- longitude: longitude of the target location.
- opts (optional): an object containing additional options for the query.
For more information on the properties of the opts object see the HTTP API for geo-spatial queries.
For more information on Cursor instances see the Cursor API above.
Examples
var db = require('arangojs')();
db.collection('some-collection', function (err, collection) {
if (err) return console.error(err);
collection.createGeoIndex('location', function (err) {
if (err) return console.error(err);
collection.near(0, 0, {
limit: 100,
distance: 'distance'
}, function (err, cursor) {
if (err) return console.error(err);
// cursor is a Cursor instance for the closest 100 query results
// each result has an additional property "distance" containing
// the document's distance to the target location in meters
});
});
});collection.within(latitude: number, longitude: number, radius: number, [opts: Object,] [callback: Callback]): Promise<Cursor>
Performs a geo-spatial query for documents within the given radius of the given location.
Parameter
- latitude: latitude of the target location.
- longitude: longitude of the target location.
- radius: the search radius (in meters).
- opts (optional): an object containing additional options for the query.
For more information on the properties of the opts object see the HTTP API for geo-spatial queries.
For more information on Cursor instances see the Cursor API above.
Examples
var db = require('arangojs')();
db.collection('some-collection', function (err, collection) {
if (err) return console.error(err);
collection.createGeoIndex('location', function (err) {
if (err) return console.error(err);
collection.within(0, 0, 500, {
limit: 100,
distance: 'distance'
}, function (err, cursor) {
if (err) return console.error(err);
// cursor is a Cursor instance for the closest 100 query results
// within up to 500 meters of the target location
// each result has an additional property "distance" containing
// the document's distance to the target location in meters
});
});
});This function implements the HTTP API for bulk imports.
collection.import(data: Array<Object> | Array<Array<any>>, [opts: Object,] [callback: Callback]): Promise<any>
Bulk imports the given data into the collection.
The data 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
...
]If opts is set, it must be an object with any of the following properties:
- waitForSync: Wait until the documents have been synced to disk. Default:
false. - details: Whether the response should contain additional details about documents that could not be imported. Default: false.
- type: Indicates which format the data uses. Can be
"documents","array"or"auto". Default:"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')();
db.collection('users', function (err, collection) {
if (err) return console.error(err);
collection.import(
[// document stream
{username: 'admin', password: 'hunter2', 'favorite-color': 'orange'},
{username: 'jcd', password: 'bionicman', 'favorite-color': 'black'},
{username: 'jreyes', password: 'amigo', 'favorite-color': 'white'},
{username: 'ghermann', password: 'zeitgeist', 'favorite-color': 'blue'}
],
function (err, result) {
if (err) return console.error(err);
result.created === 4;
}
);
// -- or --
collection.import(
[// array stream with header
['username', 'password', 'favourite_color'],
['admin', 'hunter2', 'orange'],
['jcd', 'bionicman', 'black'],
['jreyes', 'amigo', 'white'],
['ghermann', 'zeitgeist', 'blue']
],
function (err, result) {
if (err) return console.error(err);
result.created === 4;
}
);
// -- or --
collection.import(
(// raw line-delimited JSON array stream with header
'["username", "password", "favourite_color"]\r\n' +
'["admin", "hunter2", "orange"]\r\n' +
'["jcd", "bionicman", "black"]\r\n' +
'["jreyes", "amigo", "white"]\r\n' +
'["ghermann", "zeitgeist", "blue"]\r\n'
),
function (err, result) {
if (err) return console.error(err);
result.created === 4;
}
);
});These functions implement the HTTP API for manipulating documents.
collection.replace(documentHandle: string | Document, data: Object, [opts: Object,] [callback: Callback]): Promise<any>
Replaces the content of the document with the given documentHandle with the given data.
If opts is set, it must be an object with any of the following properties:
- waitForSync: Wait until the document has been synced to disk. Default:
false. - rev: Only replace the document if it matches this revision. Optional.
- policy: 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.
The documentHandle 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).
For more information on the opts object, see the HTTP API documentation for working with documents.
Examples
var db = require('arangojs')();
db.collection('some-collection', function (err, collection) {
if (err) return console.error(err);
collection.save({number: 1, hello: 'world'}, function (err, doc) {
if (err) return console.error(err);
collection.replace(doc, {number: 2}, function (err, doc2) {
if (err) return console.error(err);
doc2._id === doc._id;
doc2._rev !== doc._rev;
doc2.number === 2;
doc2.hello === undefined;
});
});
});collection.update(documentHandle: string | Document, data: Object, [opts: Object,] [callback: Callback]): Promise<any>
Updates (merges) the content of the document with the given documentHandle with the given data.
If opts is set, it must be an object with any of the following properties:
- waitForSync: Wait until document has been synced to disk. Default:
false - keepNull: If set to
false, properties with a value ofnullindicate that a property should be deleted. Default:true. - mergeObjects: If set to
false, object properties that already exist in the old document will be overwritten rather than merged. This does not affect arrays. Default:true. - rev: Only update the document if it matches this revision. Optional.
- policy: 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.
The documentHandle 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).
For more information on the opts object, see the HTTP API documentation for working with documents.
Examples
var db = require('arangojs')();
db.collection('some-collection', function (err, collection) {
if (err) return console.error(err);
collection.save({number: 1, hello: 'world'}, function (err, doc) {
if (err) return console.error(err);
collection.update(doc, {number: 2}, function (err, doc2) {
if (err) return console.error(err);
doc2._id === doc._id;
doc2._rev !== doc._rev;
doc2.number === 2;
doc2.hello === doc.hello;
});
});
});collection.remove(documentHandle: string | Document, [opts: Object,] [callback: Callback]): Promise<any>
Deletes the document with the given documentHandle from the collection.
If opts is set, it must be an object with any of the following properties:
- waitForSync: Wait until document has been synced to disk. Default:
false - rev: Only update the document if it matches this revision. Optional.
- policy: 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.
The documentHandle 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).
For more information on the opts object, see the HTTP API documentation for working with documents.
Examples
var db = require('arangojs')();
db.collection('some-collection', function (err, collection) {
if (err) return console.error(err);
collection.remove('some-doc', function (err) {
if (err) return console.error(err);
// document 'some-collection/some-doc' no longer exists
});
// -- or --
collection.remove('some-collection/some-doc', function (err) {
if (err) return console.error(err);
// document 'some-collection/some-doc' no longer exists
});
});collection.all([type: string,] [callback: Callback]): Promise<Array<T>>
Retrieves a list of all documents in the collection.
If type is set to "key", the result will be the _key of each document.
If type is set to "path", the result will be the document URI paths.
If type is set to "id" or not set, the result will be the _id of each document.
The DocumentCollection API extends the Collection API (see above) with the following methods.
documentCollection.document(documentHandle: string | Document, [callback: Callback]): Promise<Document>
Retrieves the document with the given documentHandle from the collection.
The documentHandle 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).
Examples
var db = require('arangojs')();
// assumes a document collection "my-docs" already exists
db.collection('my-docs', function (err, collection) {
if (err) return console.error(err);
collection.document('some-key', function (err, doc) {
if (err) return console.error(err);
// the document exists
doc._key === 'some-key';
doc._id === 'my-docs/some-key';
});
// -- or --
collection.document('my-docs/some-key', function (err, doc) {
if (err) return console.error(err);
// the document exists
doc._key === 'some-key';
doc._id === 'my-docs/some-key';
});
});documentCollection.save(data: Object, [callback: Callback]): Promise<Document>
Creates a new document with the given data.
Examples
var db = require('arangojs')();
db.createCollection('my-docs', function (err, collection) {
if (err) return console.error(err);
collection.save(
{some: 'data'},
function (err, doc) {
if (err) return console.error(err);
doc._key; // the document's key
doc._id === ('my-docs/' + doc._key);
doc.some === 'data';
}
);
});The EdgeCollection API extends the Collection API (see above) with the following methods.
edgeCollection.edge(documentHandle: string | Document, [callback: Callback]): Promise<Document>
Retrieves the edge with the given documentHandle from the collection.
The documentHandle can be either the _id or the _key of an edge in the collection, or an edge (i.e. an object with an _id or _key property).
Examples
var db = require('arangojs')();
// assumes an edge collection "edges" already exists
db.collection('edges', function (err, collection) {
if (err) return console.error(err);
collection.edge('some-key', function (err, edge) {
if (err) return console.error(err);
// the edge exists
edge._key === 'some-key';
edge._id === 'edges/some-key';
});
// -- or --
collection.edge('edges/some-key', function (err, edge) {
if (err) return console.error(err);
// the edge exists
edge._key === 'some-key';
edge._id === 'edges/some-key';
});
});edgeCollection.save(data: Object, fromId: string | Object, toId: string | Object, [callback: Callback]): Promise<Document>
Creates a new edge between the documents fromId and toId with the given data.
If fromId and toId are not specified, the data needs to contain the properties _from and _to.
Examples
var db = require('arangojs')();
// assumes a collection "vertices" already exists
db.createEdgeCollection('edges', function (err, collection) {
if (err) return console.error(err);
collection.save(
{some: 'data'},
'vertices/start-vertex',
'vertices/end-vertex',
function (err, edge) {
if (err) return console.error(err);
edge._key; // the edge's key
edge._id === ('edges/' + edge._key);
edge.some === 'data';
edge._from === 'vertices/start-vertex';
edge._to === 'vertices/end-vertex';
}
);
});edgeCollection.edges(documentHandle: string | Document, [callback: Callback]): Promise<Array<Document>>
Retrieves a list of all edges of the document with the given documentHandle.
The documentHandle can be either the _id or the _key of a document in any collection, or a document (i.e. an object with an _id or _key property).
Examples
var db = require('arangojs')();
// assumes a collection "vertices" already exists
db.createEdgeCollection('edges', function (err, collection) {
if (err) return console.error(err);
collection.import([
['_key', '_from', '_to'],
['x', 'vertices/a', 'vertices/b'],
['y', 'vertices/a', 'vertices/c'],
['z', 'vertices/d', 'vertices/a']
], function (err) {
if (err) return console.error(err);
collection.edges('vertices/a', function (err, edges) {
if (err) return console.error(err);
edges.length === 3;
edges.map(function (edge) {return edge._key;}); // ['x', 'y', 'z']
});
});
});edgeCollection.inEdges(documentHandle: string | Document, [callback: Callback]): Promise<Array<Document>>
Retrieves a list of all incoming edges of the document with the given documentHandle.
The documentHandle can be either the _id or the _key of a document in any collection, or a document (i.e. an object with an _id or _key property).
Examples
var db = require('arangojs')();
// assumes a collection "vertices" already exists
db.createEdgeCollection('edges', function (err, collection) {
if (err) return console.error(err);
collection.import([
['_key', '_from', '_to'],
['x', 'vertices/a', 'vertices/b'],
['y', 'vertices/a', 'vertices/c'],
['z', 'vertices/d', 'vertices/a']
], function (err) {
if (err) return console.error(err);
collection.inEdges('vertices/a', function (err, edges) {
if (err) return console.error(err);
edges.length === 1;
edges[0]._key === 'z';
});
});
});edgeCollection.outEdges(documentHandle: string | Document, [callback: Callback]): Promise<Array<Document>>
Retrieves a list of all outgoing edges of the document with the given documentHandle.
The documentHandle can be either the _id or the _key of a document in any collection, or a document (i.e. an object with an _id or _key property).
Examples
var db = require('arangojs')();
// assumes a collection "vertices" already exists
db.createEdgeCollection('edges', function (err, collection) {
if (err) return console.error(err);
collection.import([
['_key', '_from', '_to'],
['x', 'vertices/a', 'vertices/b'],
['y', 'vertices/a', 'vertices/c'],
['z', 'vertices/d', 'vertices/a']
], function (err) {
if (err) return console.error(err);
collection.outEdges('vertices/a', function (err, edges) {
if (err) return console.error(err);
edges.length === 2;
edges.map(function (edge) {return edge._key;}); // ['x', 'y']
});
});
});edgeCollection.traversal(startVertex: string | Document, [opts: Object,] [callback: Callback]): Promise<Object>
Performs a traversal starting from the given startVertex and following edges contained in this edge collection.
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
var db = require('arangojs')();
// assumes a collection "vertices" already exists
db.createEdgeCollection('edges', function (err, collection) {
if (err) return console.error(err);
collection.import([
['_key', '_from', '_to'],
['x', 'vertices/a', 'vertices/b'],
['y', 'vertices/b', 'vertices/c'],
['z', 'vertices/c', 'vertices/d']
], function (err) {
if (err) return console.error(err);
collection.traversal('vertices/a', {
direction: 'outbound',
visitor: 'result.vertices.push(vertex._key);',
init: 'result.vertices = [];'
}, function (err, result) {
if (err) return console.error(err);
result.vertices; // ['a', 'b', 'c', 'd']
});
});
});These functions implement the HTTP API for manipulating graphs.
graph.drop([dropCollections: boolean,] [callback: Callback]): Promise<any>
Deletes the graph from the database.
If dropCollections is set to true, the collections associated with the graph will also be deleted.
Equivalent to database.dropGraph(graph.name, [callback: Callback]).: Promise
Examples
var db = require('arangojs')();
db.graph('some-graph', function (err, graph) {
if (err) return console.error(err);
graph.drop(function (err) {
if (err) return console.error(err);
// the graph "some-graph" no longer exists
});
});graph.vertexCollection(collectionName: string, [callback: Callback]): Promise<GraphVertexCollection>
Fetches the vertex collection with the given collectionName from the database, then passes a new GraphVertexCollection instance to the callback.
Examples
var db = require('arangojs')();
// assuming the collections "edges" and "vertices" exist
db.createGraph({
name: 'some-graph',
edgeDefinitions: [{
collection: 'edges',
from: ['vertices'],
to: ['vertices']
}]
}, function (err, graph) {
if (err) return console.error(err);
graph.vertexCollection('vertices', function (err, collection) {
if (err) return console.error(err);
collection.name === 'vertices';
// collection is a GraphVertexCollection
});
});graph.addVertexCollection(collectionName: string, [callback: Callback]): Promise<any>
Adds the collection with the given collectionName to the graph's vertex collections.
Examples
var db = require('arangojs')();
// assuming the collection "vertices" exist
db.createGraph({
name: 'some-graph',
edgeDefinitions: []
}, function (err, graph) {
if (err) return console.error(err);
graph.addVertexCollection('vertices', function (err) {
if (err) return console.error(err);
// the collection "vertices" has been added to the graph
});
});graph.removeVertexCollection(collectionName: string, [dropCollection: boolean,] [callback: Callback]): Promise<any>
Removes the vertex collection with the given collectionName from the graph.
If dropCollection is set to true, the collection will also be deleted from the database.
Examples
var db = require('arangojs')();
// assuming the collections "edges" and "vertices" exist
db.createGraph({
name: 'some-graph',
orphanCollections: ['vertices']
}, function (err, graph) {
if (err) return console.error(err);
graph.removeVertexCollection('vertices', function (err) {
if (err) return console.error(err);
// collection "vertices" has been removed from the graph
});
// -- or --
graph.removeVertexCollection('vertices', true, function (err) {
if (err) return console.error(err);
// collection "vertices" has been removed from the graph
// the collection has also been dropped from the database
// this may have been a bad idea
});
});graph.edgeCollection(collectionName: string, [callback: Callback]): Promise<GraphEdgeCollection>
Fetches the edge collection with the given collectionName from the database, then passes a new GraphEdgeCollection instance to the callback.
Examples
var db = require('arangojs')();
// assuming the collections "edges" and "vertices" exist
db.createGraph({
name: 'some-graph',
edgeDefinitions: [{
collection: 'edges',
from: ['vertices'],
to: ['vertices']
}]
}, function (err, graph) {
if (err) return console.error(err);
graph.edgeCollection('edges', function (err, collection) {
if (err) return console.error(err);
collection.name === 'edges';
// collection is a GraphEdgeCollection
});
});graph.addEdgeDefinition(definition: Object, [callback: Callback]): Promise<any>
Adds the given edge definition definition to the graph.
For more information on edge definitions see the HTTP API for managing graphs.
Examples
var db = require('arangojs')();
// assuming the collections "edges" and "vertices" exist
db.createGraph({
name: 'some-graph',
edgeDefinitions: []
}, function (err, graph) {
if (err) return console.error(err);
graph.addEdgeDefinition({
collection: 'edges',
from: ['vertices'],
to: ['vertices']
}, function (err) {
if (err) return console.error(err);
// the edge definition has been added to the graph
});
});graph.replaceEdgeDefinition(collectionName: string, definition: Object, [callback: Callback]): Promise<any>
Replaces the edge definition for the edge collection named collectionName with the given definition.
For more information on edge definitions see the HTTP API for managing graphs.
Examples
var db = require('arangojs')();
// assuming the collections "edges", "vertices" and "more-vertices" exist
db.createGraph({
name: 'some-graph',
edgeDefinitions: [{
collection: 'edges',
from: ['vertices'],
to: ['vertices']
}]
}, function (err, graph) {
if (err) return console.error(err);
graph.replaceEdgeDefinition('edges', {
collection: 'edges',
from: ['vertices'],
to: ['more-vertices']
}, function (err) {
if (err) return console.error(err);
// the edge definition has been modified
});
});graph.removeEdgeDefinition(definitionName: string, [dropCollection: boolean,] [callback: Callback]): Promise<any>
Removes the edge definition with the given definitionName form the graph.
If dropCollection is set to true, the edge collection associated with the definition will also be deleted from the database.
For more information on edge definitions see the HTTP API for managing graphs.
Examples
var db = require('arangojs')();
// assuming the collections "edges" and "vertices" exist
db.createGraph({
name: 'some-graph',
edgeDefinitions: [{
collection: 'edges',
from: ['vertices'],
to: ['vertices']
}]
}, function (err, graph) {
if (err) return console.error(err);
graph.removeEdgeDefinition('edges', function (err) {
if (err) return console.error(err);
// the edge definition has been removed
});
// -- or --
graph.removeEdgeDefinition('edges', true, function (err) {
if (err) return console.error(err);
// the edge definition has been removed
// and the edge collection "edges" has been dropped
// this may have been a bad idea
});
});graph.traversal(startVertex: string | Document, [opts: Object,] [callback: Callback]): Promise<Object>
Performs a traversal starting from the given startVertex and following edges contained in any of the edge collections of this graph.
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
var db = require('arangojs')();
// assumes the collections "edges" and "vertices" already exist
db.createGraph({
name: 'some-graph',
edgeDefinitions: [{
collection: 'edges',
from: ['vertices'],
to: ['vertices']
}]
}, function (err, graph) {
if (err) return console.error(err);
graph.edgeCollection('edges', function (err, collection) {
if (err) return console.error(err);
collection.import([
['_key', '_from', '_to'],
['x', 'vertices/a', 'vertices/b'],
['y', 'vertices/b', 'vertices/c'],
['z', 'vertices/c', 'vertices/d']
], function (err) {
if (err) return console.error(err);
graph.traversal('vertices/a', {
direction: 'outbound',
visitor: 'result.vertices.push(vertex._key);',
init: 'result.vertices = [];'
}, function (err, result) {
if (err) return console.error(err);
result.vertices; // ['a', 'b', 'c', 'd']
});
});
});
});The GraphVertexCollection API extends the Collection API (see above) with the following methods.
graphVertexCollection.vertex(documentHandle: string | Document, [callback: Callback]): Promise<Document>
Retrieves the vertex with the given documentHandle from the collection.
The documentHandle can be either the _id or the _key of a vertex in the collection, or a vertex (i.e. an object with an _id or _key property).
Examples
// assumes the collections "edges" and "vertices" already exist
db.createGraph({
name: 'some-graph',
edgeDefinitions: [{
collection: 'edges',
from: ['vertices'],
to: ['vertices']
}]
}, function (err, graph) {
if (err) return console.error(err);
graph.vertexCollection('vertices', function (err, collection) {
if (err) return console.error(err);
collection.vertex('some-key', function (err, doc) {
if (err) return console.error(err);
// the vertex exists
doc._key === 'some-key';
doc._id === 'vertices/some-key';
});
// -- or --
collection.vertex('vertices/some-key', function (err, doc) {
if (err) return console.error(err);
// the vertex exists
doc._key === 'some-key';
doc._id === 'vertices/some-key';
});
});
});graphVertexCollection.save(data: Object, [callback: Callback]): Promise<Document>
Creates a new vertex with the given data.
Examples
var db = require('arangojs')();
// assumes the collections "edges" and "vertices" already exist
db.createGraph({
name: 'some-graph',
edgeDefinitions: [{
collection: 'edges',
from: ['vertices'],
to: ['vertices']
}]
}, function (err, graph) {
if (err) return console.error(err);
graph.vertexCollection('vertices', function (err, collection) {
if (err) return console.error(err);
collection.save(
{some: 'data'},
function (err, doc) {
if (err) return console.error(err);
doc._key; // the document's key
doc._id === ('vertices/' + doc._key);
doc.some === 'data';
}
);
});
});The GraphEdgeCollection API extends the Collection API (see above) with the following methods.
graphEdgeCollection.edge(documentHandle: string | Document, [callback: Callback]): Promise<Document>
Retrieves the edge with the given documentHandle from the collection.
The documentHandle can be either the _id or the _key of an edge in the collection, or an edge (i.e. an object with an _id or _key property).
// assumes the collections "edges" and "vertices" already exist
db.createGraph({
name: 'some-graph',
edgeDefinitions: [{
collection: 'edges',
from: ['vertices'],
to: ['vertices']
}]
}, function (err, graph) {
if (err) return console.error(err);
graph.edgeCollection('edges', function (err, collection) {
if (err) return console.error(err);
collection.edge('some-key', function (err, edge) {
if (err) return console.error(err);
// the edge exists
edge._key === 'some-key';
edge._id === 'edges/some-key';
});
// -- or --
collection.edge('edges/some-key', function (err, edge) {
if (err) return console.error(err);
// the edge exists
edge._key === 'some-key';
edge._id === 'edges/some-key';
});
});
});graphEdgeCollection.save(data: Object, [fromId: string | Document, toId: string | Document,] [callback: Callback]): Promise<Document>
Creates a new edge between the vertices fromId and toId with the given data.
If fromId and toId are not specified, the data needs to contain the properties _from and _to.
Examples
var db = require('arangojs')();
// assumes the collections "edges" and "vertices" already exist
db.createGraph({
name: 'some-graph',
edgeDefinitions: [{
collection: 'edges',
from: ['vertices'],
to: ['vertices']
}]
}, function (err, graph) {
if (err) return console.error(err);
graph.edgeCollection('edges', function (err, collection) {
if (err) return console.error(err);
collection.save(
{some: 'data'},
'vertices/start-vertex',
'vertices/end-vertex',
function (err, edge) {
if (err) return console.error(err);
edge._key; // the edge's key
edge._id === ('edges/' + edge._key);
edge.some === 'data';
edge._from === 'vertices/start-vertex';
edge._to === 'vertices/end-vertex';
}
);
});
});The Apache License, Version 2.0. For more information, see the accompanying LICENSE file.