Match modes and path modes

Match modes

A match mode specifies whether or not a relationship can be matched more than once when matching graph patterns. Cypher® contains two match modes:

Syntax

graphPattern ::=
  [ matchMode ] pathPattern [ "," pathPattern ]* [ graphPatternWhereClause ]

matchMode ::=
  { REPEATABLE ELEMENT[S] | DIFFERENT RELATIONSHIPS }

Rules

DIFFERENT RELATIONSHIPS

DIFFERENT RELATIONSHIPS is a restrictive match mode. It requires that all relationships matched across all constituent path patterns in a graph pattern be unique. More specifically:

  • A relationship may only occur once for a given MATCH result.

  • A given relationship can only be bound to at most one relationship variable (e.g. -[r]-) or an anonymous relationship pattern (-[]-).

  • A relationship can only be bound once within a relationship group variable.

No solutions can be returned if a relationship variable occurs more than once across a graph pattern. For example, the following patterns, where the r variable acts as an equijoin requiring all occurrences to match the same relationship, cannot return paths:

MATCH (a)-[r]-(b)-[f]-(c)-[r]-(d)  // r repeated twice
MATCH (a)-[r]-(b), (c)-[r]-(d)     // r repeated twice

The DIFFERENT RELATIONSHIPS keyword was released in Neo4j 2025.06. It is only available in Cypher 25 and can be used to explicitly specify Cypher’s default match mode after MATCH. Specifying the DIFFERENT RELATIONSHIPS keyword is functionally equivalent to not specifying a match mode. For example, the following two MATCH clauses are equivalent:

MATCH (a)--{2}(b)
MATCH DIFFERENT RELATIONSHIPS (a)--{2}(b)

REPEATABLE ELEMENTS
Cypher 25 onlyIntroduced in Neo4j 2025.06

REPEATABLE ELEMENTS is a non-restrictive match mode. It allows for relationships matched across all constituent path patterns in a graph pattern to be repeatedly traversed. More specifically:

  • A relationship may occur more than once for a given MATCH result.

  • A given relationship can be bound to more than one relationship variable or anonymous relationship pattern.

  • A relationship can be bound more than once within a relationship group variable.

Queries utilizing this match mode must add the keyword REPEATABLE ELEMENTS between the MATCH clause and the graph pattern.

Solutions can be returned if a relationship variable occurs more than once across a graph pattern. For example, the following two graph patterns, where the r variable acts as an equijoin requiring all occurrences to match the same relationship, can return paths:

MATCH REPEATABLE ELEMENTS (a)-[r]-(b)-[f]-(c)-[r]-(d)  // r repeated twice
MATCH REPEATABLE ELEMENTS (a)-[r]-(b), (c)-[r]-(d)     // r repeated twice

Quantifier bounds

The following applies to the use of variable-length patterns quantifiers in different match modes:

  • DIFFERENT RELATIONSHIPS does not require an upper bound on a quantifier. The following are valid: +, {n, }, { , }, *.

  • REPEATABLE ELEMENTS requires all quantifiers to have an upper bound. The following are not valid: +, {n, }, { , }, *, but these are valid: {n}, {n, m}, {,m}. This restriction is required to prevent a a potentially infinite number of returned paths.

Clauses and subqueries

Match modes can only be specified after MATCH. They cannot be applied to a MERGE clause.

Match modes are allowed in the COLLECT, COUNT, and EXISTS subqueries after a MATCH clause. If so, the match mode applies to patterns matched within the subquery and is separate from that applied to the top level graph pattern. In the following example, REPEATABLE ELEMENTS only applies to the pattern matched within the COUNT subquery:

MATCH (a)-[:R]->(b)
WHERE COUNT {
    MATCH REPEATABLE ELEMENTS (a)-[:S]-{,10}(b)
    RETURN *
} > 5
RETURN *

Selective path selectors

The following applies to match modes and the number of path patterns with selective path selectors (SHORTEST k, SHORTEST k GROUPS, ALL SHORTEST, and ANY k).

  • If the match mode is DIFFERENT RELATIONSHIPS, there can only be one path pattern if it has a selective path selector.

  • If the match mode is REPEATABLE ELEMENTS, there can be multiple path patterns even if one or more have a selective path selector.

Allowed: DIFFERENT RELATIONSHIPS with selective path selector and one path pattern
MATCH SHORTEST 2 ((a)--(b) WHERE a.p < b.p)+
Allowed: REPEATABLE ELEMENTS with multiple path patterns and selective path selectors
MATCH REPEATABLE ELEMENTS SHORTEST 2 (x) ((a)--(b) WHERE a.p < b.p){,10},
      ANY (x)-->{,10}(:X)
