Overview

A path pattern is to match paths in the graph and is composed of three successive parts:

• Path Variable Declaration (Optional)
• Path Pattern Prefix (Optional)
• Path Pattern Expression

<path pattern> ::=
  [ <path variable declaration> ] [ <path pattern prefix> ] <path pattern expression>

Path Pattern Expression

The path pattern expression is the core of a path pattern. It specifies the actual sequence of nodes and edges that make up the path which (1) starts and ends with a node, and (2) alternates between nodes and edges. A path may comprise a single node.

A path pattern expression can be a single path term, a path pattern union, or a path multiset alternation; the latter two combine multiple path terms.

<path pattern expression> ::=
  <path term> | <path pattern union> | <path multiset alternation>

Path Term

A path term consists of a singleton or a concatenation of element patterns, parenthesized path patterns, and quantified path patterns, adhering to the topological rules of a path.

<path term> ::= <path factor> [ <path factor>... ]
    
<path factor> ::=
  <element pattern> | <parenthesized path pattern> | <quantified path pattern>

1. Element Pattern

Element patterns can be concatenated recursively to build a path.

This path pattern starts from Brainy, connecting to a node labeled Club through an outgoing edge labeled Joins, where p is the path variable:

p = (:User {name: 'Brainy'})-[:Joins]->(:Club)

You can keep on chaining edge and node patterns to create more complex path patterns. This longer path pattern describes that Brainy and mochaeach both joined some clubs, with the club node bound to the variable c:

(:User {name: 'Brainy'})-[:Joins]->(c:Club)<-[:Joins]-(:User {name: 'mochaeach'})

This path pattern reuses the variable a to form a ring-like structure that starts and ends with the same node:

(a:Account)-[:Owns]->(:Card)-[:Transfers]->(:Card)-[:Transfers]->(:Card)<-[:Owns]-(a)

When two node patterns are concatenated consecutively, they bind to the same node with all filtering conditions considered conjunctively. In this example, u1 and u2 implicitly merges to (u1|u2:User {name: "Claire"}) (The union operator | here is for illustration only):

(u1:User)(u2 {name: "claire"})-[:Follows]-(u3)

Node pattern juxtaposition is currently only supported for quantified path patterns.

Two consecutive edge patterns conceptually have an empty node pattern between them. In this example, the path pattern implicitly extends to (:User)-[]-()-[]-(u):

(:User)-[]--[]-(u)

A path expression should not juxtapose a token that exposes a minus sign on the right (]-, <-, -) followed by a token that exposes a minus sign on the left (-[, ->, -), as this combination introduces the comment symbol --. See Comments.

2. Parenthesized Path Pattern

You can enclose a subpath or the entire path in a matching pair of parentheses () to form a parenthesized path pattern:

<parenthesized path pattern> ::=
  "(" [ <path mode prefix> ]
      <path pattern expression>
      [ <parenthesized path pattern where clause> ] ")"

Parenthesized path pattern currently can only be used with a quantifer to form a quantified path pattern.

3. Quantified Path Pattern

A quantifier can be affixed to an edge pattern or a parenthesized path pattern to form a quantified path pattern, constructing a path of variable length.

Path Pattern Union & Path Multiset Alternation

<path pattern union> ::=
  <path term> "|" <path term> [ { "|" <path term> }... ]
  
<path multiset alternation> ::=
  <path term> "|+|" <path term> [ { "|+|" <path term> }... ]

Path pattern union combines path terms using the vertical bar |. It merges records bound to the same variable while ensuring that duplicates are removed.

MATCH (:Club {code: "C01"})<-[:Joins]-(u:User) | (:Club {code: "C02"})<-[:Joins]-(u:User)
RETURN COLLECT_LIST(u.name) AS names

Result:

Path multiset alternation combines path terms using the multiset alternation operator |+|. It merges records bound to the same variable while ensuring that duplicates are retained.

MATCH (:Club {code: "C01"})<-[:Joins]-(u:User) |+| (:Club {code: "C02"})<-[:Joins]-(u:User)
RETURN COLLECT_LIST(u.name) AS names

Result:

Each path term in path pattern union or path multiset alternation may only reference element variables decalred in the path term. For example, the following query throws syntax error:

MATCH (:Club {code: "C01"})<-[]-(a) | 
      (:Club {code: "C02"})<-[]-(b WHERE a.name = b.name)
RETURN a, b

Path Pattern Prefix

There are two types of path pattern prefixes, path mode prefix and path search prefix that can be specified to restrict or select the matched results.

<path pattern prefix> ::= <path mode prefix> | <path search prefix>

<path mode prefix> ::= "TRAIL" | "SIMPLE" | "ACYCLIC" | "WALK"

<path search prefix> ::= <all path> | <any path> | <shortest path>

<all path> ::= "ALL" [ <path mode> ]

<any path> ::= "ANY" [ <non negative integer> ] [ <path mode> ]

<shortest path> ::=
    "ALL SHORTEST" [ <path mode prefix> ]
  | "ANY SHORTEST" [ <path mode prefix> ]
  | "SHORTEST" <non negative integer> [ <path mode prefix> ] 
  | "SHORTEST" [ <non negative integer> ] [ <path mode prefix> ] < "GROUP" | "GROUPS" >

Path Mode Prefix

Path mode prefixes (or restrictors) control how paths are traversed and whether nodes or edges can be revisited. A restrictor may be placed either at the head of a path pattern expression, or at the head of a parenthesized path pattern.

The restrictors ACYCLIC, SIMPLE and WALK are not yet supported.

Path Search Prefix

Path search prefixes (or selectors) select a finite set of matches from each partition^[1]. A selector may only be placed at the head of a path pattern expression.

^[1] The paths matched by the path pattern are conceptually partitioned by distinct pairs of start and end nodes.
^[2] k is an non-negative integer. If fewer than k paths exist, all are retained. When k is missing, it defaults to 1.

Refer to Shortest Paths for more information on the shortest selectors. When a shortest selector is used, the path mode is compulsively set to TRAIL.

The selectors ANY and ANY k are not yet supported. The explicit use of ALL is not supported either.

Combined Usage

You can use either or both restrictors and selectors in a path pattern. Restrictors can be seen as operating during pattern matching while selectors operate afterwards.

This query returns a single arbitrary acyclic path starting card C01, passing through 1 to 3 outgoing Transfers edges to another card:

MATCH p = ANY ACYCLIC (c:Card {_id: 'C01'})-[:Transfers]->{1,3}(:Card)
RETURN p

The path pattern expression could potentially find 5 paths. Firstly, the path including a repeated node C02 is removed by the restrictor ACYCLIC. The selector ANY then randomly picks one path in each partition. In total, three paths are returned.

Path Variable

A path variable is declared at the head of a path pattern expression using the operator =. The value of a path variable represents a path binding.

The variable p is bound to paths connecting any two nodes through outgoing edges labeled Follows:

MATCH p = ()-[:Follows]->()
RETURN p

A path variable can only be declared once in a graph pattern. The following query throws syntax error:

MATCH p = ()-[:Follows]->(), p = ()-[:Purchases]->()
RETURN p