Clauses

RETURN

The RETURN clause is used to state the returned attribute as a result of cypher query. It returns vertex, edge, property, etc. of matched graph pattern.

  • Vertex Return

    MATCH (j {name: 'Jack'})
RETURN j;

    To return vertex, the vertex you want to get returned should be defined in the MATCH clause and its variable should be assigned. Then, the vertex will be returned after defined in RETURN clause.

  • Edge Return

    MATCH (j {name: 'Jack'})-[k:knows]->(e)
RETURN k;

    To return edge, the edge you want to get returned should be defined in the MATCH clause and its variable should be assigned. Then, the edge will be returned after defined in RETURN clause.

  • Property Return

    MATCH (j {name: 'Jack'})
RETURN j.age;

    To return property of vertex or edge, the vertex or edge you want to find should be defined in the MATCH clause and their variables should be assigned. Then, the property will be returned with following variable and dot (.) after defined in the RETURN clause.

  • All Return

    MATCH (j {name: 'Jack'})-[k:knows]->(e)
RETURN *;

    To return all elements in MATCH clause, simply put an asterisk in RETURN clause. In this case, only element having variable will be returned.

  • Path Return

    MATCH p=(j {name: 'Jack'})-[k:knows]->(e)
RETURN p;

    To return matched path of pattern in MATCH clause, the pattern must have variable. Put the variable and equal symbol (=) before the pattern to assign a variable to the pattern. Then, the path will be returned after defined in RETURN clause.

  • Alias Return

    Query :

    MATCH (j {name: 'Jack'})
RETURN j.age AS HisAge;

    Result :

     hisage
--------
 24

    Query :

    MATCH (j {name: 'Jack'})
RETURN j.age AS "HisAge";

    Result :

     HisAge
--------
 24

    It is possible to assign an alias to the returned result with AS keyword and alias following result. Without double quotes, the alias will be displayed in lower case. Wrap the alias with double quotes, if you want it be displayed in upper case.

  • Expression Return

    RETURN 'Hello World~!';

RETURN 1219, 33.33;

MATCH (j {name: 'Jack'}), (e {name: 'Emily'})
RETURN j.age > e.age;

    It is possible to display not only the attributes defined in the pattern but also the expression. String, number, or expression with boolean result can be displayed.

  • DISTINCT Return

    Query :

    MATCH (:person {name:'Jack'})-[:knows]->()-[:knows]->(fof)   
RETURN fof.name;

    Result :

     name
--------
 Tom
 Rachel
 Edward
 Emily
 Amy
 Paul
 Rachel
(7 rows)

    Query :

    MATCH (:person {name:'Jack'})-[:knows]->()-[:knows]->(fof)   
RETURN DISTINCT fof.name;

    Result :

     name
--------
 Tom
 Rachel
 Edward
 Emily
 Amy
 Paul
(6 rows)

    There are some cases that you can find duplicated data in the result. To avoid this case, you will need DISTINCT keyword.

ORDER BY

ORDER BY clause is for ordering of result. It is used with RETURN or WITH clause and ascending or descending order can be set.

  • Order by Property

    MATCH (a:person)
RETURN a.name AS NAME
ORDER BY NAME;

MATCH (a:person)
RETURN a.name AS NAME, a.age AS AGE
ORDER BY NAME, AGE;

MATCH (a:person)
RETURN a
ORDER BY a.name;

    Basically ORDER BY clause arrange the vertex, edge, or property, so the alias of ordering standard should be defined in ORDER BY clause. That is, the alias of property which will be the standard ordering should be defined first and put in the ORDER BY clause. If there are multiple standards in ORDER BY clause, the result will be arranged by the first ordering standard first and the following ordering standard will be adapted to. If you do not want to use alias, the property can be defined in ORDER BY clause instead.

  • Descending Order

    MATCH (a:person)
RETURN a.name AS NAME
ORDER BY NAME DESC;

MATCH (a:person)
RETURN a.name AS NAME, a.age AS AGE
ORDER BY NAME DESC, AGE;

    ORDER BY clause operates ascending order as default. For descending order, put DESC. If there are multiple standards in ORDER BY clause and you want some of them work in descending order, put DESC after the standard you want .

  • Ordering NULL

    Query :

    MATCH (a:person)
RETURN a.name AS NAME, a.hobby
ORDER BY hobby DESC;

    Result :

       name   |       hobby        
----------+--------------------
 Emily    | 
 Tom      | 
 Carl     | 
 Denny    | 
 Amy      | 
 Rachel   | 
 Paul     | 
 Alice    | 
 Kelly    | 
 Sally    | 
 Angela   | 
 John     | 
 Martin   | 
 Peter    | 
 Thomas   | 
 William  | 
 Henry    | 
 Jennifer | 
 Nicole   | 
 Sharon   | 
 James    | 
 Robert   | 
 Michael  | 
 Edward   | 
 Jack     | Playing the guitar
(25 rows)

    Elements that do not have the property specified in the ORDER BY clause are printed as null. When sorting the result set, null will always come at the end of the result set. If you output a result set that contains null using the DESC keyword, null will be printed at the top of the result.

