Namespace aql

Note: Nesting aql template strings is a much safer alternative for most use cases. This low-level helper function only exists to complement the aql tag when constructing complex queries from dynamic arrays of query fragments.

example

const users = db.collection("users");
const filters = [];
if (adminsOnly) filters.push(aql`FILTER user.admin`);
if (activeOnly) filters.push(aql`FILTER user.active`);
const result = await db.query(aql`
  FOR user IN ${users}
  ${aql.join(filters)}
  RETURN user
`);

example

const users = db.collection("users");
const keys = ["jreyes", "ghermann"];

// BAD! NEEDLESSLY COMPLEX!
const docs = keys.map(key => aql`DOCUMENT(${users}, ${key}`));
const result = await db.query(aql`
  FOR user IN [
    ${aql.join(docs, ", ")}
  ]
  RETURN user
`);
// Query:
//   FOR user IN [
//     DOCUMENT(@@value0, @value1), DOCUMENT(@@value0, @value2)
//   ]
//   RETURN user
// Bind parameters:
//   @value0 -> "users"
//   value1 -> "jreyes"
//   value2 -> "ghermann"

// GOOD! MUCH SIMPLER!
const result = await db.query(aql`
  FOR key IN ${keys}
  LET user = DOCUMENT(${users}, key)
  RETURN user
`);
// Query:
//   FOR user IN @value0
//   LET user = DOCUMENT(@@value1, key)
//   RETURN user
// Bind parameters:
//   value0 -> ["jreyes", "ghermann"]
//   @value1 -> "users"

Note: Nesting aql template strings is a much safer alternative for most use cases. This low-level helper function only exists to help with rare edge cases where a trusted AQL query fragment must be read from a string (e.g. when reading query fragments from JSON) and should only be used as a last resort.

example

// BAD! DO NOT DO THIS!
const sortDirection = aql.literal('ASC');

// GOOD! DO THIS INSTEAD!
const sortDirection = aql`ASC`;

example

// BAD! DO NOT DO THIS!
const filterColor = aql.literal('FILTER d.color == "green"');
const result = await db.query(aql`
  FOR d IN some-collection
  ${filterColor}
  RETURN d
`);

// GOOD! DO THIS INSTEAD!
const color = "green";
const filterColor = aql`FILTER d.color === ${color}`;
const result = await db.query(aql`
  FOR d IN some-collection
  ${filterColor}
  RETURN d
`);

example

// WARNING: We explicitly trust the environment variable to be safe!
const filter = aql.literal(process.env.FILTER_STATEMENT);
const users = await db.query(aql`
  FOR user IN users
  ${filter}
  RETURN user
`);