For more videos from GraphConnect SF and to register for GraphConnect Europe, check out graphconnect.com..
Cypher: Neo4j’s Graph Query Language
When you ask someone what they love about Neo4j, Cypher is always at the top. Cypher is essentially ASCII art; you draw out your desired graph pattern in your code.
A node is indicated with open and closed parentheses, a data relationship is indicated by open/close square brackets, and to specify a pattern you use hyphens in combination with the nodes and relationships.
If you want to find a “node-relationship-node” pattern, you include two parentheses, a hyphen, open/close square brackets, another hyphen followed by a node on the other side, indicated below:
With Cypher, you most commonly specify a relationship direction with the “greater than”
> or “less than”
< signs. The second row above shows that the node on the left has an outgoing relationship to the node on the right, while the third example shows the opposite.
An Example Dataset: StarCraft
Let’s examine an example dataset from the game StarCraft.
Below is a hierarchical tree of requirements that demonstrate the different types of buildings you can construct and their required components. For example, the below hierarchy indicates that to build a barracks, you first need to have a command center.
We imported this tech tree into Neo4j because it’s very good at storing, modeling and querying tree-like structures. Below is the resulting graph:
In this dataset, we only have two node labels —
Unit — while the relationship, which is the hierarchy of requirements, is labeled
Above, the blue
Factory node in the center of the graph is a building that requires a
Barracks, which requires a
Supply Depot. There is an extensive hierarchy of building requirements that extends to the lowest node, which is typically the
The graph also indicates that
Units have requirements; for example, a
Medevac requires a
Starport which requires a
We also have
Builds relationships, which demonstrate what is built by the different
Buildings. For example, the
Barracks builds a
Additionally, resources — such as minerals and gas — are required in order to create
Buildings. The below example demonstrates the resource requirements for the
SVC unit and
Supply Depot building:
Query 1: What Units can be Built at the Barracks? The
The most important component when writing a query is the
MATCH clause, which is where you draw the graph pattern that will be retrieved by the query. In the below example, we indicate that we want to start with a node labeled
Building, which is included after a colon and surrounded by parentheses and is our entity type:
Here we’ve indicated that we want to find a
Building node that has an outgoing
Build relationship to a
Unit node. We chose to use the identifiers
u to precede the colons, which are now bound to the entities and can be used in the following clauses.
MATCH clause we have the
WHERE clause, which indicates that the type of building we want is
RETURN clause indicates the type of entities we want returned to us by our query.
Neo4j returns the following visual result of our data.
Query 2: Average Unit Cost
To find out the average cost of each unit, we use the same
MATCH clause but without the identifier on the
Builds relationship because we don’t want it in the
RETURN. However, we do include the
u identifiers because we want those returned in the
The below table is the result of our query; it provides us with the name of the
Building and the average cost of each
Unit at that
Building in terms of minerals and gas.
In the above example, the
b.name is unique, but this doesn’t need to be the case. You can have multiple buildings with the same name, and your query can return all of them unless you have a uniqueness constraint on that property, such as “buildings have to be unique by the name property.”
Query 3: What Buildings and Units are Unlocked by Construction of an Engineering Bay?
In StarCraft, once you’ve constructed a certain number of buildings and units, you can construct an Engineering Bay. This allows you to build even more components.
To find out what buildings and units can only be built once an Engineering Bay has been constructed, we need to traverse the
Requires relationship up one more level from the
In Query 2, we matched
Units through a
Builds relationship. In this query, we are matching
Buildings with other
Buildings through a
Requires relationship, which is why we’ve applied the building label to the nodes on either side of the
Requires relationship. However, we’ve indicated a specific building type to the node on the far right,
Neo4j returns the following, with the
Engineering Bay in the middle and the immediate one-step-out buildings that are unlocked once the
Engineering Bay has been constructed.
Query 4: Which Buildings Have No Dependencies?
Which buildings can we build right away without having any other
Units on the map?
To answer this question, we include a pattern in the
WHERE clause. We aren’t inquiring about data relationships; our only requirement is the return of entities that don’t have any
As indicated below, there are three buildings that do not have any
Requires relationships attached to them: the
Command Center and
Supply Depot. In other words, these are the only buildings that you can construct from the very start of the game.
Query 5: Which Units Have Additional Requirements for Construction?
The prerequisite for constructing most units is simply related to a specific building. However, some have additional dependencies, which we indicate in the below
MATCH clause we’ve indicated that we want to find a
Unit, and the first additional requirement
Building for that
Unit. In the first line of the
MATCH clause, we’ve bound the unit node to
u, which we also use in the second line of the
WHERE clause, we indicate with the less-than and greater-than signs that we don’t want entities returned that are the same (i.e., we don’t want units with a
Requires relationship that pointed back to the same
Below are the Neo4j results:
Query 6: What’s the Most Expensive Unit that Can Be Built at the Factory? Ordering and Limits
MATCH clause shows that a building builds a unit, and the
WHERE clause shows that the name of the building is
Factory. We want to return the name of the
Unit, as well as the amount of required mineral and gas it takes to build it.
You can use
LIMIT right after the
RETURN clause, and request the results in descending order, i.e. from most expensive to least expensive.
LIMIT 1 refers to the most expensive unit that can be built at this particular
Query 7: What Do the Barracks Unlock up to Two Levels Deep? Traversing Two-Level Relationships
Our prior queries have all included single-level relationships (i.e., the entities have been directly related). However, this is a “variable length” query. In this case, we want to
RETURN results that are separated by both one and two degrees from the
Barracks. In the
MATCH clause, we indicate this by including an asterisk and the number 2 in our relationship:
Below are the results in Neo4j:
This map shows that the
Barracks unlock the
Ghost Academy. Two steps away, the
Barracks unlock the
Query 8: What Are All The Dependencies of the Starport Building? What Not To Do
To answer this query, we move from the
Starport node all the way down the hierarchy, which you do by including an asterisk while omitting the “maximum” on the relationship:
This is not a good query, because it requires an exhaustive search of your entire database, and will only return the below:
It did the
Requires relationship all the way through the hierarchy until it didn’t have anywhere to go. This isn’t a great way to create a dependency, so let’s explore a better dependency with the
Battlecruiser as an example.
Query 9: What Are All The Buildings Required to Construct a Battlecruiser? Cypher’s Shortest Path Function
To address this query, we rely on Cypher’s
shortestPath function, which allows you to find the single shortest path between nodes. The syntax for this function is demonstrated below:
This query returns the following Neo4j graph:
Query 10: What Are All The Buildings Required to Construct a BattleCruiser and How Much Will It Cost? Cypher’s “Unwind” Function
To answer this query we rely on Cypher’s
UNWIND function, which allows you to expand a collection into a sequence of rows. In the below example, we grab the nodes out of a path, place those nodes into their own separate rows, and then
RETURN the name and amount of resources required to build it:
The below table shows the amount of required resources to build each
Building in the Neo4j graph from Query 8:
Query 11: What Are All the Necessary Components to Build a Battlecruiser, and Where Does it Need to be Built? Multiple
To answer this question, we will need to write multiple
WHERE clauses. In the below example, our first two lines are identical to the previous “shortest path” example, and we’ve bound
Unit to the identifier
Neo4j then returns the following graph:
So that is how you can use multiple
MATCH clauses within a Cypher query.
Inspired by Nicole’s talk? Register for GraphConnect Europe on April 26, 2016 at for more industry-leading presentations and workshops on the evolving world of graph database technology.