Class Database

Updates the URL list by requesting a list of all coordinators in the cluster and adding any endpoints not initially specified in the Config.

For long-running processes communicating with an ArangoDB cluster it is recommended to run this method periodically (e.g. once per hour) to make sure new coordinators are picked up correctly and can be used for fail-over or load balancing.

Example

const db = new Database();
const interval = setInterval(
  () => db.acquireHostList(),
  5 * 60 * 1000 // every 5 minutes
);

// later
clearInterval(interval);
system.close();

Returns an Analyzer instance representing the Analyzer with the given analyzerName.

Example

const db = new Database();
const analyzer = db.analyzer("some-analyzer");
const info = await analyzer.get();

Fetches all Analyzers visible in the database and returns an array of Analyzer instances for those Analyzers.

See also listAnalyzers.

Example

const db = new Database();
const analyzers = await db.analyzers();
// analyzers is an array of Analyzer instances

Begins a new streaming transaction for the given collections, then returns a Transaction instance for the transaction.

Collections can be specified as collection names (strings) or objects implementing the ArangoCollection interface: Collection, GraphVertexCollection, GraphEdgeCollection as well as (in TypeScript) DocumentCollection and EdgeCollection.

Example

const vertices = db.collection("vertices");
const edges = db.collection("edges");
const trx = await db.beginTransaction({
  read: ["vertices"],
  write: [edges] // collection instances can be passed directly
});
const start = await trx.step(() => vertices.document("a"));
const end = await trx.step(() => vertices.document("b"));
await trx.step(() => edges.save({ _from: start._id, _to: end._id }));
await trx.commit();

Begins a new streaming transaction for the given collections, then returns a Transaction instance for the transaction.

Collections can be specified as collection names (strings) or objects implementing the ArangoCollection interface: Collection, GraphVertexCollection, GraphEdgeCollection as well as (in TypeScript) DocumentCollection and EdgeCollection.

Example

const vertices = db.collection("vertices");
const edges = db.collection("edges");
const trx = await db.beginTransaction([
  "vertices",
  edges // collection instances can be passed directly
]);
const start = await trx.step(() => vertices.document("a"));
const end = await trx.step(() => vertices.document("b"));
await trx.step(() => edges.save({ _from: start._id, _to: end._id }));
await trx.commit();

Begins a new streaming transaction for the given collections, then returns a Transaction instance for the transaction.

The Collection can be specified as a collection name (string) or an object implementing the ArangoCollection interface: Collection, GraphVertexCollection, GraphEdgeCollection as well as (in TypeScript) DocumentCollection and EdgeCollection.

Example

const vertices = db.collection("vertices");
const start = vertices.document("a");
const end = vertices.document("b");
const edges = db.collection("edges");
const trx = await db.beginTransaction(
  edges // collection instances can be passed directly
);
await trx.step(() => edges.save({ _from: start._id, _to: end._id }));
await trx.commit();

Clears the list of recent slow queries.

See also listSlowQueries.

Example

const db = new Database();
await db.clearSlowQueries();
// Slow query list is now cleared

Clears the given ArangoDB user's access level for the database, or the given collection in the given database.

Example

const db = new Database();
await db.clearUserAccessLevel("steve");
// The access level of the user "steve" has been cleared for the current
// database.

Example

const db = new Database();
await db.clearUserAccessLevel("steve", { database: "staging" });
// The access level of the user "steve" has been cleared for the "staging"
// database.

Example

const db = new Database();
await db.clearUserAccessLevel("steve", { collection: "pokemons" });
// The access level of the user "steve" has been cleared for the
// "pokemons" collection in the current database.

Example

const db = new Database();
await db.clearUserAccessLevel("steve", {
  database: "staging",
  collection: "pokemons"
});
// The access level of the user "steve" has been cleared for the
// "pokemons" collection in the "staging" database.

Example

const db = new Database();
const staging = db.database("staging");
await db.clearUserAccessLevel("steve", { database: staging });
// The access level of the user "steve" has been cleared for the "staging"
// database.

Example

const db = new Database();
const staging = db.database("staging");
await db.clearUserAccessLevel("steve", {
  collection: staging.collection("pokemons")
});
// The access level of the user "steve" has been cleared for the
// "pokemons" collection in database "staging".

Closes all active connections of this database instance.

Can be used to clean up idling connections during longer periods of inactivity.

Note: This method currently has no effect in the browser version of arangojs.

Example

