Skip to content

Composite queries (clause structure)

Composite queries put data from different queries together. They then use filters, group-bys, or sorting before returning the combined return results. A composite query retrieves multiple levels of related information on existing queries and presents data as a single return result.

Nebula Graph supports three methods to compose queries (or sub-queries):

  • (OpenCypher style) Clauses are chained together, and they feed intermediate result sets between each other.
  • (nGQL extension) More than one queries can be batched together, separated by semicolons (;). The result of the last query is returned as the result of the batch.
  • (nGQL extension) Queries can be piped together by using the pipe operator (|). The result of the previous query can be used as the input of the next query.

OpenCypher compatibility

In a composite query, choose the openCypher-style or nGQL-extension. NOT BOTH.

For example, if you're in the openCypher way (MATCH, RETURN, WITH, etc), don't introduce any pipe or semicolons to combine the sub-clauses.

If you're in the nGQL-extension way (FETCH, GO, LOOKUP, etc), you must use pipe or semicolons to combine the sub-clauses.

Further more, don't put together openCypher and nGQL-extension clauses in one statement. E.g., This statement is undefined: MATCH ... | GO ... | YIELD ....

Composite queries are not transactional queries (as in SQL/Cypher)

For example, a query composed of three sub-queries: A B C, A | B | C or A; B; C. In that A is a read operation, B is a computation operation, and C is a write operation. If any part fails in the execution, the whole result is undefined. There is no rollback. What is written depends on the query executor.


OpenCypher has no requirement of transaction.


  • OpenCypher style
nebula> MATCH p=(v:player{name:"Tim Duncan"})--() \
        WITH nodes(p) AS n \
        UNWIND n AS n1 \
  • Semicolon queries
nebula> SHOW TAGS; SHOW EDGES;   // Only edges are shown.

nebula> INSERT VERTEX player(name, age) VALUES "player100":("Tim Duncan", 42); \
INSERT VERTEX player(name, age) VALUES "player101":("Tony Parker", 36); \
INSERT VERTEX player(name, age) VALUES "player102":("LaMarcus Aldridge", 33);
// Multiple vertices are inserted in a composite statement.
  • Pipe queries
nebula> GO FROM "player100" OVER follow YIELD follow._dst AS id | \
    GO FROM $ OVER serve YIELD $$ AS Team, \
    $^ AS Player;
    | Team    | Player      |
    | Nuggets | Tony Parker |

Last update: April 22, 2021