DOC-816 | Deduced vertex collections from named graphs

site/content/3.12/aql/graphs/all-shortest-paths.md

@@ -117,6 +117,56 @@ All collections in the list that do not specify their own direction use the
 direction defined after `IN` (here: `OUTBOUND`). This allows using a different
 direction for each collection in your path search.
 
+### Graph path searches in a cluster
+
+Due to the nature of graphs, edges may reference nodes from arbitrary
+collections. Following the paths can thus involve documents from various
+collections and it is not possible to predict which are visited in a
+traversal. Which collections need to be loaded by the graph engine can only be
+determined at run time.
+
+Use the [`WITH` operation](../high-level-operations/with.md) to specify the
+node collections you expect to be involved. This is required for traversals
+using collection sets in cluster deployments. Declare the collection of the
+start node as well if it's not declared already (like by a `FOR` loop).
+
+{{< tip >}}
+From v3.12.6 onward, node collections are automatically deduced for graph
+queries using collection sets / anonymous graphs if there is a named graph with
+a matching edge collection in its edge definitions.
+
+For example, suppose you have two node collections, `person` and `movie`, and
+an `acts_in` edge collection that connects them. If you want to run a path search
+query that starts (and ends) at a person that you specify with its document ID,
+you need to declare both node collections at the beginning of the query:
+
+```aql
+WITH person, movie
+FOR p IN ANY ALL_SHORTEST_PATHS "person/1544" TO "person/52560" acts_in
+  RETURN p.vertices[*].label
+```
+
+However, if there is a named graph that includes an edge definition for the
+`acts_in` edge collection, with `person` as the _from_ collection and `movie`
+as the _to_ collection, you can omit `WITH person, movie`. That is, if you
+specify `acts_in` as an edge collection in an anonymous graph query, all
+named graphs are checked for this edge collection, and if there is a matching
+edge definition, its node collections are automatically added as data sources to
+the query.
+
+```aql
+FOR p IN ANY ALL_SHORTEST_PATHS "person/1544" TO "person/52560" acts_in
+  RETURN p.vertices[*].label
+
+// Chris Rock --> Dogma <-- Ben Affleck --> Surviving Christmas <-- Jennifer Morrison
+// Chris Rock --> The Longest Yard <-- Rob Schneider --> Big Stan <-- Jennifer Morrison
+// Chris Rock --> Down to Earth <-- John Cho --> Star Trek <-- Jennifer Morrison
+```
+
+You can still declare collections manually, in which case they are added as
+data sources in addition to automatically deduced collections.
+{{< /tip >}}
+
 ## Examples
 
 Load an example graph to get a named graph that reflects some possible

site/content/3.12/aql/graphs/k-paths.md

@@ -188,6 +188,57 @@ All collections in the list that do not specify their own direction use the
 direction defined after `IN` (here: `OUTBOUND`). This allows to use a different
 direction for each collection in your path search.
 
+### Graph path searches in a cluster
+
+Due to the nature of graphs, edges may reference nodes from arbitrary
+collections. Following the paths can thus involve documents from various
+collections and it is not possible to predict which are visited in a
+traversal. Which collections need to be loaded by the graph engine can only be
+determined at run time.
+
+Use the [`WITH` operation](../high-level-operations/with.md) to specify the
+node collections you expect to be involved. This is required for traversals
+using collection sets in cluster deployments. Declare the collection of the
+start node as well if it's not declared already (like by a `FOR` loop).
+
+{{< tip >}}
+From v3.12.6 onward, node collections are automatically deduced for graph
+queries using collection sets / anonymous graphs if there is a named graph with
+a matching edge collection in its edge definitions.
+
+For example, suppose you have two node collections, `person` and `movie`, and
+an `acts_in` edge collection that connects them. If you want to run a path search
+query that starts (and ends) at a person that you specify with its document ID,
+you need to declare both node collections at the beginning of the query:
+
+```aql
+WITH person, movie
+FOR p IN 4 ANY K_PATHS "person/1544" TO "person/52560" acts_in
+  LIMIT 2
+  RETURN p.vertices[*].label
+```
+
+However, if there is a named graph that includes an edge definition for the
+`acts_in` edge collection, with `person` as the _from_ collection and `movie`
+as the _to_ collection, you can omit `WITH person, movie`. That is, if you
+specify `acts_in` as an edge collection in an anonymous graph query, all
+named graphs are checked for this edge collection, and if there is a matching
+edge definition, its node collections are automatically added as data sources to
+the query.
+
+```aql
+FOR p IN 4 ANY K_PATHS "person/1544" TO "person/52560" acts_in
+  LIMIT 2
+  RETURN p.vertices[*].label
+
+// Chris Rock --> Dogma <-- Ben Affleck --> Surviving Christmas <-- Jennifer Morrison
+// Chris Rock --> The Longest Yard <-- Rob Schneider --> Big Stan <-- Jennifer Morrison
+```
+
+You can still declare collections manually, in which case they are added as
+data sources in addition to automatically deduced collections.
+{{< /tip >}}
+
 ## Examples
 
 You can load the `kShortestPathsGraph` example graph to get a named graph that

