Path Patterns

Overview

A path pattern is to match paths in the graph. It is composed of three parts:

• Path Pattern Expression: Defines the sequence of nodes and edges that form the path. A path pattern expression can be either a single path term or a path term union or multiset alternation.
• Path Variable Declaration (Optional)
• Path Pattern Prefix (Optional)

<path pattern> ::=
  [ <path variable declaration> ] [ <path pattern prefix> ] <path pattern expression>
    
<path pattern expression> ::=
  <path term> | <path term union> | <path term multiset alteration>

Path Term

A path term consists of either a singleton or a concatenation of element patterns, parenthesized path patterns, and quantified path patterns, following the topological rules of a path which must start and end with a node and alternate between nodes and edges.

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

Element Pattern

A path term can be built by concatenating node and edge patterns recursively. For example, this path term starts from node Brainy, connecting to a Club node through an outgoing Joins edge:

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

You can keep on chaining edge and node patterns to create more complex path patterns. This path term describes that Brainy and mochaeach join the same club, with the Club node bound to the variable c:

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

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

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

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> [ <where clause> ] ")"

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

Quantified Path Pattern

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

Path Term Union & Multiset Alternation

The Path Term Union & Multiset Alternation feature is not fully supported yet.

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

Example Graph

CREATE GRAPH myGraph { 
  NODE User ({name string}),
  NODE Club (),
  EDGE Joins ()-[{}]->()
} PARTITION BY HASH(Crc32) SHARDS [1]

INSERT (rowlock:User {_id: 'U01', name: 'rowlock'}),
       (lionbower:User {_id: 'U02', name: 'lionbower'}),
       (mochaeach:User {_id: 'U03', name: 'mochaeach'}),
       (c01:Club {_id: 'C01'}),
       (c02:Club {_id: 'C02'}),
       (rowlock)-[:Joins]->(c01),
       (lionbower)-[:Joins]->(c01),
       (lionbower)-[:Joins]->(c02),
       (mochaeach)-[:Joins]->(c02)

Path term union combines path terms using the vertical bar |. It merges records bound to the same variable while removing duplicates.

MATCH ({_id: "C01"})<-[:Joins]-(u:User) | ({_id: "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 ({_id: "C01"})<-[:Joins]-(u:User) |+| ({_id: "C02"})<-[:Joins]-(u:User)
RETURN COLLECT_LIST(u.name) AS names

Result:

Note that each path term may only reference element variables decalred in the path term itself. For example, the following query throws syntax error:

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

Path Variable Declaration

A path variable is declared at the start of a path pattern with =, representing a path binding.

The variable p is bound to paths connecting any two nodes through an outgoing Follows edge:

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

Path Pattern Prefix

There are two types of path pattern prefixes:

• Path Mode
• Path Selector

Example Graph

CREATE GRAPH myGraph

INSERT (c1:default {_id: 'C1'}),
       (c2:default {_id: 'C2'}),
  	   (c3:default {_id: 'C3'}),
       (c4:default {_id: 'C4'}),
       (c1)-[:default]->(c2),
       (c2)-[:default]->(c1),
       (c2)-[:default]->(c3),
       (c3)-[:default]->(c4)

Path Mode

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

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

The following queries find 1- to 3-step outgoing paths from C1 using different path modes:

MATCH p = WALK ({_id: 'C1'})->{1,3}()
RETURN p

MATCH p = ({_id: 'C1'})->{1,3}()
RETURN p

MATCH p = ACYCLIC ({_id: 'C1'})->{1,3}()
RETURN p

MATCH p = SIMPLE ({_id: 'C1'})->{1,3}()
RETURN p

Result: p

Path Selector

A path selector is used to select a limited number of paths from each partition of the match results. When a path pattern matches multiple start and end nodes, the results are conceptually partitioned into distinct pairs of start node and end node. The path selection is performed within each partition, and the result is the union of all paths found for each partition.

The following queries find 1- to 3-step paths between C1 and target nodes C3 and C4, selecting ALL or ANY paths from each partition:

MATCH p = ({_id: 'C1'})-{1,3}(target WHERE target._id IN ['C3', 'C4'])
RETURN p

MATCH p = ANY ({_id: 'C1'})-{1,3}(target WHERE target._id IN ['C3', 'C4'])
RETURN p

Result: p

Combined Usage

When a query includes both a path selector and a path mode, the path selector should precede the path mode.

To find any 1- to 3-step outgoing WALK paths from C1 (from each partition):

MATCH p = ANY WALK ({_id: 'C1'})->{1,3}()
RETURN p

Special Considerations

Edge Pattern Juxtaposition

Two consecutive edge patterns conceptually have an empty node pattern between them. For example,

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

This path term implicitly extends to:

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

A path term 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.

Node Pattern Juxtaposition

Node pattern juxtaposition is only supported for quantified paths.