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 ageORDER 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 sinceORDER 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 hopsORDER 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 roleORDER 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 namesORDER 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 nWHERE n > 1RETURN 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 knowsORDER 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, friendsORDER BY name// {name: 'Alice', friends: 1}, {name: 'Bob', friends: 1}, {name: 'Carol', friends: 0}Lists in, rows out
UNWIND ['Alice', 'Carol'] AS whoMATCH (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 nameUNIONMATCH (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 bandORDER 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.nameProject [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.