11.1. Match

Introduction

The MATCH clause allows you to specify the patterns Neo4j will search for in the database.
This is the primary way of getting data into the current set of bindings.
It is worth reading up more on the specification of the patterns themselves in Section 9.6, “Patterns”.

MATCH is often coupled to a WHERE part which adds restrictions, or predicates, to the MATCH patterns, making them more specific.
The predicates are part of the pattern description, not a filter applied after the matching is done.
This means that WHERE should always be put together with the MATCH clause it belongs to.

MATCH can occur at the beginning of the query or later, possibly after a WITH.
If it is the first clause, nothing will have been bound yet, and Neo4j will design a search to find the results matching the clause and any associated predicates specified in any WHERE part.
This could involve a scan of the database, a search for nodes of a certain label, or a search of an index to find starting points for the pattern matching.
Nodes and relationships found by this search are available as bound pattern elements, and can be used for pattern matching of sub-graphs.
They can also be used in any further MATCH clauses, where Neo4j will use the known elements, and from there find further unknown elements.

Cypher is declarative, and so usually the query itself does not specify the algorithm to use to perform the search.
Neo4j will automatically work out the best approach to finding start nodes and matching patterns.
Predicates in WHERE parts can be evaluated before pattern matching, during pattern matching, or after finding matches.
However, there are cases where you can influence the decisions taken by the query compiler.
Read more about indexes in Section 14.1, “Indexes”, and more about the specifying index hints to force Neo4j to use a specific index in Section 10.8, “Using”.

Variable length relationships

Nodes that are a variable number of relationship→node hops away can be found using the following syntax: -[:TYPE*minHops..maxHops]->. minHops and maxHops are optional and default to 1 and infinity respectively. When no bounds are given the dots may be omitted.

Match with properties on a variable length path

A variable length relationship with properties defined on in it means that all relationships in the path
must have the property set to the given value. In this query, there are two paths between Charile Sheen and his
dad Martin Sheen. One of the includes a “blocked” relationship and the other doesn’t.
In this case we first alter the original graph by using the following query to add “blocked” and “unblocked” relationships:

Zero length paths

Using variable length paths that have the lower bound zero means that two identifiers can point to the same node. If the distance between two nodes is zero, they are by definition the same node. Note that when matching zero length paths the result may contain a match even when matching on a relationship type not in use.

Query

MATCH (wallstreet:Movie { title:'Wall Street' })-[*0..1]-(x)
RETURN x

Returns all nodes that are zero or one relationships away from Wall Street.

This means: find a single shortest path between two nodes, as long as the path is max 15 relationships long. Inside of the parentheses
you define a single link of a path — the starting node, the connecting relationship and the end node. Characteristics describing the relationship
like relationship type, max hops and direction are all used when finding the shortest path. You can also mark the path as optional.

Get node or relationship by id

Node by id

Search for nodes by id can be done with the id function in a predicate.

Note

Neo4j reuses its internal ids when nodes and relationships are deleted.
This means that applications using, and relying on internal Neo4j ids, are brittle or at risk of making mistakes.
Rather use application generated ids.