site/content/3.12/aql/graphs/k-shortest-paths.md

@@ -186,6 +186,57 @@ All collections in the list that do not specify their own direction use the
 direction defined after `IN` (here: `OUTBOUND`). This allows to use a different
 direction for each collection in your path search.
 
+### Graph path searches in a cluster
+
+Due to the nature of graphs, edges may reference nodes from arbitrary
+collections. Following the paths can thus involve documents from various
+collections and it is not possible to predict which are visited in a
+traversal. Which collections need to be loaded by the graph engine can only be
+determined at run time.
+
+Use the [`WITH` operation](../high-level-operations/with.md) to specify the
+node collections you expect to be involved. This is required for traversals
+using collection sets in cluster deployments. Declare the collection of the
+start node as well if it's not declared already (like by a `FOR` loop).
+
+{{< tip >}}
+From v3.12.6 onward, node collections are automatically deduced for graph
+queries using collection sets / anonymous graphs if there is a named graph with
+a matching edge collection in its edge definitions.
+
+For example, suppose you have two node collections, `person` and `movie`, and
+an `acts_in` edge collection that connects them. If you want to run a path search
+query that starts (and ends) at a person that you specify with its document ID,
+you need to declare both node collections at the beginning of the query:
+
+```aql
+WITH person, movie
+FOR p IN ANY K_SHORTEST_PATHS "person/1544" TO "person/52560" acts_in
+  LIMIT 2
+  RETURN p.vertices[*].label
+```
+
+However, if there is a named graph that includes an edge definition for the
+`acts_in` edge collection, with `person` as the _from_ collection and `movie`
+as the _to_ collection, you can omit `WITH person, movie`. That is, if you
+specify `acts_in` as an edge collection in an anonymous graph query, all
+named graphs are checked for this edge collection, and if there is a matching
+edge definition, its node collections are automatically added as data sources to
+the query.
+
+```aql
+FOR p IN ANY K_SHORTEST_PATHS "person/1544" TO "person/52560" acts_in
+  LIMIT 2
+  RETURN p.vertices[*].label
+
+// Chris Rock --> Dogma <-- Ben Affleck --> Surviving Christmas <-- Jennifer Morrison
+// Chris Rock --> The Longest Yard <-- Rob Schneider --> Big Stan <-- Jennifer Morrison
+```
+
+You can still declare collections manually, in which case they are added as
+data sources in addition to automatically deduced collections.
+{{< /tip >}}
+
 ## Examples
 
 You can load the `kShortestPathsGraph` example graph to get a named graph that

site/content/3.12/aql/graphs/shortest-path.md

@@ -145,6 +145,54 @@ All collections in the list that do not specify their own direction use the
 direction defined after `IN` (here: `OUTBOUND`). This allows you to use a different
 direction for each collection in your path search.
 
