Skip to content
Tutorials Center
My learning

Topics

Lesson 19 of 30 ยท Cypher and Graph Modeling

Paths, aggregation and WITH

Learn Cypher variable-length paths, shortestPath, count and collect, WITH pipelines, OPTIONAL MATCH, ORDER BY and LIMIT, with runnable Python stand-ins.

So far your Cypher patterns have matched a fixed shape: one node, one hop, two hops. The real strength of a graph database appears when you do not know how many hops you need. "Who can Ada reach through up to three follows?" and "What is the shortest chain between Ada and Gus?" are questions about paths, and Cypher has direct syntax for them.

This lesson also covers the second half of everyday Cypher: grouping and counting with count() and collect(), chaining query stages with WITH, keeping rows that have no match with OPTIONAL MATCH, and sorting and limiting results. Neo4j is a server, so the Cypher in code blocks is read-only. The Python stand-ins implement the same ideas on a small dictionary graph in your browser. They show the logic, not Neo4j's planner or storage engine. If you need a refresher on breadth-first search, see Graph BFS.

The example graph

All the examples use a small follow network. An arrow Ada -> Ben means Ada follows Ben.

flowchart LR
    Ada --> Ben
    Ada --> Cy
    Ben --> Cy
    Ben --> Dee
    Cy --> Eli
    Dee --> Eli
    Dee --> Fay
    Eli --> Gus
    Fay --> Gus

Seven people and nine FOLLOWS relationships. There are several different routes from Ada to Gus.

Variable-length paths

In a relationship pattern, a star turns a single hop into a range of hops.

CYPHER
// exactly 2 hops
MATCH (a:Person {name: 'Ada'})-[:FOLLOWS*2]->(x) RETURN x.name

// 1 to 3 hops
MATCH (a:Person {name: 'Ada'})-[:FOLLOWS*1..3]->(x) RETURN DISTINCT x.name

// 2 hops or more, no upper limit
MATCH (a:Person {name: 'Ada'})-[:FOLLOWS*2..]->(x) RETURN DISTINCT x.name

Three things matter here. First, DISTINCT is usually needed: Gus can be reached by several different routes, and each route is a separate match, so without DISTINCT he appears several times. Second, within one pattern match Cypher never uses the same relationship twice, but it may visit the same node twice, so cycles do not cause an endless loop. Third, an unbounded range such as * on a large, well-connected graph can explode in cost, because the number of paths grows very quickly. Put an upper bound on it unless you are sure the graph is small.

If you give the whole pattern a name, you get a path value and can inspect it.

CYPHER
MATCH p = (a:Person {name: 'Ada'})-[:FOLLOWS*1..3]->(x:Person {name: 'Eli'})
RETURN [n IN nodes(p) | n.name] AS route, length(p) AS hops
ORDER BY hops

nodes(p) returns the nodes along the path, relationships(p) the relationships, and length(p) the number of relationships. The bracket expression with | is a list comprehension, which maps every node to its name.

The first stand-in enumerates paths the way the pattern does: a depth-first walk that never reuses a relationship, collecting every route between a minimum and a maximum number of hops.

Python Variable-length paths and shortest path

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Look at the last line: following relationships in their stored direction, nobody can get from Gus back to Ada, so the answer is "no path". Real Cypher gives you no row in that case.

Shortest paths

Enumerating every path just to pick the shortest would waste work. Cypher has dedicated functions that search breadth first.

CYPHER
MATCH (a:Person {name: 'Ada'}), (g:Person {name: 'Gus'})
MATCH p = shortestPath((a)-[:FOLLOWS*]->(g))
RETURN [n IN nodes(p) | n.name] AS route, length(p) AS hops

