Queries

These functions implements the HTTP API for single round-trip AQL queries as well as the HTTP API for managing queries.

For collection-specific queries see Simple Queries.

database.query

async database.query(query, [bindVars,] [opts]): Cursor

Performs a database query using the given query and bindVars, then returns a new Cursor instance for the result list.

Arguments

If opts.count is set to true, the cursor will have a count property set to the query result count.

Possible key options in opts.options include: failOnWarning, cache, profile or skipInaccessibleCollections. For a complete list of query settings please reference the setting options.

Additionally if opts.allowDirtyRead is set to true, the request will explicitly permit ArangoDB to return a potentially dirty or stale result and arangojs will load balance the request without distinguishing between leaders and followers. Note that dirty reads are only supported for read-only queries (e.g. not using INSERT, UPDATE, REPLACE or REMOVE expressions).

Note: Dirty reads were introduced in ArangoDB 3.4 and are not supported by earlier versions of ArangoDB.

Additionally opts.timeout can be set to a non-negative number to force the request to be cancelled after that amount of milliseconds. Note that this will simply close the connection and not result in the actual query being cancelled in ArangoDB, the query will still be executed to completion and continue to consume resources in the database or cluster.

If query is an object with query and bindVars properties, those will be used as the values of the respective arguments instead.

Examples

const db = new Database();
const active = true;

// Using the aql template tag
const cursor = await db.query(aql`
  FOR u IN _users
  FILTER u.authData.active == ${active}
  RETURN u.user
`);
// cursor is a cursor for the query result

// -- or --

// Old-school JS with explicit bindVars:
db.query("FOR u IN _users FILTER u.authData.active == @active RETURN u.user", {
  active: true,
}).then(function (cursor) {
  // cursor is a cursor for the query result
});

aql

aql(strings, ...args): Object

Template string handler (aka template tag) for AQL queries. Converts a template string to an object that can be passed to database.query by converting arguments to bind variables.

Note: If you want to pass a collection name as a bind variable, you need to pass a Collection instance (e.g. what you get by passing the collection name to db.collection) instead. If you see the error "array expected as operand to FOR loop", you’re likely passing a collection name instead of a collection instance.

Examples

const userCollection = db.collection("_users");
const role = "admin";

const query = aql`
  FOR user IN ${userCollection}
  FILTER user.role == ${role}
  RETURN user
`;

// -- is equivalent to --
const query = {
  query: "FOR user IN @@value0 FILTER user.role == @value1 RETURN user",
  bindVars: { "@value0": userCollection.name, value1: role },
};

Note how the aql template tag automatically handles collection references (@@value0 instead of @value0) for us so you don’t have to worry about counting at-symbols.

Because the aql template tag creates actual bindVars instead of inlining values directly, it also avoids injection attacks via malicious parameters:

// malicious user input
const email = '" || (FOR x IN secrets REMOVE x IN secrets) || "';

// DON'T do this!
const query = `
  FOR user IN users
  FILTER user.email == "${email}"
  RETURN user
`;
// FILTER user.email == "" || (FOR x IN secrets REMOVE x IN secrets) || ""

// instead do this!
const query = aql`
  FOR user IN users
  FILTER user.email == ${email}
  RETURN user
`;
// FILTER user.email == @value0

database.explain

async database.explain(query, [bindVars,] [opts]): ExplainResult

Explains a database query using the given query and bindVars and returns one or more plans.

Arguments

database.parse

async database.parse(query): ParseResult

Parses the given query and returns the result.

Arguments

database.queryTracking

async database.queryTracking(): QueryTrackingProperties

Fetches the query tracking properties.

database.setQueryTracking

async database.setQueryTracking(props): void

Modifies the query tracking properties.

Arguments

database.listRunningQueries

async database.listRunningQueries(): Array<QueryStatus>

Fetches a list of information for all currently running queries.

database.listSlowQueries

async database.listSlowQueries(): Array<SlowQueryStatus>

Fetches a list of information for all recent slow queries.

database.clearSlowQueries

async database.clearSlowQueries(): void

Clears the list of recent slow queries.

database.killQuery

async database.killQuery(queryId): void

Kills a running query with the given ID.

Arguments