+### Graph path searches in a cluster
+
+Due to the nature of graphs, edges may reference nodes from arbitrary
+collections. Following the paths can thus involve documents from various
+collections and it is not possible to predict which are visited in a
+traversal. Which collections need to be loaded by the graph engine can only be
+determined at run time.
+
+Use the [`WITH` operation](../high-level-operations/with.md) to specify the
+node collections you expect to be involved. This is required for traversals
+using collection sets in cluster deployments. Declare the collection of the
+start node as well if it's not declared already (like by a `FOR` loop).
+
+{{< tip >}}
+From v3.12.6 onward, node collections are automatically deduced for graph
+queries using collection sets / anonymous graphs if there is a named graph with
+a matching edge collection in its edge definitions.
+
+For example, suppose you have two node collections, `person` and `movie`, and
+an `acts_in` edge collection that connects them. If you want to run a path search
+query that starts (and ends) at a person that you specify with its document ID,
+you need to declare both node collections at the beginning of the query:
+
+```aql
+WITH person, movie
+FOR v IN ANY SHORTEST_PATH "person/1544" TO "person/52560" acts_in
+  RETURN v.label
+```
+
+However, if there is a named graph that includes an edge definition for the
+`acts_in` edge collection, with `person` as the _from_ collection and `movie`
+as the _to_ collection, you can omit `WITH person, movie`. That is, if you
+specify `acts_in` as an edge collection in an anonymous graph query, all
+named graphs are checked for this edge collection, and if there is a matching
+edge definition, its node collections are automatically added as data sources to
+the query.
+
+```aql
+FOR v,e,p IN 1..1 OUTBOUND "person/1544" acts_in
+  RETURN v.label
+
+// Chris Rock --> Dogma <-- Ben Affleck --> Surviving Christmas <-- Jennifer Morrison
+```
+
+You can still declare collections manually, in which case they are added as
+data sources in addition to automatically deduced collections.
+{{< /tip >}}
+
 ## Conditional shortest path
 
 The `SHORTEST_PATH` computation only finds an unconditioned shortest path.

site/content/3.12/aql/graphs/traversals.md

@@ -342,9 +342,50 @@ collections and it is not possible to predict which are visited in a
 traversal. Which collections need to be loaded by the graph engine can only be
 determined at run time.
 
-Use the [`WITH` statement](../high-level-operations/with.md) to specify the collections you
-expect to be involved. This is required for traversals using collection sets
-in cluster deployments.
+Use the [`WITH` operation](../high-level-operations/with.md) to specify the
+node collections you expect to be involved. This is required for traversals
+using collection sets in cluster deployments. Declare the collection of the
+start node as well if it's not declared already (like by a `FOR` loop).
+
+{{< tip >}}
+From v3.12.6 onward, node collections are automatically deduced for graph
+queries using collection sets / anonymous graphs if there is a named graph with
+a matching edge collection in its edge definitions.
+
+For example, suppose you have two node collections, `person` and `movie`, and
+an `acts_in` edge collection that connects them. If you want to run a traversal
+query that starts at a person that you specify with its document ID,
+you need to declare both node collections at the beginning of the query:
+
+```aql
+WITH person, movie
+FOR v IN 1 OUTBOUND "person/1544" acts_in
+  LIMIT 3
+  RETURN v.label
+```
+
+However, if there is a named graph that includes an edge definition for the
+`acts_in` edge collection, with `person` as the _from_ collection and `movie`
+as the _to_ collection, you can omit `WITH person, movie`. That is, if you
+specify `acts_in` as an edge collection in an anonymous graph query, all
+named graphs are checked for this edge collection, and if there is a matching
+edge definition, its node collections are automatically added as data sources to
+the query.
+
+```aql
+FOR v, IN 0..1 OUTBOUND "person/1544" acts_in
+  LIMIT 4
+  RETURN v.label
+
+// Chris Rock
+// A.I. Artificial Intelligence
+// Lethal Weapon 4
+// Madagascar
+```
+
+You can still declare collections manually, in which case they are added as
+data sources in addition to automatically deduced collections.
+{{< /tip >}}
 
 ## Pruning
 

site/content/3.12/release-notes/version-3.12/whats-new-in-3-12.md

