Options
All
  • Public
  • Public/Protected
  • All
Menu

Module aql

import { aql } from "arangojs/aql";

The "aql" module provides the aql template string handler and helper functions, as well as associated types and interfaces for TypeScript.

The aql function and namespace is also re-exported by the "index" module.

Index

Namespaces

Interfaces

Type aliases

Functions

Type aliases

AqlValue

AqlValue: ArangoCollection | View | Graph | GeneratedAqlQuery | AqlLiteral | string | number | boolean | null | undefined | Record<string, unknown> | any[]

A value that can be used in an AQL template string or passed to an AQL helper function.

Functions

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

    Parameters

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

    Returns GeneratedAqlQuery

isAqlLiteral

  • isAqlLiteral(literal: any): literal is AqlLiteral
  • Indicates whether the given value is an AqlLiteral.

    Parameters

    • literal: any

      A value that might be an AqlLiteral.

    Returns literal is AqlLiteral

isAqlQuery

  • isAqlQuery(query: any): query is AqlQuery
  • Indicates whether the given value is an AqlQuery.

    Parameters

    • query: any

      A value that might be an AqlQuery.

    Returns query is AqlQuery

Generated using TypeDoc