Chapter 4. Cypher Query Language

Table of Contents

4.1. Identifiers
4.2. Start
4.3. Match
4.4. Where
4.5. Return
4.6. Aggregation
4.7. Order by
4.8. Skip
4.9. Limit
[Caution]Caution

This is an experimental feature.

A new query language, code-named “Cypher”, has been added to Neo4j. It allows for expressive and efficient querying of the graph store without having to write traversers in code.

Cypher is designed to be a humane query language, suitable for both developers and (importantly, we think) operations professionals who want to make ad-hoc queries on the database. Its constructs are based on English prose and neat iconography, which helps to make it (somewhat) self-explanatory.

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. Regular expression matching is implemented using the Scala programming language.

Cypher is a declarative language. It focuses on the clarity of expressing what to retrieve from a graph, not how to do it, in contrast to imperative languages like Java and Scala, and scripting languages like Gremlin (supported via the Section 6.11, “Gremlin Plugin”) and the JRuby Neo4j bindings. This makes the concern of how to optimize queries in implementation detail not exposed to the user.

The query language is comprised of several distinct parts.

Let’s see three of them in action:

For example, here is a query which finds a user called John in an index and then traverses the graph looking for friends of Johns friends (though not his direct friends) before returning both John and any friends-of-friends that are found.

Cypher Example with index lookup

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

In this next example, we take a list of users (by node ID) and traverse the graph looking for those other users that have an outgoing friend relationship, returning only those followed users who are older than 18.

Cypher Example with Node id

In Java, using the query language looks something like this:

db = new ImpermanentGraphDatabase();
engine = new ExecutionEngine( db );
CypherParser parser = new CypherParser();
ExecutionEngine engine = new ExecutionEngine(db);
Query query = parser.parse( "start n=(0) where 1=1 return n" );
ExecutionResult result = engine.execute( query );

assertThat( result.columns(), hasItem( "n" ) );
Iterator<Node> n_column = result.columnAs( "n" );
assertThat( asIterable( n_column ), hasItem(db.getNodeById(0)) );
assertThat( result.toString(), containsString("Node[0]") );