GQL API

Quantified Paths

Overview

A quantified path is a variable-length path pattern where an edge pattern or a group of path patterns is repeated. This is extremely useful when the exact hop count between nodes is unknown, or when traversing hierarchies or networks of varying depths (such as mana path networks).

Quantifiers

A quantifier is written as a postfix to an edge pattern or a parenthesized path pattern:

Quantifier Description
{m, n} Between m and n repetitions (inclusive).
{m} Exactly m repetitions.
{m,} At least m repetitions.
{,n} Between 0 and n repetitions (inclusive).
* Equivalent to {0,}. Zero or more repetitions.
+ Equivalent to {1,}. One or more repetitions.

Building Quantified Paths

1. Quantified Edges

An edge pattern followed directly by a quantifier. Works on both full and abbreviated edge patterns.

Find wizards reachable within 1 to 3 hops of AlliedWith edges from "Albus":

MATCH p = (:Wizard {name: "Albus"})-[:AlliedWith]->{1,3}(w:Wizard)
RETURN p

2. Quantified Path Groups

Enclose a sequence of node and edge patterns in parentheses () and append the quantifier. This repeats the entire group structure.

Find paths repeating the (Wizard)-[:Teaches]->(Spell) pattern exactly 2 times:

MATCH p = ((:Wizard)-[:Teaches]->(:Spell)){2}
RETURN p

3. Zero-Hop repetition semantics

When a quantifier allows 0 repetitions (e.g. {0,3} or *), a 0-hop match is returned. This represents the starting node itself (a path of length 0 with zero edges).

Group Variables and Referencing Semantics

Variables declared inside the repeated segment of a quantified path are bound to a list of elements (nodes or edges) encountered across the hops. These are called group variables.

Referencing Outside the Quantified Segment

Outside the parenthesized repeatable group, the variable is exposed as a list. Evaluating property lookups directly on them (e.g., w.level) will fail because list types do not have these properties.

-- SYNTAX ERROR (w and s are lists of elements!)
MATCH p = ((w:Wizard)-[e:Teaches]->(s:Spell)){1,2}
WHERE w.level > 50
RETURN p

-- CORRECT (Filtering using list functions or subqueries)
MATCH p = ((w:Wizard)-[e:Teaches]->(s:Spell)){1,2}
RETURN p, w, s

Referencing Inside the Quantified Segment

Inside the repeatable group, variables are treated as singletons representing the individual nodes or edges at each specific hop. You can filter them inline.

Find paths of 1 to 2 wizard-spell teachings where each teaching wizard has a magic level greater than 40:

MATCH p = ((w:Wizard WHERE w.level > 40)-[:Teaches]->(s:Spell)){1,2}
RETURN p