Syntax and semantics

For rules on valid node variable names, see the Cypher^® naming rules.

Matches all nodes with the label A and binds them to the variable n:

Matches all nodes with the label B and a property departs with the time value 11:11:

Matches all nodes with the property departs with a value equal to the current time plus 30 minutes:

Note that the syntax for type expressions in relationship patterns is the same as for label expressions in node patterns (although unlike node labels, relationships must have exactly one type).

For rules on valid relationship variable names, see the Cypher naming rules.

Matches all relationships with the type R and binds them to the variable r:

Matches all relationships with type R and property distance equal to 100:

Matches all relationships where property distance is between 10 and 100:

Matches all relationships that connect nodes with label A as their source and nodes with label B as their target:

Matches all relationships that connect nodes with label A and nodes with label B, irrespective of their direction:

For valid label identifiers, see the Cypher naming rules.

The following table lists the symbols used in label expressions:

Associativity is left-to-right.

In the following table, a tick is shown where the label expression matches the node with the labels shown:

As relationships have exactly one type each, this expression will never match a relationship:

Similarly, the following will always match a relationship:

The use of negation can make the conjunction useful in relationship patterns. The following matches relationships that have a type that is neither A nor B:

The property key-value expression is treated as a conjunction of equalities on the properties of the element that the containing pattern matches.

For example, the following node pattern:

is equivalent to the following node pattern with a WHERE clause:

The value expression can be any expression as listed in the section on expressions, except for path patterns (which will throw a syntax error) and regular expressions (which will be treated as string literals). An empty property key-value expression matches all elements. Property key-value expressions can be combined with a WHERE clause.

Matches all nodes with property p = 10:

Matches all relationships with property p = 10 and q equal to date 2023-02-10:

Matches all relationships with its property p equal to the property p of its source node:

Matches all nodes with property p = 10 and property q greater than 100:

See the related section for each of the syntax rules:

The minimum number of elements in the path pattern must be greater than zero. For example, a path pattern that is a quantified path pattern with a quantifier that has a lower bound of zero is not allowed:

A path pattern must always begin and end with a node pattern.

A path pattern may be composed of a concatenation of simple and quantified path patterns. Two simple path patterns, however, may not be placed next to each other.

When a path pattern is matched to paths in a graph, nodes can be revisited but relationships cannot.

A subpath variable (a path variable declared inside a parenthesized path pattern expression) can only be used if a shortest path mode is also specified.

See graph patterns for rules on declaring variables multiple times.

A single node pattern is allowed as it has at least one element:

A simple path pattern with more than one element:

A quantified path pattern can have a lower bound of zero in its quantifier as long as it abuts other patterns that have at least one element:

A quantified relationship can also have a lower bound of zero as long as the overall path pattern has at least one element:

A concatenation of simple and quantified path patterns:

Referencing non-local node variable in a simple path pattern:

Referencing a non-local relationship variable within a quantified path pattern:

A variable that was introduced in a previous clause can be referenced as long as that variable was defined outside of a quantified path pattern:

Paths matched by the path pattern can be assigned to a variable:

The absence of an upper bound in the general quantifier syntax means there is no upper bound. The following table shows variants of the quantifier syntax and their canonical form:

Note that a quantified path pattern with the quantifier {1} is not equivalent to a fixed-length path pattern. Although the resulting quantified path pattern will match on the same paths the fixed-length path contained in it would without the quantifier, the presence of the quantifier means that all variables within the path pattern will be exposed as group variables.

For rules on valid relationship variable names, see Cypher naming rules.

The following table shows variants of the variable-length quantifier syntax and their equivalent quantifier form (the form used by quantified path patterns):

Note that * used here on its own is not the same as the Kleene star (an operator that represents zero or more repetitions), as the Kleene star has a lower bound of zero. The above table can be used to translate the quantifier used in variable-length relationships. The rules given for quantified path patterns would apply to the translation.

This table shows some examples:

The variable of a variable-length relationship can be used in subsequent patterns to refer to the list of relationships the variable is bound to. This is the same as the equijoin for variables bound to single nodes or relationships.

This section uses the following graph:

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

In the following query, the node variables will be bound to the same nodes:

The list of relationships keeps its order. This means that in the following query, where the direction of the variable-length relationship in the second MATCH is switched, the equijoin will only match once, when there is a single relationship:

The variable r can be reversed in order like any list, and made to match the switch in relationship pattern direction:

Changing the bounds on subsequent MATCH statements will mean that only the overlapping lengths of the quantifier bounds will produce results:

Because Cypher only allows paths to traverse a relationship once (see relationship uniqueness), repeating a variable-length relationship in the same graph pattern will yield no results. For example, this MATCH clause will never pass on any intermediate results to subsequent clauses:

Attempting to repeat a variable-length relationship in a single relationship pattern will raise an error. For example, the following pattern raises an error because the variable r appears in both a variable-length relationship and a fixed-length relationship:

The following pattern matches paths starting with nodes labeled A and ending with nodes labeled B, that traverse between two and three relationships of type R:

The following traverses relationships of type R or S or T exactly five times:

The following traverses any relationship between zero and five times, with the path beginning at nodes labeled A and ending at nodes labeled B. Note that this will also return all nodes that have both labels A and B for the case where zero relationships are traversed:

If the lower bound is removed, it will default to one, and will no longer return paths of length zero, i.e. single nodes:

The following pattern traverses one or more relationships of any direction that have property p = $param:

Return a single shortest path for each distinct pair of nodes matching (:A) and (:B):

Return any two paths connecting each distinct pair of nodes matching (:A) and (:B):

Return all paths equal to the shortest path length for each distinct pair of nodes matching (:A) and (:B):

Return all paths equal to the two shortest path lengths for each distinct pair of nodes matching (:A) and (:B):

Return a single shortest path for each distinct pair of nodes, where the path length is an even number:

For every single shortest path connecting each distinct pair of nodes, only return those that have path length that is an even number (so fewer results than the previous example):

Note that it is possible to pass a fixed length path pattern (with a single relationship) to the path selector function, but doing so would not serve any purpose in discovering a shortest path.

Return a single shortest path for each distinct pair of nodes matching (:A) and (:B):

Return all paths equal to the shortest path length for each distinct pair of nodes matching (:A) and (:B):

The rules for path patterns apply to each constituent path pattern of a graph pattern.

The WHERE clause can refer to variables inside and outside of quantified path patterns:

An equijoin can be formed to match "H" shaped graphs:

With no variables in common, this graph pattern will result in a Cartesian join between the sets of matches for the two path patterns:

Multiple equijoins can be formed between path patterns:

Variables declared in a previous MATCH can be referenced inside of a quantified path pattern:

The repetition of a relationship variable in the following yields no solutions due to Cypher enforcing relationship uniqueness within a match for a graph pattern:

When a quantified path pattern is expanded, the fixed path pattern contained in its parentheses is repeated and chained. This results in pairs of node patterns sitting next to each other. Take the following quantified path pattern as an example:

This is expanded by repeating the fixed path pattern (x:X)←-(y:Y) three times, with indices on the variables to show that no equijoin is implied (see equijoins for more information):

The result is that two pairs of node patterns end up adjoining each other, (y1:Y)(x2:X) and (y2:Y)(x3:X). During the matching process, each pair of node patterns will match the same nodes, and those nodes will satisfy the conjunction of the predicates in the node patterns. For example, in the first pair both y1 and x2 will bind to the same node, and that node must have labels X and Y. This expansion and binding is depicted in the following diagram:

Pairs of node patterns are also generated when a simple path pattern is placed next to a quantified path. For example, consider the following path pattern:

After expanding the iterations of the quantified path pattern, the right-hand node pattern (:B) adjoins the left-hand node pattern (:X). The result will match the same paths as the union of matches of the following two path patterns:

If the simple path pattern is on the right of the quantified path pattern, its leftmost node (:A) adjoins the rightmost node (:Y) of the last iteration of the quantified path pattern. For example, the following:

will match the same paths as the union of the following two path patterns:

When two quantified path patterns adjoin, the rightmost node of the last iteration of the first pattern is merged with the leftmost node of the first iteration of the second pattern. For example, the following adjoining patterns:

will match the same set of paths as the union of the paths matched by these two path patterns:

If the quantifier allows for zero iterations of a pattern, for example {0,3}, then the 0th iteration of that pattern results in the node patterns on either side pairing up.

For example, the following path pattern:

will match the same set of paths as the union of the paths matched by the following two path patterns: