WITH operation in AQL

Reading implicitly from a collections means that the collections are not specified explicitly in language constructs like the following:

• FOR ... IN collection
• INSERT ... INTO collection
• UPDATE ... IN collection
• GRAPH "graph-name" (via the graph definition)

Instead, the collections are only known at runtime of the query. Such dynamic collection access is invisible to the AQL query parser at query compile time. Dynamic access is possible via the DOCUMENT() function as well as with graph traversals (in particular the variant using collection sets), because edges may point to arbitrary vertex collections. Additionally, if you specify the start vertex of a traversal using a string, its collection needs to be declared as well.

Collections that are explicitly used in a query are automatically detected by the AQL query parser. Any additional collections that will be involved in the query but cannot be detected automatically by the query parser can be manually specified using a WITH statement. It is recommended to declare all collections that the DOCUMENT() function or graph traversals using collection sets might possibly access to avoid occasional query failures.

Syntax

WITH collection1 [, collection2 [, ... collectionN ] ]

WITH is also a keyword that is used in other contexts, for example in UPDATE statements. To declare additional collections, you must place the WITH keyword at the very start of the query.

Usage

The WITH operation is only required if you use a cluster deployment and only for AQL queries that dynamically read from vertex collections as part of graph traversals.

You can enable the --query.require-with startup option to make single server instances require WITH declarations like cluster deployments to ease development, see Requiring WITH statements.

Dynamic access via the DOCUMENT() function does not require you to list the involved collections. Using named graphs in traversals (GRAPH "graph-name") does not require it either, assuming that all vertices are in collections that are part of the graph, as enforced by the Graph API. That means, it is only necessary for traversals using anonymous graphs / collection sets.

The following example query specifies an edge collection usersHaveManagers to perform a graph traversal. It is the only explicitly specified collection in the query. It does not need to be declared using the WITH operation.

However, the involved vertex collections need to be declared. In this example, the start vertex is specified as a string and it is stored in the users collections. Furthermore, the edges of the edge collection reference vertices of a collection called managers. Both collections are declared at the beginning of the query using the WITH operation:

WITH users, managers
FOR v, e, p IN 1..2 OUTBOUND 'users/1' usersHaveManagers
  RETURN { v, e, p }