Release History
Help

YMatrix

Quick Start

Deployment

Data Usage

Manage Clusters

Security

Best Practice

Technical Principles

Advanced Features

Graph Database

Guide

SQL Reference

FAQ

RETURN

In the RETURN part of a query, you specify which parts of the matched pattern to output. Output may include agtype values, vertices, edges, or properties.

Returning Vertices

To return a vertex, list it in the RETURN clause.

Query

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

Returns the vertex.

Result

n
{id: 0; label: ''; properties: {name: 'B'}}::vertex
(1 row)

Returning Edges

To return an edge associated with n, include it directly in the RETURN list.

Query

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

Returns the relationship.

r
{id: 2; startid: 0; endid: 1; label: 'KNOWS'; properties: {}}::edge
(1 row)

Returning Properties

To return a property, use dot notation.

Query

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

Returns the value of the name property.

Result

name
'A'
(1 row)

Returning All Elements

Use * to return all vertices, edges, and paths found by the query.

Query

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

Returns both vertices and the edge used in the pattern.

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)

Variables Containing Special Characters

To use placeholders composed of non-alphanumeric characters, enclose the variable name in backticks (`).

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);

Returns the happy property of the vertex named "A".

Result

happy
"Yes!"
(1 row)

Column Aliasing

To assign a different name to a returned field than the expression used, rename it in the column definition list.

Query

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

Returns the name property of the vertex, but renames the output column.

Result

objects_name
'A'
(1 row)

Optional Properties

If a property may be absent, its value is treated as NULL.

Query

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

Returns the age property if present; otherwise returns NULL.

Result

age
55
NULL
(2 rows)

Other Expressions

Any expression — literals, predicates, properties, functions, or combinations — may appear in RETURN.

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 string, and a function call with a pattern expression argument.

Result

older_than_30 literal id
true 'I''m a literal' 1
(1 row)

Deduplicating Results

DISTINCT retrieves only unique rows based on the selected output fields.

Note!
Although every vertex has a unique id, DISTINCT is most relevant when the same vertex is matched multiple times via different relationships.
For example:
(A)-[:KNOWS]->(B) and (A)-[:LIKES]->(B).
Executing MATCH (a {name: 'A'})-[]->(b) RETURN b matches B twice — once via KNOWS, once via LIKES — returning two identical rows.
With DISTINCT, B appears only once.

Query

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

Returns the vertex named "B", but only once.

Result

b
{id: 1; label: ''; properties: {name: 'B'}}::vertex
(1 row)
← Previous
MATCH
Next →
WITH