const db = new Database();
const sessions = db.collection("sessions");
// Clean up expired sessions once per hour
setInterval(async () => {
  await db.query(aql`
    FOR session IN ${sessions}
    FILTER session.expires < DATE_NOW()
    REMOVE session IN ${sessions}
  `);
  // Making sure to close the connections because they're no longer used
  system.close();
}, 1000 * 60 * 60);

Returns a Collection instance for the given collection name.

In TypeScript the collection implements both the DocumentCollection and EdgeCollection interfaces and can be cast to either type to enforce a stricter API.

Example

const db = new Database();
const collection = db.collection("potatoes");

Example

interface Person {
  name: string;
}
const db = new Database();
const persons = db.collection<Person>("persons");

Example

interface Person {
  name: string;
}
interface Friend {
  startDate: number;
  endDate?: number;
}
const db = new Database();
const documents = db.collection("persons") as DocumentCollection<Person>;
const edges = db.collection("friends") as EdgeCollection<Friend>;

Fetches all collections from the database and returns an array of Collection instances.

In TypeScript these instances implement both the DocumentCollection and EdgeCollection interfaces and can be cast to either type to enforce a stricter API.

See also listCollections.

Example

const db = new Database();
const collections = await db.collections();
// collections is an array of DocumentCollection and EdgeCollection
// instances not including system collections

Example

const db = new Database();
const collections = await db.collections(false);
// collections is an array of DocumentCollection and EdgeCollection
// instances including system collections

Writes all locally available services to the database and updates any service bundles missing in the database.

Example

await db.commitLocalServiceState();
// all services available on the coordinator have been written to the db

Example

await db.commitLocalServiceState(true);
// all service conflicts have been resolved in favor of this coordinator

Creates a new Analyzer with the given analyzerName and options, then returns an Analyzer instance for the new Analyzer.

Example

const db = new Database();
const analyzer = await db.createAnalyzer("potatoes", { type: "identity" });
// the identity Analyzer "potatoes" now exists

Creates a new collection with the given collectionName and options, then returns a DocumentCollection instance for the new collection.

Example

const db = new Database();
const documents = db.createCollection("persons");

Example

interface Person {
  name: string;
}
const db = new Database();
const documents = db.createCollection<Person>("persons");

Creates a new edge collection with the given collectionName and options, then returns an EdgeCollection instance for the new edge collection.

Example

const db = new Database();
const edges = db.createCollection("friends", {
  type: CollectionType.EDGE_COLLECTION
});

Example

interface Friend {
  startDate: number;
  endDate?: number;
}
const db = new Database();
const edges = db.createCollection<Friend>("friends", {
  type: CollectionType.EDGE_COLLECTION
});

Creates a new database with the given databaseName with the given options and returns a Database instance for that database.

Example

const db = new Database();
const info = await db.createDatabase("mydb", {
  users: [{ username: "root" }]
});
// the database has been created

Creates a new database with the given databaseName with the given users and returns a Database instance for that database.

Example

const db = new Database();
const info = await db.createDatabase("mydb", [{ username: "root" }]);
// the database has been created

Creates a new edge collection with the given collectionName and options, then returns an EdgeCollection instance for the new edge collection.

This is a convenience method for calling createCollection with options.type set to EDGE_COLLECTION.

Example

const db = new Database();
const edges = db.createEdgeCollection("friends");

Example

interface Friend {
  startDate: number;
  endDate?: number;
}
const db = new Database();
const edges = db.createEdgeCollection<Friend>("friends");

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.

Example

const db = new Database();
await db.createFunction(
  "ACME::ACCOUNTING::CALCULATE_VAT",
  "(price) => price * 0.19"
);
// Use the new function in an AQL query with template handler:
const cursor = await db.query(aql`
  FOR product IN products
  RETURN MERGE(
    { vat: ACME::ACCOUNTING::CALCULATE_VAT(product.price) },
    product
  )
`);
// cursor is a cursor for the query result

Creates a graph with the given graphName and edgeDefinitions, then returns a Graph instance for the new graph.

Creates a new ArangoDB user with the given password.

Example

const db = new Database();
const user = await db.createUser("steve", "hunter2");
// The user "steve" has been created

Creates a new ArangoDB user with the given options.

Example

const db = new Database();
const user = await db.createUser("steve", { passwd: "hunter2" });
// The user "steve" has been created

Creates a new View with the given viewName and options, then returns a View instance for the new View.