Not allowed: DIFFERENT RELATIONSHIPS with more than one path pattern and a selective path selector
MATCH ALL SHORTEST (x) ((a)--(b) WHERE a.p < b.p){,10},
      ANY (x)-->{,10}(:X)

Examples

This section uses the following graph:

match modes reference

To recreate it, run the following query against an empty Neo4j database:

CREATE (n1:A {q: 1}),
       (n2:B {q: 2}),
       (n3:A {q: 3}),
       (n4:A {q: 4}),

       (n1)-[:R]->(n2),
       (n2)-[:R]->(n3),
       (n3)-[:R]->(n2),
       (n2)-[:R]->(n4),
       (n4)-[:R]->(n1)

To demonstrate the basic concept behind REPEATABLE ELEMENTS, and how it differs from the DIFFERENT RELATIONSHIPS match mode, consider the following pattern, which attempts to form a relationship equijoin: (a)-[r]-(b)-[r]-(c). For this pattern to return any results, the same relationship must be re-traversed. That is, the same relationship connecting a to b must be the same as that connecting b to c.

If tested using DIFFERENT RELATIONSHIPS, no results are returned due to the restrictions of the match mode.

Find paths re-traversing the same relationship using DIFFERENT RELATIONSHIPS
MATCH  p = (:A)-[r]-(:B)-[r]-(:A)
RETURN [n IN nodes(p) | n.q] AS nodes
Result
(no results)

However, if the same query uses the REPEATABLE ELEMENTS match mode, four paths are returned in which the same relationship is traversed more than once.

Find paths re-traversing the same relationship using REPEATABLE ELEMENTS
MATCH  REPEATABLE ELEMENTS p = (:A)-[r]-(:B)-[r]-(:A)
RETURN [n IN nodes(p) | n.q] AS nodes
Result
nodes

[3, 2, 3]

[4, 2, 4]

[3, 2, 3]

[1, 2, 1]

Rows: 4

The DIFFERENT RELATIONSHIPS match mode allows only nodes to recur in a path.

Match a pattern with a length of 5 relationships using the DIFFERENT RELATIONSHIPS match mode
MATCH p = (:B)-->{5}()
RETURN [n IN nodes(p) | n.q] AS nodes
Result
nodes

[2, 3, 2, 4, 1, 2]

[2, 4, 1, 2, 3, 2]

Rows: 2

The REPEATABLE ELEMENTS match mode allows both nodes and relationships to be repeatedly traversed in paths.

Match a pattern with a length of 5 relationships using the REPEATABLE ELEMENTS match mode
MATCH REPEATABLE ELEMENTS p = (:B)-->{5}()
RETURN [n IN nodes(p) | n.q] AS nodes
Result
nodes

[2, 3, 2, 3, 2, 3]

[2, 3, 2, 3, 2, 4]

[2, 3, 2, 4, 1, 2]

[2, 4, 1, 2, 3, 2]

[2, 4, 1, 2, 4, 1]

Rows: 2

Path modes
Cypher 25 onlyIntroduced in Neo4j 2026.03

Path modes define the uniqueness constraints for nodes and relationships within a single path pattern. This contrasts with match modes which constrain relationship uniqueness across an entire MATCH clause.

Cypher supports three path modes:

  • WALK: no constraints imposed; both nodes and relationships can be repeated within the path.

  • TRAIL: relationships cannot be repeated, but nodes can be repeated within the path.

  • ACYCLIC: nodes cannot be repeated within a path. A node can be repeated across paths, enabling the formation of equijoins.

Syntax

pathModePrefix ::= pathMode [ pathKeywords ]

pathMode ::= WALK | TRAIL | ACYCLIC

pathKeywords ::= PATH | PATHS

Rules

The table below shows the effective uniqueness constraint for each combination of match mode and path mode.

Effective uniqueness constraints for match mode and path mode combinations
Match mode Path mode Effective uniqueness constraint Notes

DIFFERENT RELATIONSHIPS

WALK

Relationship uniqueness

Constraint enforced by match mode.

DIFFERENT RELATIONSHIPS

TRAIL

Relationship uniqueness

Path mode does not alter the constraint imposed by the match mode.

DIFFERENT RELATIONSHIPS

ACYCLIC

Node uniqueness and relationship uniqueness

Path mode constraint stricter than match mode; prevents node repetition.

REPEATABLE ELEMENTS

WALK

No uniqueness

Both match mode and path mode allow repetitions of nodes and relationships.

Note that TRAIL and ACYCLIC cannot be combined with the REPEATABLE ELEMENTS match mode.

In practice, the syntax needed to achieve each uniqueness constraint is:

Path pattern uniqueness constraints and the corresponding syntax
Desired constraint Syntax Notes

