RETURN

Introduction

The RETURN clause defines the parts of a pattern (nodes, relationships, and/or properties) to be included in the query result.

Example graph

The following graph is used for the examples below:

graph return clause

To recreate the graph, run the following query against an empty Neo4j database.

CREATE
  (keanu:Person {name: 'Keanu Reeves', bornIn: 'Beirut', nationality: 'Canadian'}),
  (taiChi:Movie {title: 'Man of Tai Chi', released: 2013}),
  (keanu)-[:ACTED_IN]->(taiChi),
  (keanu)-[:DIRECTED]->(taiChi)

Return nodes

To return a node, list it in the RETURN clause:

Query
MATCH (p:Person {name: 'Keanu Reeves'})
RETURN p
Table 1. Result
p

{"bornIn":"Beirut","nationality":"Canadian","name":"Keanu Reeves"}

Rows: 1

Return relationships

To return a relationship type, list it in the RETURN clause:

Query
MATCH (p:Person {name: 'Keanu Reeves'})-[r:ACTED_IN]->(m)
RETURN type(r)
Table 2. Result
type(r)

"ACTED_IN"

Rows: 1

Return property

To return a specific property, use the dot separator:

Query
MATCH (p:Person {name: 'Keanu Reeves'})
RETURN p.bornIn
Table 3. Result
p.bornIn

"Beirut"

Rows: 1
It is more performant to return properties rather than the full node or relationship.

Return all elements

To return all nodes, relationships and paths found in a query, use the * symbol:

Query
MATCH p = (keanu:Person {name: 'Keanu Reeves'})-[r]->(m)
RETURN *

This returns the two nodes, and the two possible paths between them.

Table 4. Result
keanu m p r

{"bornIn":"Beirut","nationality":"Canadian","name":"Keanu Reeves"}

{"title":"Man of Tai Chi","released":2013}

(:Person {bornIn: "Beirut",nationality: "Canadian",name: "Keanu Reeves"})-[:ACTED_IN]→(:Movie {title: "Man of Tai Chi",released: 2013})

{:ACTED_IN}

{"bornIn":"Beirut","nationality":"Canadian","name":"Keanu Reeves"}

{"title":"Man of Tai Chi","released":2013}

(:Person {bornIn: "Beirut",nationality: "Canadian",name: "Keanu Reeves"})-[:DIRECTED]→(:Movie {title: "Man of Tai Chi",released: 2013})

{:DIRECTED}

Rows: 1

Variable with uncommon characters

To introduce a variable made up of characters not contained in the English alphabet, use ` to enclose the variable:

Query
MATCH (`/uncommon variable\`)
WHERE `/uncommon variable\`.name = 'Keanu Reeves'
RETURN `/uncommon variable\`.bornIn

The bornIn property of the node with the name property set to 'Keanu Reeves' is returned:

Table 5. Result
/uncommon variable\.bornIn

"Beirut"

Rows: 1

Column alias

Names of returned columns can be renamed using the AS operator:

Query
MATCH (p:Person {name: 'Keanu Reeves'})
RETURN p.nationality AS citizenship

Returns the nationality property of 'Keanu Reeves', but the column is renamed to citizenship.

Table 6. Result
citizenship

"Canadian"

Rows: 1

Optional properties

If the existence of a property is unknown, it can still be included in a RETURN clause. It will be treated as null if it is missing.

Query
MATCH (n)
RETURN n.bornIn

This example returns the bornIn properties for nodes that has that property, and null for those nodes missing the property.

Table 7. Result
n.bornIn

"Beirut"

<null>

Rows: 2

Other expressions

Any expression can be used as a return item — literals, predicates, properties, functions, and so on.

Query
MATCH (m:Movie {title: 'Man of Tai Chi'})
RETURN m.released < 2012, "I'm a literal",[p=(m)--() | p] AS `(m)--()`

Returns a predicate, a literal and function call with a pattern expression parameter:

Table 8. Result
m.released < 2012 "I’m a literal" (m)--()

false

"I’m a literal"

[(:Movie {title: "Man of Tai Chi",released: 2013})←[:DIRECTED]-(:Person {bornIn: "Beirut",nationality: "Canadian",name: "Keanu Reeves"}), (:Movie {title: "Man of Tai Chi",released: 2013})←[:ACTED_IN]-(:Person {bornIn: "Beirut",nationality: "Canadian",name: "Keanu Reeves"})]

Rows: 1

Unique results

DISTINCT retrieves only unique rows for the columns that have been selected for output.

Query
MATCH (p:Person {name: 'Keanu Reeves'})-->(m)
RETURN DISTINCT m

The Movie node 'Man of Tai Chi' is returned by the query, but only once (without the DISTINCT operator it would have been returned twice because there are two relationships going to it from 'Keanu Reeves'):

Table 9. Result
m

{"title":"Man of Tai Chi","released":2013}+

Rows: 1