Writing queries

    Any values passed via interpolation (i.e. using the ${expression} syntax)are passed to ArangoDB as,so you don’t have to worry about escaping them in order to protect againstinjection attacks in user-supplied data.

    The result of the executed query isan ArangoDB array cursor.You can extract all query results using the toArray() method orstep through the result set using the next() method.

    You can also consume a cursor with a for-loop:

    1. const cursor = query`
    2.   FOR i IN 1..5
    3.   RETURN i
    4. `;
    5. for (const item of cursor) {
    6.   console.log(item);
    7. }

    When you generallywant to avoid hardcoding exact collection names. But if you pass acollection name directly to a query it will be treated as a string:

    1. // THIS DOES NOT WORK
    2. const users = module.context.collectionName("users");
    3. // e.g. "myfoxx_users"
    4. const admins = query`
    5.   FOR user IN ${users}
    6.   FILTER user.isAdmin
    7.   RETURN user
    8. `.toArray(); // ERROR

    Note that you don’t need to use any different syntax to usea collection in a query, but you do need to make sure the collection isan actual ArangoDB collection object rather than a plain string.

    In addition to the query template tag, ArangoDB also providesthe aql template tag, which only generates a query objectbut doesn’t execute it:

    1. const { db, aql } = require("@arangodb");
    2. const max = 7;
    3. const query = aql`
    4.   FOR i IN 1..${max}
    5.   RETURN i
    6. `;

    You can also use the db._query method to execute queries usingplain strings and passing the bind parameters as an object:

    1. // Note the lack of a tag, this is a normal string
    3.   FOR user IN @@users
    4.   FILTER user.isAdmin
    5.   RETURN user
    6. `;
    7. const admins = db._query(query, {
    8.   // We're passing a string instead of a collection
    9.   // because this is an explicit collection bind parameter
    10.   // using the AQL double-at notation
    11.   "@users": module.context.collectionName("users")
    12. }).toArray();

    Note that when using plain strings as queries ArangoDB providesno safeguards to prevent accidental AQL injections:

    If you need to insert AQL snippets dynamically, you can still usethe query template tag by using the aql.literal helper function tomark the snippet as a raw AQL fragment:

    1. const filter = aql.literal(
    2.   adminsOnly ? 'FILTER user.isAdmin' : ''
    3. );
    4. const result = query`
    5.   FOR user IN ${users}
    6.   ${filter}
    7.   RETURN user
    8. `.toArray();

    Both the query and aql template tags understand fragments markedwith the aql.literal helper and inline them directly into the queryinstead of converting them to bind parameters.

    Note that because the aql.literal helper takes a raw string as argumentthe same security implications apply to it as when writing raw AQL queriesusing plain strings:

    1. // Malicious user input where you might expect a condition
    2. const evil = "true REMOVE u IN myfoxx_users";
    4. const filter = aql.literal(`FILTER ${evil}`);
    5. const result = query`
    6.   ${filter}
    7.   RETURN user
    8. `.toArray();
    9. // Actual query executed by the code:
    10. // FOR user IN myfoxx_users
    11. // FILTER true
    12. // REMOVE user IN myfoxx_users
    13. // RETURN user

    A typical scenario that might result in an exploit like this is takingarbitrary strings from a search UI to filter or sort results by a field name.Make sure to restrict what values you accept.

    However to help testability and make the queries more reusable,it’s often a good idea to move them out of your request handlersinto separate functions, e.g.:

    1. // in queries/get-user-emails.js
    2. "use strict";
    3. const { query, aql } = require("@arangodb");
    4. const users = module.context.collection("users");
    5. module.exports = (activeOnly = true) => query`
    6.   FOR user IN ${users}
    7.   ${aql.literal(activeOnly ? "FILTER user.active" : "")}
    8.   RETURN user.email
    9. `.toArray();
    11. // in your router
    12. const getUserEmails = require("../queries/get-user-emails");
    14. router.get("/active-emails", (req, res) => {
    15.   res.json(getUserEmails(true));
    16. });
    17. router.get("/all-emails", (req, res) => {