Options
All
  • Public
  • Public/Protected
  • All
Menu

Namespace aql

Callable

  • 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
`);

    Parameters

    • templateStrings: TemplateStringsArray
    • Rest ...args: AqlValue[]

    Returns GeneratedAqlQuery

Index

Functions

Functions

join

  • Constructs AqlQuery objects from an array of arbitrary values.

    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"

    Parameters

    • values: AqlValue[]

      Array of values to join. These values will behave exactly like values interpolated in an aql template string.

    • Default value sep: string = " "

      Seperator to insert between values. This value will behave exactly like a value passed to aql.literal, i.e. it will be inlined as-is, rather than being converted into a bind parameter.

    Returns GeneratedAqlQuery

literal

  • Marks an arbitrary scalar value (i.e. a string, number or boolean) as safe for being inlined directly into AQL queries when used in an aql template string, rather than being converted into a bind parameter.

    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
`);

    Parameters

    • value: string | number | boolean | AqlLiteral | null | undefined

    Returns AqlLiteral

Generated using TypeDoc