Introduction

What is Cypher?

Cypher^® is a declarative graph query language that allows for expressive and efficient querying and updating of the graph. It is designed to be suitable for both developers and operations professionals. Cypher is designed to be simple, yet powerful; highly complicated database queries can be easily expressed, enabling you to focus on your domain, instead of getting lost in database access.

Cypher is inspired by a number of different approaches and builds on established practices for expressive querying. Many of the keywords, such as WHERE and ORDER BY, are inspired by SQL. Pattern matching borrows expression approaches from SPARQL. Some of the list semantics are borrowed from languages such as Haskell and Python. Cypher’s constructs, based on English prose and neat iconography, make queries easy both to write, and to read.

Structure

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.

Let’s create a simple example graph with the following query:

CREATE (john:Person {name: 'John'})
CREATE (joe:Person {name: 'Joe'})
CREATE (steve:Person {name: 'Steve'})
CREATE (sara:Person {name: 'Sara'})
CREATE (maria:Person {name: 'Maria'})
CREATE (john)-[:FRIEND]->(joe)-[:FRIEND]->(steve)
CREATE (john)-[:FRIEND]->(sara)-[:FRIEND]->(maria)

Example Graph

  N0 [
    label = "{Person|name = \'John\'\l}"
  ]
  N0 -> N1 [
    color = "#2e3436"
    fontcolor = "#2e3436"
    label = "FRIEND\n"
  ]
  N0 -> N3 [
    color = "#2e3436"
    fontcolor = "#2e3436"
    label = "FRIEND\n"
  ]
  N1 [
    label = "{Person|name = \'Joe\'\l}"
  ]
  N1 -> N2 [
    color = "#2e3436"
    fontcolor = "#2e3436"
    label = "FRIEND\n"
  ]
  N2 [
    label = "{Person|name = \'Steve\'\l}"
  ]
  N3 [
    label = "{Person|name = \'Sara\'\l}"
  ]
  N3 -> N4 [
    color = "#2e3436"
    fontcolor = "#2e3436"
    label = "FRIEND\n"
  ]
  N4 [
    label = "{Person|name = \'Maria\'\l}"
  ]

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)
RETURN john.name, fof.name

Resulting in:

+----------------------+
| john.name | fof.name |
+----------------------+
| "John"    | "Steve"  |
| "John"    | "Maria"  |
+----------------------+
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 user.name IN ['Joe', 'John', 'Sara', 'Maria', 'Steve'] AND follower.name =~ 'S.*'
RETURN user.name, follower.name

Resulting in:

+---------------------------+
| user.name | follower.name |
+---------------------------+
| "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.