@@ -1293,6 +1293,50 @@ Indexes used:
  10   idx_1836452431376941056   persistent   coll   
 ```
 
+### Deduction of node collection for graph queries
+
+<small>Introduced in: v3.12.6</small>
+
+AQL graph traversals and path searches using anonymous graphs / collection sets
+require that you declare all involved node collections upfront for cluster
+deployments. That is, you need to use the `WITH` operation to list the collections
+edges may point to, as well as the collection of the start node if not declared
+otherwise. This also applies to single servers if the `--query.require-with`
+startup option is enabled for parity between both deployment modes.
+
+For example, assume you have two node collections, `person` and `movie`, and
+edges pointing from one to the other stored in an `acts_in` edge collection.
+If you want to run a traversal query starting from a person that you specify
+with its document ID, you need to declare both node collections at the
+beginning of the query:
+
+```aql
+WITH person, movie
+FOR v IN 0..1 OUTBOUND "person/1544" acts_in
+  LIMIT 4
+  RETURN v.label
+```
+
+From v3.12.6 onward, the node collections can be automatically inferred if there
+is a named graph using the same edge collection(s).
+
+For example, assume there is a named graph that includes an edge definition for
+the `acts_in` edge collection, with `person` as the _from_ collection and `movie`
+as the _to_ collection. If you now specify `acts_in` as an edge collection in
+an anonymous graph query, all named graphs are checked for this edge collection,
+and if there is a matching edge definition, its node collections are automatically
+added as data sources to the query. You no longer have to manually declare the
+`person` and `movie` collections:
+
+```aql
+FOR v IN 0..1 OUTBOUND "person/1544" acts_in
+  LIMIT 4
+  RETURN v.label
+```
+
+You can still declare collections manually, in which case they are added as
+data sources in addition to automatically deduced collections.
+
 ## Indexing
 
 ### Multi-dimensional indexes

site/content/3.13/aql/graphs/all-shortest-paths.md

@@ -117,6 +117,58 @@ All collections in the list that do not specify their own direction use the
 direction defined after `IN` (here: `OUTBOUND`). This allows using a different
 direction for each collection in your path search.
 
+### Graph path searches in a cluster
+
+Due to the nature of graphs, edges may reference nodes from arbitrary
+collections. Following the paths can thus involve documents from various
+collections and it is not possible to predict which are visited in a path
+search - unless you use named graphs that define all node and edge collections
+that belong to them and the graph data is consistent.
+
+If you use anonymous graphs / collection sets for graph queries, which node
+collections need to be loaded by the graph engine can deduced automatically if
+there is a named graph with a matching edge collection in its edge definitions
+(introduced in v3.12.6). Edge collections are always declared explicitly in
+queries, directly or via referencing a named graph.
+
+Without a named graph, the involved node collections can only be determined at
+run time. Use the [`WITH` operation](../high-level-operations/with.md) to
+declare the node collections upfront. This is required for path searches
+using collection sets in cluster deployments (if there is no named graph to
+deduce the node collections from). Declare the collection of the start node as
+well if it's not declared already (like by a `FOR` loop).
+
+For example, suppose you have two node collections, `person` and `movie`, and
+an `acts_in` edge collection that connects them. If you want to run a path search
+query that starts (and ends) at a person that you specify with its document ID,
+you need to declare both node collections at the beginning of the query:
+
+```aql
+WITH person, movie
+FOR p IN ANY ALL_SHORTEST_PATHS "person/1544" TO "person/52560" acts_in
+  RETURN p.vertices[*].label
+```
+
+However, if there is a named graph that includes an edge definition for the
+`acts_in` edge collection, with `person` as the _from_ collection and `movie`
+as the _to_ collection, you can omit `WITH person, movie`. That is, if you
+specify `acts_in` as an edge collection in an anonymous graph query, all
+named graphs are checked for this edge collection, and if there is a matching
+edge definition, its node collections are automatically added as data sources to
+the query.
+
+```aql
+FOR p IN ANY ALL_SHORTEST_PATHS "person/1544" TO "person/52560" acts_in
+  RETURN p.vertices[*].label
+
+// Chris Rock --> Dogma <-- Ben Affleck --> Surviving Christmas <-- Jennifer Morrison
+// Chris Rock --> The Longest Yard <-- Rob Schneider --> Big Stan <-- Jennifer Morrison
+// Chris Rock --> Down to Earth <-- John Cho --> Star Trek <-- Jennifer Morrison
+```
+
+You can still declare collections manually, in which case they are added as
+data sources in addition to automatically deduced collections.
+
 ## Examples
 
 Load an example graph to get a named graph that reflects some possible