LIMIT

The LIMIT clause is a clause that limits the number of results in a result set.

  • Limit Result Set

    MATCH (a)
RETURN a.name
LIMIT 10;

    If you want to limit the number of results you want to output, you can specify the number in the LIMIT clause. If the number of results in the result set is less than or equal to the number specified in the LIMIT clause, all results will be output.

  • LIMIT With ORDER BY

    MATCH (a)
RETURN a.name AS NAME
ORDER BY NAME
LIMIT 10;

MATCH (a)
RETURN a.name AS NAME
ORDER BY NAME DESC
LIMIT 10;

    The LIMIT clause often used with the ORDER BY clause. If you want to print only the top few, use both. To sort the records in descending order, use the DESC keyword.

SKIP

The SKIP clause is a clause that changes the search start location.

  • Skip

    Query :

    MATCH (a)
RETURN a.name;

    Result :

       name   
----------
 Emily     
 Tom       
 Carl      
 Denny     
 Amy       
 Rachel    
  .
  .
  .

    Query :

    MATCH (a)
RETURN a.name
SKIP 3;

    Result :

       name           
----------
 Denny     
 Amy       
 Rachel    
 Paul      
 Alice     
 Kelly    
  .
  .
  .

    When searching for a pattern in the MATCH clause, skip the number specified in the SKIP clause and start the search.

  • SKIP With ORDER BY

    MATCH (a)
RETURN a.name AS NAME
ORDER BY NAME
SKIP 3;

    If the ORDER BY clause is used together, it will sort and skip the number specified in the SKIP clause and start the search. Use it when you want to return a few except the top.

  • SKIP With ORDER BY And LIMIT

    MATCH (a)
RETURN a.name AS NAME
ORDER BY NAME
SKIP 3
LIMIT 7;

    If you want to return a few intermediate values from the top, use the SKIP clause with the ORDER BY and LIMIT clauses.

WITH

The WITH clause is a clause that connects multiple cypher queries. That is, the WITH clause can be regarded as a RETURN clause that passes the value of the preceding query to the input of the following query.

  • WITH

    MATCH (j:person {name:'Jack'})-[:knows]->(common:person)<-[:knows]-(other:person)
RETURN other, count(common);

WHERE count(common) > 1
RETURN other;

MATCH (j:person {name:'Jack'})-[:knows]->(common:person)<-[:knows]-(other:person)
WITH other, count(common) AS cnt
WHERE cnt > 1
RETURN other;

    The WITH clause is described as an example of the above three queries. The first query returns the number of acquaintances that Jack and ‘someone’ know in common, along with the ‘someone’. If the second query is related to the first query, it can be understood that the query is a query that returns ‘someone’ corresponding to a case where the number of common acquaintances is greater than one. The second query can not be executed alone, and the second query has a meaning when it is combined with the first query. The WITH clause plays a role of connecting the two queries.
    The third query is a query that includes a WITH clause that links the first and second queries. It holds the results of the first query in variable, alias form, and passes the results to the second query. If you want to connect several queries like this case and the output of the preceding query is used as the input of the trailing query, you can connect it with the WITH clause. The WITH clause must be held in variable or alias form.

  • Partitioning

    MATCH (j:person {name:'Jack'})-[:knows]->(common:person)<-[:knows]-(other:person)
RETURN other, count(common)
ORDER BY other.name
LIMIT 10;

WHERE count(common) > 1
RETURN other;

MATCH (j:person {name:'Jack'})-[:knows]->(common:person)<-[:knows]-(other:person)
WITH other, count(common) AS cnt
ORDER BY other.name
LIMIT 10
WHERE cnt > 1
RETURN other;

    It is important to partition the entire query when using the WITH clause. Consider the WITH clause as a RETURN clause and the ORDER BY and LIMIT clauses that come after a RETURN as a partition. Therefore, if there is an ORDER BY, LIMIT clause in the preceding query, you can write the clause after the WITH clause, and then create a trailing query.

UNION

The UNION clause combines the results of several queries into one.

  • UNION

    MATCH (a:person)
WHERE 20 < a.age::int
RETURN a.name AS name
UNION
MATCH (b:person)
WHERE b.age::int < 50
RETURN b.name AS name;

MATCH (a:person)
WHERE 20 < a.age::int
RETURN a.name AS name
UNION ALL
MATCH (b:person)
WHERE b.age::int < 50
RETURN b.name AS name;

    If you put the UNION keyword between two queries, you can combine the two results together. UNION prints duplicate values only once. When the UNION and ALL are used together, values are output as duplicates when combining the two results.

  • Precondition

    MATCH (a:person)
RETURN a.name AS AAA
UNION
MATCH (b:person)
RETURN b.age AS AAA;

MATCH (a:person)
RETURN a.name
UNION
MATCH (b:person)
RETURN b.age;

    To combine result set of two or more queries using the UNION operator, there are the basic rules. The number of elements specified in the RETURN clause of each query must be the same. It is only necessary to have the same number of elements specified in each query RETURN, even for different properties.