No uniqueness constraint

MATCH REPEATABLE ELEMENTS …​

Relationship uniqueness

No keywords required

Node uniqueness

MATCH ACYCLIC …​

ACYCLIC must be specified at the start of each path pattern.

As the above tables show, ACYCLIC is the only path mode that alters the effective uniqueness constraint of the path pattern match. For more information about ACYCLIC, see Acyclic paths.

All path modes in a MATCH must be the same

All path patterns in a single MATCH clause must use the same path mode. For example, you cannot mix ACYCLIC with a pattern that uses the TRAIL mode:

MATCH p = ACYCLIC (a)-->(b), q = TRAIL (c)-->(d)
RETURN p, q
GQLSTATUS error chain

42N61: error: syntax error or access rule violation - unsupported mixing of different path modes. Mixing ACYCLIC and TRAIL in the same graph pattern is not supported. Split the pattern into separate MATCH clauses instead.

42001: error: syntax error or access rule violation - invalid syntax

Only WALK can be combined with the REPEATABLE ELEMENTS match mode

Explicit path modes like ACYCLIC or TRAIL cannot be used with the REPEATABLE ELEMENTS match mode. For example:

MATCH REPEATABLE ELEMENTS p = ACYCLIC (n)-->{1, 10}(m)
RETURN p
GQLSTATUS error chain

42N60: error: syntax error or access rule violation - unsupported combination of match mode and path mode. REPEATABLE ELEMENTS with ACYCLIC path mode is not supported.

42001: error: syntax error or access rule violation - invalid syntax

Mixing restrictive path selectors and explicit path modes

Neo4j versions and rules for mixing restrictive path selectors and explicit path modes
Neo4j versions Behavior

2026.03 - 2026.4

Explicit path modes cannot be combined with restrictive path selectors (e.g., ANY, SHORTEST) or with legacy shortest path functions like shortestPath().

2026.5 - current

Explicit path modes can be combined with restrictive path selectors, but not with legacy shortest path functions.

Supported
MATCH p = ANY SHORTEST ACYCLIC (a:A)-->+(b:!A)
RETURN p

Path modes and variable-length paths

Explicit path modes cannot be used with the variable-length relationships syntax (e.g., -[*]->). Use quantified path patterns or quantified relationships instead.

Supported — explicit path mode with quantified relationship syntax
MATCH ACYCLIC (start)-[:R]->{4,7}(target)
RETURN start, target
Not supported — explicit path mode with variable-length relationship syntax
MATCH ACYCLIC (start)-[*4..7]->(target)
RETURN start, target
GQLSTATUS error chain

51N26: error: system configuration or operation exception - not supported in this version. Using explicit path modes on a pattern containing a variable-length relationship is not available. This implementation of Cypher does not support ACYCLIC on variable-length relationships.

42001: error: syntax error or access rule violation - invalid syntax

Path modes cannot be applied to MERGE clauses

For example, this is not allowed:

MERGE ACYCLIC (robert:Critic)-[:P]->(c:Critic)
GQLSTATUS error chain

42I04: error: syntax error or access rule violation - invalid expression. 'ACYCLIC' cannot be used in a MERGE clause.

42001: error: syntax error or access rule violation - invalid syntax

Repeated node variables within a path pattern result in no matches

Declaring a node variable more than once within a single restrictive path pattern (like ACYCLIC) results in no matches. Because the variable must bind to the same node element and the path mode forbids repeated nodes, there is no solution. The below query finds no matches because the node x is repeated.

MATCH p = ACYCLIC (x:Router)-[:LINK]->(x)
RETURN p

Repeated node variables across different path patterns specify an equijoin

When a node variable is repeated in separate path patterns within the same MATCH clause, it specifies an equijoin. In the below example, x is repeated across p and q, creating an equijoin between two acyclic paths. This is allowed because each individual path pattern remains acyclic.

MATCH p = ACYCLIC (a:Router)-[:LINK]->+(x:Router),
  q = ACYCLIC (x)-[:LINK]->+(z:Router)
RETURN p, q

Path mode scope in subqueries

The path mode of a subquery (such as an EXISTS or COUNT expression) is independent of the path mode in the outer query. This allows you to perform secondary checks with different uniqueness constraints. In the below example, the outer query finds path using relationship uniqueness (default WALK path mode + default match mode DIFFERENT RELATIONSHIPS). The subquery then checks for the existence of an ACYCLIC path connecting a and b.

MATCH p = (a:Router {name: 'A'})-[:LINK]->+(b:Router {name: 'D'})
  WHERE EXISTS { MATCH ACYCLIC (a)-[:LINK]->+(b) }
RETURN [n IN nodes(p) | n.name] AS route