The official ArangoDB low-level JavaScript clients.
npm install arangojs
git clone https://github.com/arangodb/arangojs.git
cd arangojs
npm install
npm run dist
All asynchronous functions take an optional node-style callback (or "errback") with the following arguments:
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:
[these: A, are: B, optional: C].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 }result argument passed to callbacks is always identical to the type of the equivalent promise's onFulfilled argument and is therefore not explicitly specified in the type signatures. I.e. if the return type is specified as Promise<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
http://localhost:8529._system.x-arango-version header. Default: 20300.http.Agent instance configured with the agentOptions.{maxSockets: 3, keepAlive: true, keepAliveMsecs: 1000}.Promise implementation to use or false to disable promises entirely (for performance). Default: the global Promise constructor 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:
true.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
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,] [opts: 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
If opts.count is set to true, the cursor will have a count property set to the query result count.
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
"myfuncs::accounting::calculate_vat".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
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
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
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
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
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
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
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
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
false."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
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, [opts: Object | boolean,] [callback: Callback]): Promise<Index>
Creates a hash index on the collection.
Parameter
If opts is a boolean, it will be interpreted as opts.unique.
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, [opts: Object | boolean,] [opts: Object,] [callback: Callback]): Promise<Index>
Creates a skiplist index on the collection.
Parameter
If opts is a boolean, it will be interpreted as opts.unique.
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
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
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
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
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
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:
false."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:
false."last", the document will be replaced regardless of the revision."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:
falsefalse, properties with a value of null indicate that a property should be deleted. Default: true.false, object properties that already exist in the old document will be overwritten rather than merged. This does not affect arrays. Default: true."last", the document will be replaced regardless of the revision."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:
false"last", the document will be replaced regardless of the revision."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<Object>>
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.
collection.byKeys(keys: Array<string>, [callback: Callback]): Promise<Array<Object>>
Retrieves a list of the documents with the given keys in the collection.
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.
FAQs
The official ArangoDB JavaScript driver.
The npm package arangojs receives a total of 5,897 weekly downloads. As such, arangojs popularity was classified as popular.
We found that arangojs demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 5 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
At its inaugural meeting, the JSR Working Group outlined plans for an open governance model and a roadmap to enhance JavaScript package management.
Security News
Research
An advanced npm supply chain attack is leveraging Ethereum smart contracts for decentralized, persistent malware control, evading traditional defenses.
Security News
Research
Attackers are impersonating Sindre Sorhus on npm with a fake 'chalk-node' package containing a malicious backdoor to compromise developers' projects.