Quantified Paths

Overview

A quantified path is a variable-length path where the complete path or a part of it is repeated a specified number of times. Quantified paths are useful when you:

• Don’t know the exact number of hops required between nodes.
• Need to capture relationships at varying depths.
• Want to simplify queries by compressing repetitive pattens.

Quantifiers

A quantifier is written as a postfix to either an edge pattern or a parenthesized path pattern to specify how many times the pattern should repeat.

A quantifier's upper bound must be at least 1. A quantifier that can only repeat zero times, such as {0}, {0,0}, or {,0}, is not allowed and raises an error.

A lower bound of 0 is allowed when paired with a positive upper bound ({0,n}, {,n}, or *): the pattern may match zero times. In the zero-repetition case, the quantified segment is skipped entirely, contributing none of its own nodes or edges, and the node patterns on either side of the quantifier are merged:

• (a)(...){0,n}(b): a and b collapse onto the same node, combining their conditions with logical AND.
• (a)(...){0,n}: binds each a.
• (...){0,n}(b): binds each b.
• A quantifier applied to an entire standalone path pattern (no node pattern outside it) contributes nothing for the zero-repetition case; only its one-or-more-repetition matches are returned.

Example Graph

GQL
INSERT (jack:User {_id: "U01", name: "Jack"}), (mike:User {_id: "U02", name: "Mike"}),
       (c1:Device {_id: "Comp1"}), (c2:Device {_id: "Comp2"}),
       (c3:Device {_id: "Comp3"}), (c4:Device {_id: "Comp4"}),
       (jack)-[:Owns]->(c1), (mike)-[:Owns]->(c4),
       (c1)-[:Flows {packets: 20}]->(c2), (c1)-[:Flows {packets: 30}]->(c4),
       (c2)-[:Flows {packets: 34}]->(c3), (c2)-[:Flows {packets: 12}]->(c4),
       (c3)-[:Flows {packets: 74}]->(c4)

Building Quantified Paths

When writing a quantified path to its full form:

• Two consecutive node patterns are merged into a single node pattern with their filtering conditions combined using logical AND.
• Two consecutive edge patterns are implicitly connected by an empty node pattern.

Quantified Edge

Edge patterns can be directly followed by a quantifier, and both the full and abbreviated edge patterns are supported.

Quantified Entire Path

You can enclose the entire path pattern in parentheses () and append a quantifier.

Quantified Partial Path

You can enclose part of a path pattern in parentheses () and append a quantifier for it.

Another example:

Examples

Lowerbound and Upperbound

GQL
MATCH p = ({name: 'Jack'})->()-[f:Flows WHERE f.packets > 20]->{1,3}()<-({name: 'Mike'})
RETURN p

Result: p

Fixed Length

GQL
MATCH p = ((:Device)->(:Device)){2}
RETURN p

Result: p

Fixed Lowerbound

GQL
MATCH ({_id: 'Comp1'})->{2,}(n)
RETURN COLLECT_LIST(n._id)

Result:

GQL
MATCH p = ({_id: 'Comp1'})-[f:Flows WHERE f.packets > 20]->*()
RETURN p

Result: p

GQL
MATCH p = ({_id: 'Comp1'})-[f:Flows WHERE f.packets > 20]->+()
RETURN p

Result: p

Fixed Upperbound

GQL
MATCH p = ({name: 'Jack'})->(()-[f:Flows WHERE f.packets > 20]->()){,2}<-({name: 'Mike'})
RETURN p

Result: p

Group Variables

Element variables declared within the repeatable part of a quantified path are bound to a list of nodes or edges, known as group variables or group list.

Example Graph

GQL
INSERT (rowlock:User {_id: "U1", name: "rowlock", age: 24}),
       (quasar92:User {_id: "U2", name: "Quasar92", age: 29}),
       (claire:User {_id: "U3", name: "claire", age: 35}),
       (rowlock)-[:Follows {score: 2}]->(quasar92),
       (quasar92)-[:Follows {score: 3}]->(claire)

Referencing Outside the Quantified Segment

Whenever a group variable is referenced outside the repeatable part of the quantified path where it is declared, it refers to a list of nodes or edges.

In this query, variables a and b represent lists of nodes encountered along the matched paths, rather than individual nodes:

GQL
MATCH p = ((a)-[]->(b)){1,2}
RETURN p, a, b

Result:

To aggregate the group variables, use the FOR statement to expand it into individual records:

GQL
MATCH path = ()-[edges]->{1,2}()
CALL (path, edges) {
  FOR edge IN edges
  RETURN sum(edge.score) AS scores 
}
FILTER scores > 2
RETURN path, scores

Result:

The following query throws syntax error since a and b are lists:

GQL - Syntax Error
MATCH p = ((a)-[]->(b)){1,2}
WHERE a.age < b.age
RETURN p

Referencing Inside the Quantified Segment

A group variable has a singleton reference only when it is referenced within the repeatable part of the quantified path where it is declared.

In this query, a and b are treated as singletons that represent individual nodes. The condition a.age < b.age is evaluated for each pair of nodes a and b as the path is matched:

GQL
MATCH p = ((a)-[]->(b) WHERE a.age < b.age){1,2}
RETURN p

Result: p