RETURN

Generic Description

Final projection clause that controls what the client receives.

Simple example:

MATCH (p:Person) RETURN p.name, p.city

Consumer-Level Explanation

Use RETURN when the query must final projection clause that controls what the client receives and the planner needs to see that operation as part of the Cypher row pipeline. Keep the clause explicit because it controls row grain, variable scope, and what later clauses are allowed to reference.

More Detailed Explanation

RETURN is where query intent becomes application output. It can emit raw entities, scalar expressions, map projections, aggregation results, algorithm outputs, and function-derived structures. In practice it is where graph queries become API payloads, analytics tables, or UI data models.

What this clause is really for:

it defines one concrete stage in the Cypher row pipeline, so variables available before and after RETURN must be clear
it should make graph structure, temporal filters, document payload shaping, or procedure output explicit instead of relying on client-side interpretation
planner tooling depends on this clause boundary to know row grain, variable scope, and whether later expressions are reads, writes, schema operations, or projections

Advanced Example

This example keeps RETURN inside a complete query pipeline so the clause boundary, visible variables, and returned row shape are clear to planner tooling.

MATCH (u:User)-[e:VIEWED]->(d:Document)
TIME e.ts BETWEEN datetime('2025-01-01T00:00:00Z') AND datetime('2025-02-01T00:00:00Z')
WITH u, e, d,
     date_trunc('day', e.ts) AS day_bucket,
     properties(d) AS doc_map,
     unpivot(properties(d.metadata)) AS metadata_rows,
     cosine_similarity(vector(properties(d).embedding), vector([0.22, 0.18, 0.44])) AS score
RETURN u.user_id, d.title, day_bucket, keys(doc_map) AS doc_keys, metadata_rows, score
ORDER BY score DESC
LIMIT 15

Real Use Cases

building API-ready rows directly in Cypher
shaping graph entities into compact report columns
returning partially denormalized structures that would otherwise require application-side transformation

Real Limitations And Tradeoffs

returning raw wide entities can create noisy results
unclear aliases reduce downstream usability
late projection means unnecessary data may flow through earlier stages