Skip to content

Reading data

Every example on this page runs against this small graph. Paste it into any client to follow along:

CREATE (alice:Person {name: 'Alice', age: 30, city: 'Lima'}),
(bob:Person {name: 'Bob', age: 25, city: 'Quito'}),
(carol:Person:Admin {name: 'Carol', age: 41, city: 'Lima'}),
(acme:Company {name: 'Acme'}),
(alice)-[:KNOWS {since: 2020}]->(bob),
(bob)-[:KNOWS {since: 2021}]->(carol),
(alice)-[:WORKS_AT {role: 'engineer'}]->(acme),
(carol)-[:WORKS_AT {role: 'cto'}]->(acme)

Results are shown as rows, the way the Python client’s .rows() and the HTTP API’s rows return them.

Match nodes

MATCH (p:Person)
RETURN p.name AS name, p.age AS age
ORDER BY age DESC
{name: 'Carol', age: 41}
{name: 'Alice', age: 30}
{name: 'Bob', age: 25}

Filter inline with a property map, or with WHERE for anything richer:

MATCH (p:Person {city: 'Lima'}) RETURN p.name AS name ORDER BY name
// {name: 'Alice'}, {name: 'Carol'}
MATCH (p:Person)
WHERE p.age >= 30 AND p.city = 'Lima'
RETURN p.name AS name ORDER BY name
// {name: 'Alice'}, {name: 'Carol'}

A node with several labels matches each of them; (n:Person|Company) matches either:

MATCH (n:Person|Company) RETURN labels(n) AS labels, n.name AS name ORDER BY name
{labels: ['Company'], name: 'Acme'}
{labels: ['Person'], name: 'Alice'}
{labels: ['Person'], name: 'Bob'}
{labels: ['Admin', 'Person'], name: 'Carol'}

Returning a whole node gives its id, labels and properties:

MATCH (p:Person) RETURN p ORDER BY p.name LIMIT 1
{"p": {"_kind": "node", "id": "01a19a62-6427-7db1-8897-f10d97824111",
"label": "Person", "labels": ["Person"],
"properties": {"age": 30, "city": "Lima", "name": "Alice"}}}

The id is a UUID assigned at creation. Read it in Cypher as id(p), elementId(p) or p._id; look a node up by it with MATCH (p:Person {_id: $id}).

Match relationships

MATCH (a:Person)-[k:KNOWS]->(b:Person)
RETURN a.name AS from, b.name AS to, k.since AS since
ORDER BY since
{from: 'Alice', to: 'Bob', since: 2020}
{from: 'Bob', to: 'Carol', since: 2021}

Direction is ->, <-, or omitted (-) for either. -[:A|B]-> matches either type, and --> matches any type. Filter the far end like any node:

MATCH (p:Person)-[:WORKS_AT]->(:Company {name: 'Acme'})
RETURN p.name AS name ORDER BY name
// {name: 'Alice'}, {name: 'Carol'}

Variable-length paths

MATCH (:Person {name: 'Alice'})-[:KNOWS*1..2]->(f)
RETURN f.name AS name ORDER BY name
// {name: 'Bob'}, {name: 'Carol'}

Bounds can be * (one or more), *n, *n..m, *..m, *n.. and *0..m (zero hops includes the start node), and parameters: *1..$hops. Bind the path to inspect it:

MATCH p = (:Person {name: 'Alice'})-[:KNOWS*]->(b)
RETURN [n IN nodes(p) | n.name] AS route, length(p) AS hops
ORDER BY hops
{route: ['Alice', 'Bob'], hops: 1}
{route: ['Alice', 'Bob', 'Carol'], hops: 2}

A relationship variable on a variable-length hop (-[rs:KNOWS*1..2]->) is the list of relationships, so size(rs) is the hop count.

Shortest paths

Bind both endpoints first, then ask for the path between them. The upper bound is required:

MATCH (a:Person {name: 'Alice'})
MATCH (c:Person {name: 'Carol'})
MATCH p = shortestPath((a)-[:KNOWS*..10]-(c))
RETURN length(p) AS hops
// {hops: 2}

allShortestPaths(…) has the same shape and returns every path of the minimum length. For weighted shortest paths over a whole subgraph, use algo.shortest_path.

Optional matches

OPTIONAL MATCH keeps the row and fills NULL when the pattern has no match:

MATCH (p:Person)
OPTIONAL MATCH (p)-[w:WORKS_AT]->(c:Company)
RETURN p.name AS name, c.name AS company, w.role AS role
ORDER BY name
{name: 'Alice', company: 'Acme', role: 'engineer'}
{name: 'Bob', company: null, role: null}
{name: 'Carol', company: 'Acme', role: 'cto'}

An OPTIONAL MATCH matches its whole pattern or nothing; it never keeps half of a multi-hop pattern.

Aggregation

Non-aggregated items in RETURN (or WITH) are the grouping key:

MATCH (p:Person)
RETURN p.city AS city, count(*) AS people, avg(p.age) AS avg_age,
collect(p.name) AS names
ORDER BY city
{city: 'Lima', people: 2, avg_age: 35.5, names: ['Alice', 'Carol']}
{city: 'Quito', people: 1, avg_age: 25.0, names: ['Bob']}

Available aggregates: count(*), count(x), sum, avg, min, max, collect, stdev, stdevp, percentileCont, percentileDisc, each with optional DISTINCT (count(DISTINCT p.city)).

Chain with WITH

WITH ends one stage and starts the next. Use it to filter on an aggregate:

MATCH (p:Person)
WITH p.city AS city, count(*) AS n
WHERE n > 1
RETURN city, n
// {city: 'Lima', n: 2}

Order and page

MATCH (p:Person) RETURN p.name AS name ORDER BY p.age DESC SKIP 1 LIMIT 1
// {name: 'Alice'}
MATCH (p:Person) RETURN DISTINCT p.city AS city ORDER BY city
// {city: 'Lima'}, {city: 'Quito'}

SKIP and LIMIT take an integer literal or a $parameter.

Existence checks and subqueries

// People without a job:
MATCH (p:Person)
WHERE NOT EXISTS { MATCH (p)-[:WORKS_AT]->() }
RETURN p.name AS name
// {name: 'Bob'}

The shorter forms WHERE (p)-[:WORKS_AT]->() and WHERE exists((p)-[:WORKS_AT]->()) work too.

A pattern comprehension collects matches per row:

MATCH (p:Person)
RETURN p.name AS name, [(p)-[:KNOWS]->(f) | f.name] AS knows
ORDER BY name
{name: 'Alice', knows: ['Bob']}
{name: 'Bob', knows: ['Carol']}
{name: 'Carol', knows: []}

A correlated CALL { … } runs once per incoming row; import variables with a leading WITH:

MATCH (p:Person)
CALL { WITH p MATCH (p)-[:KNOWS]->(f) RETURN count(f) AS friends }
RETURN p.name AS name, friends
ORDER BY name
// {name: 'Alice', friends: 1}, {name: 'Bob', friends: 1}, {name: 'Carol', friends: 0}

Lists in, rows out

UNWIND ['Alice', 'Carol'] AS who
MATCH (p:Person {name: who})
RETURN p.name AS name, p.age AS age
// {name: 'Alice', age: 30}, {name: 'Carol', age: 41}

Pass the list as a parameter (UNWIND $names AS who) to look up many keys in one statement.

Combine results with UNION

MATCH (p:Person) RETURN p.name AS name
UNION
MATCH (c:Company) RETURN c.name AS name
// {name: 'Alice'}, {name: 'Bob'}, {name: 'Carol'}, {name: 'Acme'}

Every branch must return the same column names in the same order. UNION removes duplicates; UNION ALL keeps them.

Conditional values

MATCH (p:Person)
RETURN p.name AS name,
CASE WHEN p.age >= 40 THEN 'senior'
WHEN p.age >= 30 THEN 'mid'
ELSE 'junior' END AS band
ORDER BY name
// {name: 'Alice', band: 'mid'}, {name: 'Bob', band: 'junior'}, {name: 'Carol', band: 'senior'}

Parameters

Always pass values as parameters rather than splicing them into the query text. It is safer, lets the engine reuse plans, and keeps values out of the slow-query log:

MATCH (p:Person) WHERE p.age IN $ages RETURN p.name AS name ORDER BY name
// with {"ages": [25, 41]}: {name: 'Bob'}, {name: 'Carol'}

See the plan

Prefix a query with EXPLAIN to get the plan instead of results:

EXPLAIN MATCH (p:Person)-[:KNOWS]->(f) WHERE p.age > 26 RETURN f.name
Project [f.name=f.name]
Expand source=p edge_type=KNOWS dir=-> target=f
NodeScan label=Person alias=p projection=[age, id] predicates=[p.age > 26]

EXPLAIN VERBOSE adds row estimates; EXPLAIN RAW shows the plan before optimisation. A declared index or constraint turns a filtered NodeScan into an indexed lookup.

Column names

An aliased item (RETURN p.name AS name) is named by its alias. An unaliased item is named by its canonical text, for example p.name or count(*); complex expressions are normalised (RETURN 'a' STARTS WITH 'b' comes back as ('a' STARTS WITH 'b')). Alias anything a program reads.