Chapter 3. Cypher

This chapter contains the complete and authoritative documentation for the Cypher query language.

3.1. Introduction

For a short introduction, see Section 3.1.1, “What is Cypher?”. To take your first steps with Cypher, see Section 2.2, “Get started with Cypher”. For the terminology used, see Appendix B, Terminology.

3.1.1. What is Cypher?

Cypher is a declarative graph query language that allows for expressive and efficient querying and updating of the graph store. Cypher is a relatively simple but still very powerful language. Very complicated database queries can easily be expressed through Cypher. This allows you to focus on your domain instead of getting lost in database access.

Cypher is designed to be a humane query language, suitable for both developers and (importantly, we think) operations professionals. Our guiding goal is to make the simple things easy, and the complex things possible. Its constructs are based on English prose and neat iconography which helps to make queries more self-explanatory. We have tried to optimize the language for reading and not for writing.

Being a declarative language, Cypher focuses on the clarity of expressing what to retrieve from a graph, not on how to retrieve it. This is in contrast to imperative languages like Java, scripting languages like Gremlin, and the JRuby Neo4j bindings. This approach makes query optimization an implementation detail instead of burdening the user with it and requiring her to update all traversals just because the physical database structure has changed (new indexes etc.).

Cypher is inspired by a number of different approaches and builds upon established practices for expressive querying. Most of the keywords like WHERE and ORDER BY are inspired by SQL. Pattern matching borrows expression approaches from SPARQL. Some of the list semantics have been borrowed from languages such as Haskell and Python.


Cypher borrows its structure from SQL — queries are built up using various clauses.

Clauses are chained together, and they feed intermediate result sets between each other. For example, the matching variables from one MATCH clause will be the context that the next clause exists in.

The query language is comprised of several distinct clauses. You can read more details about them later in the manual.

Here are a few clauses used to read from the graph:

  • MATCH: The graph pattern to match. This is the most common way to get data from the graph.
  • WHERE: Not a clause in its own right, but rather part of MATCH, OPTIONAL MATCH and WITH. Adds constraints to a pattern, or filters the intermediate result passing through WITH.
  • RETURN: What to return.

Let’s see MATCH and RETURN in action.

Imagine an example graph like the following one:

Figure 3.1. Example Graph

For example, here is a query which finds a user called 'John' and 'John’s' friends (though not his direct friends) before returning both 'John' and any friends-of-friends that are found.

MATCH (john {name: 'John'})-[:friend]->()-[:friend]->(fof)

Resulting in:

| | |
| "John"    | "Maria"  |
| "John"    | "Steve"  |
2 rows

Next up we will add filtering to set more parts in motion:

We take a list of user names and find all nodes with names from this list, match their friends and return only those followed users who have a 'name' property starting with 'S'.

MATCH (user)-[:friend]->(follower)
WHERE IN ['Joe', 'John', 'Sara', 'Maria', 'Steve'] AND =~ 'S.*'

Resulting in:

| | |
| "Joe"     | "Steve"       |
| "John"    | "Sara"        |
2 rows

And here are examples of clauses that are used to update the graph:

  • CREATE (and DELETE): Create (and delete) nodes and relationships.
  • SET (and REMOVE): Set values to properties and add labels on nodes using SET and use REMOVE to remove them.
  • MERGE: Match existing or create new nodes and patterns. This is especially useful together with unique constraints.