RETURN clause

The RETURN clause defines which data should be included in the resulting set.

Dataset

The following examples are executed with this dataset. You can create this dataset locally by executing the queries at the end of the page: Dataset queries.

Data set

1. Returning nodes

The node variable needs to be added to the RETURN statement:

MATCH (c:Country {name: 'United Kingdom'})
RETURN c;

Output:

+-----------------------------------------------------------------------------------------------------+
| c                                                                                                   |
+-----------------------------------------------------------------------------------------------------+
| (:Country {continent: "Europe", language: "English", name: "United Kingdom", population: 66000000}) |
+-----------------------------------------------------------------------------------------------------+

2. Returning relationships

The relationship variable needs to be added to the RETURN statement:

MATCH (c:Country {name: 'United Kingdom'})<-[r]-(:Person {name: 'Harry'})
RETURN type(r);

Output:

+------------+
| type(r)    |
+------------+
| WORKING_IN |
| LIVING_IN  |
+------------+

3. Returning properties

The property of a node or a relationship can be returned by using the dot separator:

MATCH (c:Country {name: 'United Kingdom'})
RETURN c.name;

Output:

+----------------+
| c.name         |
+----------------+
| United Kingdom |
+----------------+

4. Returning multiple elements

To return multiple elements separate them with a comma character:

MATCH (c:Country {name: 'United Kingdom'})
RETURN c.name, c.population, c.continent;

Output:

+----------------+----------------+----------------+
| c.name         | c.population   | c.continent    |
+----------------+----------------+----------------+
| United Kingdom | 66000000       | Europe         |
+----------------+----------------+----------------+

5. Returning all elements

To return all the elements from a query, use the * symbol:

MATCH (:Country {name: 'United Kingdom'})-[]-(p:Person)
RETURN *;

Output:

+---------------------------+
| p                         |
+---------------------------+
| (:Person {name: "Harry"}) |
| (:Person {name: "Harry"}) |
| (:Person {name: "Anna"})  |
+---------------------------+

6. Handling uncommon characters

