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.

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

• (openCypher) Clauses are chained together, and they feed intermediate result sets between each other.

• (Native nGQL) More than one query can be batched together, separated by semicolons (;). The result of the last query is returned as the result of the batch.

• (Native nGQL) Queries can be piped together by using the pipe (|). The result of the previous query can be used as the input of the next query.

OpenCypher compatibility

In a composite query, do not put together openCypher and native nGQL clauses in one statement. For example, this statement is undefined: MATCH ... | GO ... | YIELD ....

• If you are in the openCypher way (MATCH, RETURN, WITH, etc), do not introduce any pipe or semicolons to combine the sub-clauses.

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

Undefined behavior

Do not put together native nGQL and openCypher compatible sentences in one composite statement because this behavior is undefined.

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

For example, a query is 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 will be undefined. There is no rollback. What is written depends on the query executor.

Note

OpenCypher has no requirement of transaction.

Examples

• OpenCypher compatibility statement

  # Connect multiple queries with clauses.
  nebula> MATCH p=(v:player{name:"Tim Duncan"})--() \
          WITH nodes(p) AS n \
          UNWIND n AS n1 \
          RETURN DISTINCT n1;
  

• Native nGQL (Semicolon queries)

  # Only return edges.
  nebula> SHOW TAGS; SHOW EDGES;
  
  # Insert multiple vertices.
  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);
  

• Native nGQL (Pipe queries)

  # Connect multiple queries with pipes.
  nebula> GO FROM "player100" OVER follow YIELD dst(edge) AS id | \
          GO FROM $-.id OVER serve YIELD properties($$).name AS Team, \
          properties($^).name AS Player;
  +-----------+-----------------+
  | Team      | Player          |
  +-----------+-----------------+
  | "Spurs"   | "Tony Parker"   |
  | "Hornets" | "Tony Parker"   |
  | "Spurs"   | "Manu Ginobili" |
  +-----------+-----------------+
  

---

Last update: March 13, 2023