Function aql

Template string handler (template tag) for AQL queries.

The aql tag can be used to write complex AQL queries as multi-line strings without having to worry about bindVars and the distinction between collections and regular parameters.

Tagged template strings will return an AqlQuery object with query and bindVars attributes reflecting any interpolated values.

Any ArangoCollection instance used in a query string will be recognized as a collection reference and generate an AQL collection bind parameter instead of a regular AQL value bind parameter.

Note: you should always use the aql template tag when writing dynamic AQL queries instead of using untagged (normal) template strings. Untagged template strings will inline any interpolated values and return a plain string as result. The aql template tag will only inline references to the interpolated values and produce an AQL query object containing both the query and the values. This prevents most injection attacks when using untrusted values in dynamic queries.

Example

// Some user-supplied string that may be malicious
const untrustedValue = req.body.email;

// Without aql tag: BAD! DO NOT DO THIS!
const badQuery = `
  FOR user IN users
  FILTER user.email == "${untrustedValue}"
  RETURN user
`;
// e.g. if untrustedValue is '" || user.admin == true || "':
// Query:
//   FOR user IN users
//   FILTER user.email == "" || user.admin == true || ""
//   RETURN user

// With the aql tag: GOOD! MUCH SAFER!
const betterQuery = aql`
  FOR user IN users
  FILTER user.email == ${untrustedValue}
  RETURN user
`;
// Query:
//   FOR user IN users
//   FILTER user.email == @value0
//   RETURN user
// Bind parameters:
//   value0 -> untrustedValue

Example

const collection = db.collection("some-collection");
const minValue = 23;
const result = await db.query(aql`
  FOR d IN ${collection}
  FILTER d.num > ${minValue}
  RETURN d
`);

// Equivalent raw query object
const result2 = await db.query({
  query: `
    FOR d IN @@collection
    FILTER d.num > @minValue
    RETURN d
  `,
  bindVars: {
    "@collection": collection.name,
    minValue: minValue
  }
});

Example

const collection = db.collection("some-collection");
const color = "green";
const filter = aql`FILTER d.color == ${color}'`;
const result = await db.query(aql`
  FOR d IN ${collection}
  ${filter}
  RETURN d
`);