RETURN

In the RETURN part of your query, you define which parts of the pattern you want to output. Output can include agtype values, nodes, relationships, or properties.

Return nodes

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

Query

SELECT *
FROM cypher('graph_name', $$
    MATCH (n {name: 'B'})
    RETURN n
$$) as (n agtype);

The example will return the node.

Result

n

{id: 0; label: ‘’ properties: {name: ‘B’}}::vertex

(1 row)

Return edges

To return n’s edges, just include it in the RETURN list.

Query

SELECT *
FROM cypher('graph_name', $$
    MATCH (n)-[r:KNOWS]->()
    WHERE n.name = 'A'
    RETURN r
$$) as (r agtype);

The relationship is returned by the example.

r

{id: 2; startid: 0; endid: 1; label: ‘KNOWS’ properties: {}}::edge

(1 row)

Return property

To return a property, use the dot separator, as follows:

Query

SELECT *
FROM cypher('graph_name', $$
    MATCH (n {name: 'A'})
    RETURN n.name
$$) as (name agtype);

The value of the property name gets returned.

Result

name

‘A’

(1 row)

Return all elements

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

Query

SELECT *
FROM cypher('graph_name', $$
	MATCH (a {name: 'A'})-[r]->(b)
	RETURN *
$$) as (a agtype, b agtype, r agtype);

This returns the two vertices, and the edge used in the query.

Result

a	b	r
{"id": 281474976710659, "label": "", "properties": {"age": 55, "name": "A", "happy": "Yes!"}}::vertex	{"id": 1125899906842625, "label": "BLOCKS", "end_id": 281474976710660, "start_id": 281474976710659, "properties": {}}::edge	{"id": 281474976710660, "label": "", "properties": {"name": "B"}}::vertex
{"id": 281474976710659, "label": "", "properties": {"age": 55, "name": "A", "happy": "Yes!"}}::vertex	{"id": 1407374883553281, "label": "KNOWS", "end_id": 281474976710660, "start_id": 281474976710659, "properties": {}}::edge	{"id": 281474976710660, "label": "", "properties": {"name": "B"}}::vertex
(2 rows)

Variable with uncommon characters

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

Query

SELECT *
FROM cypher('graph_name', $$
    MATCH (`This isn\'t a common variable`)
    WHERE `This isn\'t a common variable`.name = 'A'
    RETURN `This isn\'t a common variable`.happy
$$) as (happy agtype);

The node with name “A” is returned.

Result

happy

"Yes!"

(1 row)

Aliasing a field

If the name of the field should be different from the expression used, you can rename it by changing the name in the column list definition.

Query

SELECT *
FROM cypher('graph_name', $$
    MATCH (n {name: 'A'})
    RETURN n.name
$$) as (objects_name agtype);

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

Result

objects_name

‘A’

(1 row)

Optional properties

If a property might or might not be there, it will be treated as null if it is missing.

Query

SELECT *
FROM cypher('graph_name', $$
    MATCH (n)
    RETURN n.age
$$) as (age agtype);

This query returns the property if it exists, or null if the property does not exist.

Result

age

55

NULL

(2 rows)

Other expressions

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

Query

SELECT *
FROM cypher('graph_name', $$
    MATCH (a)
    RETURN a.age > 30, 'I'm a literal', id(a)
$$) as (older_than_30 agtype, literal agtype, id agtype);

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

Result

older_than_30	literal	id
true	‘I’m a literal’	1
(1 row)

Pattern expressions in projections

A pattern expression is a path pattern, such as (a)-[:KNOWS]->(:Person), used in a position where a value is expected. It evaluates to a boolean that is true when at least one matching path exists. In addition to being used as a predicate in a WHERE clause, a pattern expression can be returned directly from a RETURN (or WITH) projection.

Query

SELECT *
FROM cypher('graph_name', $$
    MATCH (a:Person)
    RETURN a.name, (a)-[:KNOWS]->(:Person) AS knows_someone
    ORDER BY a.name
$$) as (name agtype, knows_someone agtype);

For each person, this returns a boolean indicating whether they have an outgoing KNOWS relationship to another Person.

Result

name	knows_someone
"A"	true
"B"	true
"C"	true
"D"	false
"D"	false
(5 rows)

Performance: A pattern expression is evaluated as an EXISTS subquery. In a projection it is evaluated once for every row produced by the match, so its cost grows with the number of rows returned. Returning several pattern expressions, or returning them over a large result set, can be expensive on large graphs; where possible, narrow the result set with a WHERE clause before projecting pattern expressions.

Unique results

DISTINCT retrieves only unique records depending on the fields that have been selected to output.

Query

SELECT *
FROM cypher('graph_name', $$
MATCH (a {name: 'A'})-[]->(b)
RETURN DISTINCT b
$$) as (b agtype);

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

Result

b

{id: 1; label: ‘’ properties: {name: ‘B’}}::vertex

(1 row)