shortestPath returns one shortest path; allShortestPaths returns every path of the shortest length. Replace -> with - to ignore direction, which is how you ask "how are these two people connected, whichever way the follows go?". Recent Neo4j versions also offer a newer SHORTEST keyword inside path patterns; check the manual for your version if you want it. Note that this is unweighted: it counts hops, not distances. Weighted routes are the job of algorithms such as Dijkstra, covered in Graph algorithms: PageRank, communities, shortest paths.

Aggregation: count and collect

Cypher has no GROUP BY clause. Instead, when a RETURN (or WITH) mixes plain expressions and aggregate functions, the plain expressions become the grouping keys automatically.

CYPHER
MATCH (p:Person)<-[:FOLLOWS]-(fan:Person)
RETURN p.name AS person, count(fan) AS followers, collect(fan.name) AS fans
ORDER BY followers DESC, person
LIMIT 3

Here p.name is the key, count(fan) counts matches per person, and collect(fan.name) gathers the matched names into a list. Other aggregates include sum, avg, min, max and count(DISTINCT x). Compare this with SQL's GROUP BY: the idea is the same, but the grouping columns are implicit.

Chaining stages with WITH

WITH works like RETURN in the middle of a query. It decides which variables continue to the next stage, and it is the place where you aggregate and then filter on the aggregate. This is what HAVING does in SQL.

CYPHER
MATCH (p:Person)<-[:FOLLOWS]-(fan)
WITH p, count(fan) AS followers
WHERE followers >= 2
MATCH (p)-[:FOLLOWS]->(next)
RETURN p.name, followers, collect(next.name) AS follows
ORDER BY followers DESC

Read it as a pipeline: find followers, count them per person, keep people with at least two, then match again from those people. Variables not named in WITH are gone afterwards, so list everything you still need.

OPTIONAL MATCH

A normal MATCH drops any row that has no match. OPTIONAL MATCH works like a left join: the row stays and the missing parts become null.

CYPHER
MATCH (p:Person)
OPTIONAL MATCH (p)<-[:FOLLOWS]-(fan)
RETURN p.name, count(fan) AS followers

People nobody follows now appear with a count of 0. Note that count(fan) ignores nulls, which is exactly why this works; count(*) would count the row itself and report 1.

ORDER BY, SKIP and LIMIT

ORDER BY sorts, SKIP n ignores the first n rows, and LIMIT n keeps n rows. Nulls sort last in ascending order. For stable paging, always add a tie-breaker such as the name or id to the sort.

The second stand-in runs the aggregation pipeline from above on the same graph, step by step, including the optional match and the limit.

Python count, collect, WITH and OPTIONAL MATCH

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Ada appears with zero followers because of the optional match. Cy, Eli and Gus each have two followers and pass the WHERE, but Gus follows nobody, so the second MATCH (an ordinary inner match) drops him from the final result. That is the pipeline behaving exactly as the Cypher above describes.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does (a)-[:FOLLOWS*1..3]->(x) match?

    The star with a range means a variable number of hops, here between one and three.
  2. 2. Why do you often need DISTINCT with a variable-length pattern?

    Matches are paths, not nodes. Two routes to the same person give two rows unless you deduplicate.
  3. 3. How do you filter on an aggregate, like HAVING in SQL?

    WITH ends a stage, aggregates, and lets the next WHERE filter on the aggregated value.
  4. 4. Why does count(fan) give 0 for a person with no followers after an OPTIONAL MATCH?

    OPTIONAL MATCH keeps the row with null for the missing parts, and count(expr) does not count nulls.

Summary

  • *min..max after a relationship type matches a variable number of hops; always set an upper bound on big graphs.
  • A match is a path, so use DISTINCT when you want unique end nodes.
  • shortestPath and allShortestPaths search breadth first and count hops, not weighted distance.
  • Aggregates group by the other expressions in RETURN or WITH; collect builds lists.
  • WITH chains stages and is where you filter on aggregates; OPTIONAL MATCH behaves like a left join.
  • The Python stand-ins show the logic only; Neo4j itself plans and executes these queries on its own storage.

Next: Graph data modeling.