Overview

The RETURN statement allows you to specify columns to include in the final table. Each column is defined by an expression that can include variables, properties, functions, constants, etc.

<return statement> ::= 
  "RETURN" [ <set quantifier> ] { <"*"> | <return item list> }
  [ <group by clause> ]
                          
<return item list> ::= <return item> [ { "," <return item> }... ]

<return item> ::= <value expression> [ <return item alias> ]
  
<return item alias> ::= "AS" <identifier>

<set quantifier> ::= "DISTINCT" | "ALL"

Details

• When the set quantifier DISTINCT is specified, each return item is an operand of a grouping operation, duplicate records are removed, and only distinct ones are returned.
• * returns all columns in the current working table.
• The keyword AS is used to rename columns.
• The RETURN statement supports the use of the GROUP BY clause to group the final table by specifying grouping keys.

Example Graph

The following examples run against this graph:

To create this graph, run the following query against an empty graph:

INSERT (alex:Student {_id: 's1', name: 'Alex', gender: 'male'}),
       (susan:Student {_id: 's2', name: 'Susan', gender: 'female'}),
       (art:Course {_id: 'c1', name: 'Art', credit: 13}),
       (literature:Course {_id: 'c2', name: 'Literature', credit: 15}),
       (alex)-[:Take {year: 2024, term: 'Spring'}]->(art),
       (susan)-[:Take {year: 2023, term: 'Fall'}]->(art),
       (susan)-[:Take {year: 2023, term: 'Spring'}]->(literature)

Returning Nodes

A variable bound to nodes returns the label and properties of each node.

MATCH (n:Course)
RETURN n

Result: n

Returning Edges

A variable bound to edges returns the label and properties of each edge.

MATCH ()-[e]->()
RETURN e

Result: e

Returning Paths

A variable bound to paths returns the nodes and edges included in each path. Each element includes its label and properties.

MATCH p = ()-[:Take {term: "Spring"}]->()
RETURN p

Result:

Returning Labels

The function labels() can be used to return the labels of nodes and edges.

MATCH ({_id: "s2"})-[e]->(n)
RETURN labels(e), labels(n)

Result:

Returning Properties

The period operator . can be used to extract the value of a specified property from a variable bound to nodes or edges. The null value will be returned if the specified property is not found on the nodes or edges.

MATCH (:Student {name:"Susan"})-[]->(c:Course)
RETURN c.name, c.credit, c.type

Result:

Returning All

* is used to return all columns in the current working table.

MATCH (s:Student {name:"Susan"})-[]->(c:Course)
RETURN *

Result:

s

c

Column Alias

The keyword AS is used to rename the returned columns.

MATCH (s:Student)-[t:Take]->(c:Course)
RETURN s.name AS Student, c.name AS Course, t.year AS TakenIn

Result:

Returning Distinct Records

The DISTINCT set quantifier can be used to deduplicate records.

MATCH ()-[e]->()
RETURN DISTINCT e.year

Result:

Returning with Aggregation

Aggregation functions, such as sum() and max(), can be directly applied in the RETURN statement.

MATCH (:Student {name:"Susan"})-[]->(c:Course)
RETURN sum(c.credit)

Result:

Returning by CASE

The CASE expression can be directly applied in the RETURN statement.

MATCH (n:Course)
RETURN n.name AS Course, CASE WHEN n.credit > 14 THEN "Y" ELSE "N" END AS Recommended

Result:

Returning Limited Records

The LIMIT statement can be used to restrict the number of rows returned.

MATCH (n:Course)
RETURN n.name LIMIT 1

Result:

Returning Ordered Records

The ORDER BY statement can be used to sort the rows according to the specified values.

MATCH (n:Course)
RETURN n ORDER BY n.credit DESC

Result: n

Returning with Grouping

The GROUP BY clause can be optionally used to group the final table.

MATCH ()-[e:Take]->()
RETURN e.term AS Term, count(e) GROUP BY Term

Result: