MATCH

The MATCH clause allows you to specify the patterns Cypher 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 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, 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 first clause, nothing will have been bound yet, and Cypher will design a search to find the results matching the clause and any associated predicates specified in any WHERE part. Vertices and edges 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 future clauses, where Cypher 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. Predicates in WHERE parts can be evaluated before pattern matching, during pattern matching, or after finding matches.

Basic vertex finding

Get all Vertices

By just specifying a pattern with a single vertex and no labels, all vertices in the graph will be returned.

Query

SELECT * FROM cypher('graph_name', $$
MATCH (v)
RETURN v
$$) as (v agtype);

Returns all the vertices in the database.

v

{id: 0; label: ‘Person’; properties{name: ‘Charlie Sheen’}}::vertex

{id: 1; label: ‘Person’; properties{name: ‘Martin Sheen’}}::vertex

{id: 2; label: ‘Person’; properties{name: ‘Michael Douglas’}}::vertex

{id: 3; label: ‘Person’; properties{name: ‘Oliver Stone’}}::vertex

{id: 4; label: ‘Person’; properties{name: ‘Rob Reiner’}}::vertex

{id: 5; label: ‘Movie’; properties{name: ‘Wall Street’}}::vertex

{id: 6; label: ‘Movie’; properties{title: ‘The American President’}}::vertex

7 row(s) returned

Get all vertices with a label

Getting all vertices with a label on them is done with a single node pattern where the vertex has a label on it.

Query

SELECT * FROM cypher('graph_name', $$
MATCH (movie:Movie)
RETURN movie.title
$$) as (title agtype);

Returns all the movies in the database.

title

‘Wall Street’

‘The American President’

2 row(s) returned

Related Vertices

The symbol -[]- means related to, without regard to type or direction of the edge.

Query

SELECT * FROM cypher('graph_name', $$
MATCH (director {name: 'Oliver Stone'})-[]-(movie)
RETURN movie.title
$$) as (title agtype);

Returns all the movies directed by ‘Oliver Stone’

title

‘Wall Street’

1 row(s) returned

Match with labels

To constrain your pattern with labels on vertices, you add it to your vertex in the pattern, using the label syntax.

Query

SELECT * FROM cypher('graph_name', $$
MATCH (:Person {name: 'Oliver Stone'})-[]-(movie:Movie)
RETURN movie.title
$$) as (title agtype);

Returns any vertices connected with the Person ‘Oliver’ that are labeled Movie.

title

‘Wall Street’

1 row(s) returned

Edge basics

Outgoing Edges

When the direction of an edge is of interest, it is shown by using -> or <-.

Query

SELECT * FROM cypher('graph_name', $$
MATCH (:Person {name: 'Oliver Stone'})-[]->(movie)
RETURN movie.title
$$) as (title agtype);

Returns any vertices connected with the Person’Oliver’ by an outgoing edge.

title

‘Wall Street’

1 row(s) returned

Directed Edges and variable

If a variable is required, either for filtering on properties of the edge, or to return the edge, this is how you introduce the variable.

Query

SELECT * FROM cypher('graph_name', $$
MATCH (:Person {name: 'Oliver Stone'})-[r]->(movie)
RETURN type(r)
$$) as (type agtype);

Returns the type of each outgoing edge from ‘Oliver’.

title

‘DIRECTED’

1 row(s) returned

Match on edge type

When you know the edge type you want to match on, you can specify it by using a colon together with the edge type.

Query

SELECT * FROM cypher('graph_name', $$
MATCH (:Movie {title: 'Wall Street'})<-[:ACTED_IN]-(actor)
RETURN actor.name
$$) as (actors_name agtype);

Returns all actors that ACTED_IN’Wall Street’.

actors_name

‘Charlie Sheen’

‘Martin Sheen’

‘Michael Douglas’

3 row(s) returned

Match on edge type and use a variable

If you both want to introduce a variable to hold the edge, and specify the edge type you want, just add them both.

Query

SELECT * FROM cypher('graph_name', $$
MATCH ({title: 'Wall Street'})<-[r:ACTED_IN]-(actor)
RETURN r.role
$$) as (role agtype);

Returns ACTED_IN roles for ‘Wall Street’.

role

‘Gordon Gekko’

‘Carl Fox’

‘Bud Fox’

3 row(s) returned

Multiple Edges

Edges can be expressed by using multiple statements in the form of ()-[]-(), or they can be strung together.

Query

SELECT * FROM cypher('graph_name', $$
    MATCH (charlie {name: 'Charlie Sheen'})-[:ACTED_IN]->(movie)<-[:DIRECTED]-(director)
    RETURN movie.title, director.name
$$) as (title agtype, name agtype);

Returns the movie ‘Charlie Sheen’ acted in and its director.

title	name
‘Wall Street’	‘Oliver Stone’
1 row(s) returned