Results, aggregation and row pipelines

Wiki / Cypher query language

On this page

• RETURN
• WITH
• UNWIND
• UNION / UNION ALL

RETURN

Project rows into the result. Supports aliases, DISTINCT, *, ordering and paging.

MATCH (p:Person) RETURN p.name AS name, p.age * 12 AS months;

MATCH (p:Person) RETURN DISTINCT p.dept;

MATCH (p:Person)-[r:KNOWS]->(b) RETURN *;     // all bound variables

MATCH (p:Person)
RETURN p.name, p.age
ORDER BY p.age DESC, p.name ASC               // multi-key; ASC default; NULLs last in ASC, first in DESC
SKIP 10 LIMIT 5;

RETURN 1 + 1 AS two;                           // RETURN without a MATCH

Aggregation happens in RETURN (and WITH): non-aggregated items become the grouping key. See Aggregate functions.

MATCH (p:Person)
RETURN p.dept AS dept, count(*) AS n, avg(p.age) AS mean
ORDER BY n DESC;

WITH

The query horizon: project (exactly like RETURN) and pass the result on to the next clause. This is how you chain, aggregate-then-filter, and limit mid-query.

// aggregate, then filter the aggregate (WHERE after WITH = Cypher's HAVING):
MATCH (p:Person)
WITH p.dept AS dept, count(*) AS n
WHERE n > 1
RETURN dept, n ORDER BY n DESC LIMIT 10;

// narrow scope and carry a computed value forward:
MATCH (p:Person)
WITH p, p.age * 12 AS months
WHERE months > 240
RETURN p.name, months;

WITH supports the same modifiers as RETURN: DISTINCT, ORDER BY, SKIP, LIMIT, aliasing, and a trailing WHERE.

UNWIND

Expand a list into rows.

UNWIND [1, 2, 3] AS x RETURN x;               // three rows

UNWIND range(1, 5) AS x RETURN sum(x) AS total;   // 15

MATCH (p:Person)
UNWIND p.nicknames AS nick
RETURN p.name, nick;

• UNWIND null yields no rows.
• UNWIND <non-list> yields a single row with that value.

UNION / UNION ALL

Combine the results of two queries. Column names must match.

RETURN 1 AS n
UNION ALL
RETURN 2 AS n;                                 // 2 rows (duplicates kept)

MATCH (p:Person) RETURN p.name AS name
UNION
MATCH (c:Company) RETURN c.name AS name;       // UNION dedupes rows

Related articles

Indexes and constraints · Procedure directory · Transactions and concurrency