RETURN

Specifies the output columns and expressions.

Category: query-language

Syntax

RETURN [DISTINCT] <expr> [AS <alias>], ...

Description

## Overview RETURN is the terminal projection clause in a Cypher query. It defines which columns appear in the final result set returned to the caller. Every read query must end with a RETURN clause (or be wrapped in a CALL subquery that has its own RETURN). The clause operates on the bindings produced by preceding MATCH, WITH, UNWIND, or CALL clauses. In DeltaForge, RETURN produces Arrow RecordBatch output. Column names are derived from aliases (AS) when provided, or from the expression text otherwise. Aggregation functions in RETURN implicitly group by the non-aggregated expressions, following the same semantics as the openCypher specification. ## Behavior - Non-aggregated expressions in the RETURN list form the implicit GROUP BY key when any aggregation function (count, sum, avg, min, max, collect) is present. - RETURN DISTINCT applies deduplication after all expressions are evaluated, including aggregations. - Returning a bare variable (e.g., `RETURN a`) serializes all properties of the node or relationship as a structured column. This is useful for graph visualization but produces wider result sets. - RETURN * is supported and projects all variables currently in scope. ## Limitations - Nested aggregation (e.g., `count(sum(n.value))`) is not supported. Use a WITH clause to perform the inner aggregation first, then aggregate the result in RETURN. - The collect() function returns a list column in the Arrow output. Downstream SQL consumers that receive Cypher results via the cypher() table function should account for list-typed columns.

Parameters

Name	Type	Description
`distinct`		Enables deduplication of result rows. When set, identical rows are collapsed into a single output row.
`items`		Specifies the list of expressions to project as output columns. Accepts property access (n.name), aggregation functions (count, avg, sum, min, max, collect), arithmetic, CASE expressions, and literal values. Use AS to assign column aliases.

Examples

-- Return specific node properties
USE my_zone.my_schema.my_graph
MATCH (n)
RETURN n.name AS name, n.department AS dept, n.age AS age
ORDER BY n.name;

-- Return with aggregation: count and average
USE my_zone.my_schema.my_graph
MATCH (n)
RETURN n.department AS dept,
       count(n) AS headcount,
       avg(n.h_index) AS avg_h,
       min(n.h_index) AS min_h,
       max(n.h_index) AS max_h
ORDER BY avg_h DESC;

-- Return distinct labels from the graph
USE my_zone.my_schema.my_graph
MATCH (n)
RETURN DISTINCT n.department AS department
ORDER BY department;

-- Return edge properties alongside node properties
USE my_zone.my_schema.my_graph
MATCH (a)-[r]->(b)
RETURN a.name AS source, b.name AS target,
       r.relationship_type AS type, r.weight AS weight
ORDER BY r.weight DESC;

-- Return count of distinct collaboration targets per node
USE my_zone.my_schema.my_graph
MATCH (a)-[]->(b)
RETURN a.name AS name, count(DISTINCT b) AS collaborator_count
ORDER BY collaborator_count DESC;

-- Return full node/edge objects for visualization
USE my_zone.my_schema.my_graph
MATCH (a)-[r]->(b)
RETURN a, r, b;

Pitfalls

Missing aliases produce auto-generated column names based on the expression text, which can be fragile when consumed by downstream SQL queries. Always assign explicit aliases with AS for stable column references.
Aggregation without a grouping key collapses the entire result into a single row. If the RETURN list contains only aggregation functions, the output is one row regardless of how many nodes matched.
RETURN DISTINCT on high-cardinality result sets requires sorting and deduplication in memory. For large graphs, prefer filtering with WHERE or aggregating with count(DISTINCT x) to reduce memory pressure.
Returning full node objects (RETURN n) includes all properties from the underlying Delta table columns, which may include columns not relevant to the graph. Use explicit property access (n.name, n.id) for predictable output.