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.

NOTE: 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: February 24, 2021