The MATCH clause is used to search for the pattern described in it.
The MATCH clause permits 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 Three.Two.7, “Patterns”.
MATCH is often coupled to a WHERE part which adds limitations, or predicates, to the MATCH patterns, making them more specific. The predicates are part of the pattern description, and should not be considered a filter applied only 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 very first clause, nothing will have been roped 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 knots of a certain label, or a search of an index to find kicking off points for the pattern matching. Knots and relationships found by this search are available as roped 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 treatment to finding commence knots 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 Trio.Five.1, “Indexes”, and more about specifying hints to force Neo4j to solve a query in a specific way in Section Trio.6.Four, “Planner hints and the USING keyword”.
To understand more about the patterns used in the MATCH clause, read Section Trio.Two.7, “Patterns”
The following graph is used for the examples below:
Trio.Three.1.Two. Basic knot finding
Get all knots
By just specifying a pattern with a single knot and no labels, all knots in the graph will be returned.
Comes back all the knots in the database.
Get all knots with a label
Getting all knots with a label on them is done with a single knot pattern where the knot has a label on it.
Comebacks all the movies in the database.
“The American President”
The symbol — means related to, without regard to type or direction of the relationship.
Comes back all the movies directed by ‘Oliver Stone’ .
Match with labels
To constrain your pattern with labels on knots, you add it to your pattern knots, using the label syntax.
Comebacks any knots connected with the Person ‘Oliver’ that are labeled Movie .
Trio.Trio.1.Trio. Relationship basics
When the direction of a relationship is of interest, it is shown by using -→, or ←,- , like this:
Comebacks any knots connected with the Person ‘Oliver’ by an outgoing relationship.
Directed relationships and variable
If a variable is required, either for filtering on properties of the relationship, or to come back the relationship, this is how you introduce the variable.
Comes back the type of each outgoing relationship from ‘Oliver’ .
Match on relationship type
When you know the relationship type you want to match on, you can specify it by using a colon together with the relationship type.
Comes back all actors that ACTED_IN ‘Wall Street’ .
Match on numerous relationship types
To match on one of numerous types, you can specify this by chaining them together with the pipe symbol | .
Comes back knots with an ACTED_IN or DIRECTED relationship to ‘Wall Street’ .
Match on relationship type and use a variable
If you both want to introduce an variable to hold the relationship, and specify the relationship type you want, just add them both, like this:
Comebacks ACTED_IN roles for ‘Wall Street’ .
Trio.Three.1.Four. Relationships in depth
Inwards a single pattern, relationships will only be matched once. You can read more about this in Section Trio.1.Four, “Uniqueness”.
Relationship types with uncommon characters
Sometimes your database will have types with non-letter characters, or with spaces in them. Use ` (backtick) to quote these. To demonstrate this we can add an extra relationship inbetween ‘Charlie Glitter’ and ‘Rob Reiner’ :
Which leads to the following graph:
Comebacks a relationship type with a space in it
“TYPE WITH SPACE”
Relationships can be voiced by using numerous statements in the form of ()–() , or they can be strung together, like this:
Comebacks the movie ‘Charlie Gloss’ acted in and its director.
Variable length relationships
Knots that are a variable number of relationship→,knot 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. The dots may also be omitted when setting only one strapped and this implies a stationary length pattern.
Comebacks all movies related to ‘Charlie Glitter’ by 1 to Trio hops.
“The American President”
“The American President”
Relationship variable in variable length relationships
When the connection inbetween two knots is of variable length, the list of relationships comprising the connection can be returned using the following syntax:
Comes back a list of relationships.
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 inbetween ‘Charlie Gloss’ and his father ‘Martin Gloss’ . One of them includes a ‘blocked’ relationship and the other doesn’t. In this case we very first alter the original graph by using the following query to add BLOCKED and UNBLOCKED relationships:
This means that we are beginning out with the following graph:
Comes back the paths inbetween ‘Charlie Glitter’ and ‘Martin Glitter’ where all relationships have the blocked property set to false .
Zero length paths
Using variable length paths that have the lower corded zero means that two variables can point to the same knot. If the path length inbetween two knots is zero, they are by definition the same knot. Note that when matching zero length paths the result may contain a match even when matching on a relationship type not in use.
Comebacks the movie itself as well as actors and directors one relationship away
If you want to come back or filter on a path in your pattern graph, you can a introduce a named path.
Comebacks the two paths beginning from ‘Michael Douglas’
Matching on a strapped relationship
When your pattern contains a tied relationship, and that relationship pattern doesn’t specify direction, Cypher will attempt to match the relationship in both directions.
This comes back the two connected knots, once as the begin knot, and once as the end knot
Three.Three.1.Five. Shortest path
Single shortest path
Finding a single shortest path inbetween two knots is as effortless as using the shortestPath function. It’s done like this:
This means: find a single shortest path inbetween two knots, as long as the path is max 15 relationships long. Within the parentheses you define a single link of a path ,—, ,the embarking knot, the connecting relationship and the end knot. Characteristics describing the relationship like relationship type, max hops and direction are all used when finding the shortest path. If there is a WHERE clause following the match of a shortestPath , relevant predicates will be included in the shortestPath . If the predicate is a none() or all() on the relationship elements of the path, it will be used during the search to improve spectacle (see Section Trio.7.6, “Shortest path planning”).
Single shortest path with predicates
Predicates used in the WHERE clause that apply to the shortest path pattern are evaluated before determining what the shortest matching path is.
This query will find the shortest path inbetween ‘Charlie Gloss’ and ‘Martin Glitter’ , and the WHERE predicate will ensure that we don’t consider the father/son relationship inbetween the two.
All shortest paths
Finds all the shortest paths inbetween two knots.
Finds the two shortest paths inbetween ‘Martin Gloss’ and ‘Michael Douglas’ .
Trio.Trio.1.6. Get knot or relationship by id
Knot by id
Searching for knots by id can be done with the id() function in a predicate.
Neo4j reuses its internal ids when knots and relationships are deleted. This means that applications using, and relying on internal Neo4j ids, are brittle or at risk of making mistakes. It is therefore recommended to rather use application-generated ids.
The corresponding knot is returned.
Relationship by id
Search for relationships by id can be done with the id() function in a predicate.
This is not recommended practice. See the section called “Node by id” for more information on the use of Neo4j ids.
The relationship with id 0 is returned.
Numerous knots by id
Numerous knots are selected by specifying them in an IN clause.
This comebacks the knots listed in the IN expression.