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

• query: string | AqlQuery | AqlLiteral

  An AQL query as a string or AQL query object or AQL literal. If the query is an AQL query object, the second argument is treated as the opts argument instead of bindVars.

• bindVars: Object (optional)

  An object defining the variables to bind the query to.

• opts: Object (optional)

  Additional parameter object that will be passed to the query API. Possible keys are count and options (explained below)

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).

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

• query: string | AqlQuery | AqlLiteral

  An AQL query as a string or AQL query object or AQL literal. If the query is an AQL query object, the second argument is treated as the opts argument instead of bindVars.

• bindVars: Object (optional)

  An object defining the variables to bind the query to.

• opts: Object (optional)

  • optimizer: Object (optional)

    An object with a single property rules, a string array of optimizer rules to be used for the query.

  • maxNumberOfPlans: number (optional)

    Maximum number of plans that the optimizer is allowed to generate. Setting this to a low value limits the amount of work the optimizer does.

  • allPlans: boolean (Default: false)

    If set to true, all possible execution plans will be returned as the plans property. Otherwise only the optimal execution plan will be returned as the plan property.

database.parse

async database.parse(query): ParseResult

Parses the given query and returns the result.

Arguments

• query: string | AqlQuery | AqlLiteral

  An AQL query as a string or AQL query object or AQL literal. If the query is an AQL query object, its bindVars (if any) will be ignored.

database.queryTracking

async database.queryTracking(): QueryTrackingProperties

Fetches the query tracking properties.

database.setQueryTracking

async database.setQueryTracking(props): void

Modifies the query tracking properties.

Arguments

• props: Partial<QueryTrackingProperties>

  Query tracking properties with new values to set.

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

• queryId: string

  The ID of a currently running query.