10.1. Return

The RETURN clause defines what to include in the query result set.

In the RETURN part of your query, you define which parts of the pattern you are interested in. It can be nodes, relationships, or properties on these.

[Tip]Tip

If what you actually want is the value of a property, make sure to not return the full node/relationship. This will improve performance.

Figure 10.1. Graph

cypher-return-graph.svg

Return nodes

To return a node, list it in the RETURN statement.

Query  

MATCH (n { name: "B" })
RETURN n

The example will return the node.

Result

n
1 row

Node[1]{name:"B"}

Try this query live create (_0 {`age`:55, `happy`:"Yes!", `name`:"A"}) create (_1 {`name`:"B"}) create (_0)-[:`BLOCKS`]->(_1) create (_0)-[:`KNOWS`]->(_1) ; match (n {name: "B"}) return n

Return relationships

To return a relationship, just include it in the RETURN list.

Query  

MATCH (n { name: "A" })-[r:KNOWS]->(c)
RETURN r

The relationship is returned by the example.

Result

r
1 row

:KNOWS[0]{}

Try this query live create (_0 {`age`:55, `happy`:"Yes!", `name`:"A"}) create (_1 {`name`:"B"}) create (_0)-[:`BLOCKS`]->(_1) create (_0)-[:`KNOWS`]->(_1) ; match (n {name: "A"})-[r:KNOWS]->(c) return r

Return property

To return a property, use the dot separator, like this:

Query  

MATCH (n { name: "A" })
RETURN n.name

The value of the property name gets returned.

Result

n.name
1 row

"A"

Try this query live create (_0 {`age`:55, `happy`:"Yes!", `name`:"A"}) create (_1 {`name`:"B"}) create (_0)-[:`BLOCKS`]->(_1) create (_0)-[:`KNOWS`]->(_1) ; match (n {name: "A"}) return n.name

Return all elements

When you want to return all nodes, relationships and paths found in a query, you can use the * symbol.

Query  

MATCH p=(a { name: "A" })-[r]->(b)
RETURN *

This returns the two nodes, the relationship and the path used in the query.

Result

abpr
2 rows

Node[0]{name:"A",happy:"Yes!",age:55}

Node[1]{name:"B"}

[Node[0]{name:"A",happy:"Yes!",age:55},:BLOCKS[1]{},Node[1]{name:"B"}]

:BLOCKS[1]{}

Node[0]{name:"A",happy:"Yes!",age:55}

Node[1]{name:"B"}

[Node[0]{name:"A",happy:"Yes!",age:55},:KNOWS[0]{},Node[1]{name:"B"}]

:KNOWS[0]{}

Try this query live create (_0 {`age`:55, `happy`:"Yes!", `name`:"A"}) create (_1 {`name`:"B"}) create (_0)-[:`BLOCKS`]->(_1) create (_0)-[:`KNOWS`]->(_1) ; match p=(a {name: "A"})-[r]->(b) return *

Variable with uncommon characters

To introduce a placeholder that is made up of characters that are outside of the english alphabet, you can use the ` to enclose the variable, like this:

Query  

MATCH (`This isn't a common variable`)
WHERE `This isn't a common variable`.name='A'
RETURN `This isn't a common variable`.happy

The node with name "A" is returned

Result

`This isn't a common variable`.happy
1 row

"Yes!"

Try this query live create (_0 {`age`:55, `happy`:"Yes!", `name`:"A"}) create (_1 {`name`:"B"}) create (_0)-[:`BLOCKS`]->(_1) create (_0)-[:`KNOWS`]->(_1) ; match (`This isn't a common variable`) where `This isn't a common variable`.name='A' return `This isn't a common variable`.happy

Column alias

If the name of the column should be different from the expression used, you can rename it by using AS <new name>.

Query  

MATCH (a { name: "A" })
RETURN a.age AS SomethingTotallyDifferent

Returns the age property of a node, but renames the column.

Result

SomethingTotallyDifferent
1 row

55

Try this query live create (_0 {`age`:55, `happy`:"Yes!", `name`:"A"}) create (_1 {`name`:"B"}) create (_0)-[:`BLOCKS`]->(_1) create (_0)-[:`KNOWS`]->(_1) ; match (a {name: "A"}) return a.age AS SomethingTotallyDifferent

Optional properties

If a property might or might not be there, you can still select it as usual. It will be treated as NULL if it is missing

Query  

MATCH (n)
RETURN n.age

This example returns the age when the node has that property, or null if the property is not there.

Result

n.age
2 rows

55

<null>

Try this query live create (_0 {`age`:55, `happy`:"Yes!", `name`:"A"}) create (_1 {`name`:"B"}) create (_0)-[:`BLOCKS`]->(_1) create (_0)-[:`KNOWS`]->(_1) ; match (n) return n.age

Other expressions

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

Query  

MATCH (a { name: "A" })
RETURN a.age > 30, "I'm a literal",(a)-->()

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

Result

a.age > 30"I'm a literal"(a)-->()
1 row

true

"I'm a literal"

[[Node[0]{name:"A",happy:"Yes!",age:55},:BLOCKS[1]{},Node[1]{name:"B"}],[Node[0]{name:"A",happy:"Yes!",age:55},:KNOWS[0]{},Node[1]{name:"B"}]]

Try this query live create (_0 {`age`:55, `happy`:"Yes!", `name`:"A"}) create (_1 {`name`:"B"}) create (_0)-[:`BLOCKS`]->(_1) create (_0)-[:`KNOWS`]->(_1) ; match (a {name: "A"}) return a.age > 30, "I'm a literal", (a)-->()

Unique results

DISTINCT retrieves only unique rows depending on the columns that have been selected to output.

Query  

MATCH (a { name: "A" })-->(b)
RETURN DISTINCT b

The node named B is returned by the query, but only once.

Result

b
1 row

Node[1]{name:"B"}

Try this query live create (_0 {`age`:55, `happy`:"Yes!", `name`:"A"}) create (_1 {`name`:"B"}) create (_0)-[:`BLOCKS`]->(_1) create (_0)-[:`KNOWS`]->(_1) ; match (a {name: "A"})-->(b) return distinct b