Uncommon characters are handled using placeholder variables enclosed with the symbol ```. For example, a query could look like this:

MATCH (`An uncommon variable!`)
WHERE `An uncommon variable!`.name = 'A'
RETURN `An uncommon variable!`.value;

7. Returning elements with an alias

You can specify an alias for an element in the RETURN statement using AS:

MATCH (c:Country {name: 'United Kingdom'})
RETURN c.name AS Name;

Output:

+----------------+
| Name           |
+----------------+
| United Kingdom |
+----------------+

8. Optional properties

If the property being returned does not exist, null will be returned:

MATCH (c:Country {name: 'United Kingdom'})
RETURN c.color;

Output:

+---------+
| c.color |
+---------+
| Null    |
+---------+

9. Returning expressions

Expressions can be included in the RETURN statement:

MATCH (c:Country {name: 'United Kingdom'})
RETURN c.name = 'United Kingdom', "Literal";

Output:

+---------------------------+---------------------------+
| c.name = 'United Kingdom' | "Literal"                 |
+---------------------------+---------------------------+
| true                      | Literal                   |
+---------------------------+---------------------------+

10. Returning unique results

The RETURN statement can be followed by the DISTINCT operator, which will remove duplicate results:

MATCH ()-[:LIVING_IN]->(c)
RETURN DISTINCT c;

Output:

+-----------------------------------------------------------------------------------------------------+
| c                                                                                                   |
+-----------------------------------------------------------------------------------------------------+
| (:Country {continent: "Europe", language: "German", name: "Germany", population: 83000000})         |
| (:Country {continent: "Europe", language: "English", name: "United Kingdom", population: 66000000}) |
+-----------------------------------------------------------------------------------------------------+

11. Returning aggregated results

The RETURN statement can be used with Aggregation functions:

MATCH (c:Country)
RETURN AVG(c.population) as average_population;

Output:

+-----------------------------------------------------------------------------------------------------+
| population                                                                                          |
+-----------------------------------------------------------------------------------------------------+
| 72,000,000                                                                                           |
+-----------------------------------------------------------------------------------------------------+

Aggregations functions can be also used with DISTINCT operator, which will performe calculations only on unique values:

MATCH ()-[:LIVING_IN]->(c)
RETURN AVG(DISTINCT c.population) as average population;

Output:

+-----------------------------------------------------------------------------------------------------+
| population                                                                                          |
+-----------------------------------------------------------------------------------------------------+
| 74,500,000                                                                                            |
+-----------------------------------------------------------------------------------------------------+

12. Limiting the number of returned results

You can limit the number of returned results with the LIMIT sub-clause. To get the first ten results, you can use this query:

MATCH (n:Person) RETURN n LIMIT 10;

13. Order results

Since the patterns which are matched can come in any order, it is very useful to be able to enforce some ordering among the results. In such cases, you can use the ORDER BY sub-clause.

For example, the following query will get all :Person nodes and order them by their names:

MATCH (n:Person) RETURN n ORDER BY n.name;

By default, ordering will be ascending. To change the order to be descending, you should append DESC.

For example, you can use this query to order people by their name descending:

MATCH (n:Person) RETURN n ORDER BY n.name DESC;

You can also order by multiple variables. The results will be sorted by the first variable listed. If the values are equal, the results are sorted by the second variable, and so on.

For example, ordering by first name descending and last name ascending:

MATCH (n:Person) RETURN n ORDER BY n.name DESC, n.lastName;

Note that ORDER BY sees only the variable names as carried over by RETURN. This means that the following will result in an error.

MATCH (old:Person) RETURN old AS new ORDER BY old.name;

Instead, the new variable must be used:

MATCH (old:Person) RETURN old AS new ORDER BY new.name;

The ORDER BY sub-clause may come in handy with SKIP and/or LIMIT sub-clauses. For example, to get the oldest person you can use the following:

MATCH (n:Person) RETURN n ORDER BY n.age DESC LIMIT 1;

You can also order result before returning them. The following query will order all the nodes according to name, and then return them in a list.

MATCH (n)
WITH n ORDER BY n.name DESC
RETURN collect(n.name) AS names;

Dataset queries

We encourage you to try out the examples by yourself. You can get our dataset locally by executing the following query block.

MATCH (n) DETACH DELETE n;
 
CREATE (c1:Country {name: 'Germany', language: 'German', continent: 'Europe', population: 83000000});
CREATE (c2:Country {name: 'France', language: 'French', continent: 'Europe', population: 67000000});
CREATE (c3:Country {name: 'United Kingdom', language: 'English', continent: 'Europe', population: 66000000});
 
MATCH (c1),(c2)
WHERE c1.name= 'Germany' AND c2.name = 'France'
CREATE (c2)<-[:WORKING_IN {date_of_start: 2014}]-(p:Person {name: 'John'})-[:LIVING_IN {date_of_start: 2014}]->(c1);
 
MATCH (c)
WHERE c.name= 'United Kingdom'
CREATE (c)<-[:WORKING_IN {date_of_start: 2014}]-(p:Person {name: 'Harry'})-[:LIVING_IN {date_of_start: 2013}]->(c);
 
MATCH (p1),(p2)
WHERE p1.name = 'John' AND p2.name = 'Harry'
CREATE (p1)-[:FRIENDS_WITH {date_of_start: 2011}]->(p2);
 
MATCH (p1),(p2)
WHERE p1.name = 'John' AND p2.name = 'Harry'
CREATE (p1)<-[:FRIENDS_WITH {date_of_start: 2012}]-(:Person {name: 'Anna'})-[:FRIENDS_WITH {date_of_start: 2014}]->(p2);
 
MATCH (p),(c1),(c2)
WHERE p.name = 'Anna' AND c1.name = 'United Kingdom' AND c2.name = 'Germany'
CREATE (c2)<-[:LIVING_IN {date_of_start: 2014}]-(p)-[:LIVING_IN {date_of_start: 2014}]->(c1);
 
MATCH (n)-[r]->(m) RETURN n,r,m;