Example

const db = new Database();
const view = await db.createView("potatoes", { type: "arangosearch" });
// the ArangoSearch View "potatoes" now exists

Creates a new Database instance for the given databaseName that shares this database's connection pool.

See also new Database.

Example

const systemDb = new Database();
const myDb = system.database("my_database");

Fetches all databases from the server and returns an array of Database instances for those databases.

See also listDatabases and userDatabases.

Example

const db = new Database();
const names = await db.databases();
// databases is an array of databases

Retrieves a zip bundle containing the service files.

Returns a Buffer in node.js or Blob in the browser.

Example

const db = new Database();
const serviceBundle = await db.downloadService("/my-foxx");

Deletes the database with the given databaseName from the server.

Example

const db = new Database();
await db.dropDatabase("mydb");
// database "mydb" no longer exists

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

Example

const db = new Database();
await db.dropFunction("ACME::ACCOUNTING::CALCULATE_VAT");
// the function no longer exists

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

Collections can be specified as collection names (strings) or objects implementing the ArangoCollection interface: Collection, GraphVertexCollection, GraphEdgeCollection as well as (in TypeScript) DocumentCollection and EdgeCollection.

Note: The action function will be evaluated and executed on the server inside ArangoDB's embedded JavaScript environment and can not access any values other than those passed via the params option.

See the official ArangoDB documentation for the JavaScript @arangodb module for information about accessing the database from within ArangoDB's server-side JavaScript environment.

Example

const db = new Database();

const action = `
  function(params) {
    // This code will be executed inside ArangoDB!
    const { query } = require("@arangodb");
    return query\`
        FOR user IN _users
        FILTER user.age > ${params.age}
        RETURN u.user
      \`.toArray();
  }
`);

const result = await db.executeTransaction({
  read: ["_users"]
}, action, {
  params: { age: 12 }
});
// result contains the return value of the action

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

Collections can be specified as collection names (strings) or objects implementing the ArangoCollection interface: Collection, GraphVertexCollection, GraphEdgeCollection as well as (in TypeScript) DocumentCollection and EdgeCollection.

Note: The action function will be evaluated and executed on the server inside ArangoDB's embedded JavaScript environment and can not access any values other than those passed via the params option. See the official ArangoDB documentation for the JavaScript @arangodb module for information about accessing the database from within ArangoDB's server-side JavaScript environment.

Example

const db = new Database();

const action = `
  function(params) {
    // This code will be executed inside ArangoDB!
    const { query } = require("@arangodb");
    return query\`
        FOR user IN _users
        FILTER user.age > ${params.age}
        RETURN u.user
      \`.toArray();
  }
`);

const result = await db.executeTransaction(["_users"], action, {
  params: { age: 12 }
});
// result contains the return value of the action

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

The Collection can be specified as a collection name (string) or an object implementing the ArangoCollection interface: Collection, GraphVertexCollection, GraphEdgeCollection as well as (in TypeScript) DocumentCollection and EdgeCollection.

Note: The action function will be evaluated and executed on the server inside ArangoDB's embedded JavaScript environment and can not access any values other than those passed via the params option. See the official ArangoDB documentation for the JavaScript @arangodb module for information about accessing the database from within ArangoDB's server-side JavaScript environment.

Example

const db = new Database();

const action = `
  function(params) {
    // This code will be executed inside ArangoDB!
    const { query } = require("@arangodb");
    return query\`
        FOR user IN _users
        FILTER user.age > ${params.age}
        RETURN u.user
      \`.toArray();
  }
`);

const result = await db.executeTransaction("_users", action, {
  params: { age: 12 }
});
// result contains the return value of the action

Checks whether the database exists.

Example

const db = new Database();
const result = await db.exists();
// result indicates whether the database exists

Explains a database query using the given query.

See the aql template string handler for information about how to create a query string without manually defining bind parameters nor having to worry about escaping variables.

Example

const db = new Database();
const collection = db.collection("some-collection");
const explanation = await db.explain(aql`
  FOR doc IN ${collection}
  FILTER doc.flavor == "strawberry"
  RETURN doc._key
`);

Explains a database query using the given query.

See the aql template string handler for information about how to create a query string without manually defining bind parameters nor having to worry about escaping variables.

Example

const db = new Database();
const collection = db.collection("some-collection");
const explanation = await db.explain(
  aql`
    FOR doc IN ${collection}
    FILTER doc.flavor == "strawberry"
    RETURN doc._key
  `,
  { allPlans: true }
);

Explains a database query using the given query and bindVars.

See the aql template string handler for a safer and easier alternative to passing strings directly.

Example

const db = new Database();
const collection = db.collection("some-collection");
const explanation = await db.explain(
  `
    FOR doc IN @@collection
    FILTER doc.flavor == "strawberry"
    RETURN doc._key
  `,
  { "@collection": collection.name }
);

Explains a database query using the given query and bindVars.

See the aql template string handler for a safer and easier alternative to passing strings directly.

Example

const db = new Database();
const collection = db.collection("some-collection");
const explanation = await db.explain(
  `
    FOR doc IN @@collection
    FILTER doc.flavor == "strawberry"
    RETURN doc._key
  `,
  { "@collection": collection.name },
  { allPlans: true }
);

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

Example

const db = new Database();
const info = await db.get();
// the database exists

Retrieves information about a mounted service.

Example

const db = new Database();
const info = await db.getService("/my-service");
// info contains detailed information about the service

Retrieves information about the service's configuration options and their current values.

See also replaceServiceConfiguration and updateServiceConfiguration.

Example

const db = new Database();
const config = await db.getServiceConfiguration("/my-service");
for (const [key, option] of Object.entries(config)) {
  console.log(`${option.title} (${key}): ${option.current}`);
}

Retrieves information about the service's configuration options and their current values.

See also replaceServiceConfiguration and updateServiceConfiguration.

Example

const db = new Database();
const config = await db.getServiceConfiguration("/my-service", true);
for (const [key, value] of Object.entries(config)) {
  console.log(`${key}: ${value}`);
}

Retrieves information about the service's dependencies and their current mount points.

See also replaceServiceDependencies and updateServiceDependencies.

Example

const db = new Database();
const deps = await db.getServiceDependencies("/my-service");
for (const [key, dep] of Object.entries(deps)) {
  console.log(`${dep.title} (${key}): ${dep.current}`);
}

Retrieves information about the service's dependencies and their current mount points.

See also replaceServiceDependencies and updateServiceDependencies.

Example

const db = new Database();
const deps = await db.getServiceDependencies("/my-service", true);
for (const [key, value] of Object.entries(deps)) {
  console.log(`${key}: ${value}`);
}

Retrieves an Open API compatible Swagger API description object for the service installed at the given mount point.

Example

const db = new Database();
const spec = await db.getServiceDocumentation("/my-service");
// spec is a Swagger API description of the service

Retrieves the text content of the service's README or README.md file.

Returns undefined if no such file could be found.

Example

const db = new Database();
const readme = await db.getServiceReadme("/my-service");
if (readme !== undefined) console.log(readme);
else console.warn(`No README found.`)

Fetches the user data of a single ArangoDB user.

Example

const db = new Database();
const user = await db.getUser("steve");
// user is the user object for the user named "steve"

Fetches the given ArangoDB user's access level for the database, or the given collection in the given database.

Example

const db = new Database();
const accessLevel = await db.getUserAccessLevel("steve");
// The access level of the user "steve" has been fetched for the current
// database.

Example

const db = new Database();
const accessLevel = await db.getUserAccessLevel("steve", {
  database: "staging"
});
// The access level of the user "steve" has been fetched for the "staging"
// database.

Example

const db = new Database();
const accessLevel = await db.getUserAccessLevel("steve", {
  collection: "pokemons"
});
// The access level of the user "steve" has been fetched for the
// "pokemons" collection in the current database.

Example

const db = new Database();
const accessLevel = await db.getUserAccessLevel("steve", {
  database: "staging",
  collection: "pokemons"
});
// The access level of the user "steve" has been fetched for the
// "pokemons" collection in the "staging" database.

Example

const db = new Database();
const staging = db.database("staging");
const accessLevel = await db.getUserAccessLevel("steve", {
  database: staging
});
// The access level of the user "steve" has been fetched for the "staging"
// database.

Example

const db = new Database();
const staging = db.database("staging");
const accessLevel = await db.getUserAccessLevel("steve", {
  collection: staging.collection("pokemons")
});
// The access level of the user "steve" has been fetched for the
// "pokemons" collection in database "staging".

Fetches an object mapping names of databases to the access level of the given ArangoDB user for those databases.

Example

const db = new Database();
const accessLevels = await db.getUserDatabases("steve");
for (const [databaseName, accessLevel] of Object.entries(accessLevels)) {
  console.log(`${databaseName}: ${accessLevel}`);
}

Fetches an object mapping names of databases to the access level of the given ArangoDB user for those databases and the collections within each database.

Example

const db = new Database();
const accessLevels = await db.getUserDatabases("steve", true);
for (const [databaseName, obj] of Object.entries(accessLevels)) {
  console.log(`${databaseName}: ${obj.permission}`);
  for (const [collectionName, accessLevel] of Object.entries(obj.collections)) {
    console.log(`${databaseName}/${collectionName}: ${accessLevel}`);
  }
}

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

Example

const db = new Database();
const graph = db.graph("some-graph");

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

See also listGraphs.

Example

const db = new Database();
const graphs = await db.graphs();
// graphs is an array of Graph instances

Installs a new service.

Example

const db = new Database();
// Using a node.js file stream as source
const source = fs.createReadStream("./my-foxx-service.zip");
const info = await db.installService("/hello", source);

Example

const db = new Database();
// Using a node.js Buffer as source
const source = fs.readFileSync("./my-foxx-service.zip");
const info = await db.installService("/hello", source);

Example

const db = new Database();
// Using a File (Blob) from a browser file input
const element = document.getElementById("my-file-input");
const source = element.files[0];
const info = await db.installService("/hello", source);

Kills a running query with the given queryId.

See also listRunningQueries.

Example

const db = new Database();
const queries = await db.listRunningQueries();
await Promise.all(queries.map(
  async (query) => {
    if (query.state === "executing") {
      await db.killQuery(query.id);
    }
  }
));

Fetches all Analyzers visible in the database and returns an array of Analyzer descriptions.

See also analyzers.

Example

const db = new Database();
const analyzers = await db.listAnalyzers();
// analyzers is an array of Analyzer descriptions

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

See also collections.

Example

const db = new Database();
const collections = await db.listCollections();
// collections is an array of collection descriptions
// not including system collections

Example

const db = new Database();
const collections = await db.listCollections(false);
// collections is an array of collection descriptions
// including system collections

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

See also databases and listUserDatabases.

Example

const db = new Database();
const names = await db.listDatabases();
// databases is an array of database names

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

Example

const db = new Database();
const functions = await db.listFunctions();
const names = functions.map(fn => fn.name);

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

See also graphs.

Example

const db = new Database();
const graphs = await db.listGraphs();
// graphs is an array of graph descriptions

Fetches a list of information for all currently running queries.

See also listSlowQueries and killQuery.

Example

const db = new Database();
const queries = await db.listRunningQueries();

Retrieves a list of scripts defined in the service manifest's "scripts" section mapped to their human readable representations.

Example

const db = new Database();
const scripts = await db.listServiceScripts("/my-service");
for (const [name, title] of Object.entries(scripts)) {
  console.log(`${name}: ${title}`);
}

Fetches a list of all installed service.

Example

const db = new Database();
const services = await db.listServices();

Example

const db = new Database();
const services = await db.listServices(false); // all services

Fetches a list of information for all recent slow queries.

See also listRunningQueries and clearSlowQueries.

Example

const db = new Database();
const queries = await db.listSlowQueries();
// Only works if slow query tracking is enabled

Fetches all active transactions from the database and returns an array of transaction descriptions.

See also transactions.

Example

const db = new Database();
const transactions = await db.listTransactions();
// transactions is an array of transaction descriptions

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

See also userDatabases and listDatabases.

Example

const db = new Database();
const names = await db.listUserDatabases();
// databases is an array of database names

Fetches all ArangoDB users visible to the authenticated user and returns an array of user objects.

Example

const db = new Database();
const users = await db.listUsers();
// users is an array of user objects

Fetches all Views from the database and returns an array of View descriptions.

See also views.

Example

const db = new Database();

const views = await db.listViews();
// views is an array of View descriptions

Validates the given database credentials and exchanges them for an authentication token, then uses the authentication token for future requests and returns it.

Example

const db = new Database();
await db.login("admin", "hunter2");
// with an authentication token for the "admin" user.

Parses the given query and returns the result.

See the aql template string handler for information about how to create a query string without manually defining bind parameters nor having to worry about escaping variables.

Example

const db = new Database();
const collection = db.collection("some-collection");
const ast = await db.parse(aql`
  FOR doc IN ${collection}
  FILTER doc.flavor == "strawberry"
  RETURN doc._key
`);