GO¶

OpenCypher compatibility¶

This page applies to nGQL extensions only.

Syntax¶

GO [[<M> TO] <N> STEPS ] FROM <vertex_list>
OVER <edge_type_list> [{REVERSELY | BIDIRECT}]
[ WHERE <expression> [ {AND | OR} expression ...]) ]
[YIELD [DISTINCT] <return_list>]
[| ORDER BY <expression> [{ASC | DESC}]]
[| LIMIT [<offset_value>,] <number_rows>]

GO [[<M> TO] <N> STEPS ] FROM <vertex_list>
OVER <edge_type_list> [{REVERSELY | BIDIRECT}]
[ WHERE <conditions>]
[| GROUP BY {col_name | expr | position} YIELD <col_name>]

<vertex_list> ::=
    <vid> [, <vid> ...]

<edge_type_list> ::=
   edge_type [, edge_type ...]
   | *

<return_list> ::=
    <col_name> [AS <col_alias>] [, <col_name> [AS <col_alias>] ...]

GO traverses in a graph with specified filters and returns results.

<N> STEPS specifies the hop number. If not specified, the default value for N is one. When N is zero, Nebula Graph does not traverse any edges and returns nothing.
M TO N STEPS traverses from M to N hops. When M is zero, the output is the same as that of M is one. That is, the output of GO 0 TO 2 and GO 1 TO 2 are the same.
<vertex_list> is a list of vertex IDs separated by commas, or a special place holder $-.id. For more information, see Pipe.
<edge_type_list>is a list of edge types which the traversal can go through.
REVERSELY | BIDIRECT defines the direction of the query. By default, GO statements searches for outgoing edges. If REVERSELY is set, GO searches for incoming edges. If BIDIRECT is set, GO searches for edges of both directions.
WHERE <expression> specifies the traversal filters. You can use WHERE for the source vertices, the edges, and the destination vertices. You can use WHERE together with AND, OR, and NOT. For more information, see WHERE.

NOTE: There are some restrictions for the WHERE clause when you traverse along with multiple edge types. For example, WHERE edge1.prop1 > edge2.prop2 is not supported.

YIELD [DISTINCT] <return_list> specifies the desired output. For more information, see YIELD. When not specified, the destination vertex IDs are returned by default.
ORDER BY sorts the outputs with the specified orders. For more information, see ORDER BY.

NOTE: When the sorting method is not specified, the output orders can be different for the same query.

LIMIT limits the row numbers for the output. For more information, see LIMIT.
GROUP BY groups outputs into subgroups based on values of the specified properties. For more information, see GROUP BY.

Examples¶

// Returns teams that player 102 serves.
nebula> GO FROM "player102" OVER serve;
+------------+
| serve._dst |
+------------+
| "team203"  |
+------------+
| "team204"  |
+------------+

// Returns the 2 hop friends of the player 102.
nebula> GO 2 STEPS FROM "player102" OVER follow;
+-------------+
| follow._dst |
+-------------+
| "player101" |
+-------------+
| "player125" |
+-------------+
...

// Adds a filter for the traversal then duplicates the output.
nebula> GO FROM "player100", "player102" OVER serve \
WHERE serve.start_year > 1995 \
YIELD DISTINCT $$.team.name AS team_name, serve.start_year AS start_year, $^.player.name AS player_name;
+-----------------+------------+---------------------+
| team_name       | start_year | player_name         |
+-----------------+------------+---------------------+
| "Spurs"         | 1997       | "Tim Duncan"        |
+-----------------+------------+---------------------+
| "Trail Blazers" | 2006       | "LaMarcus Aldridge" |
+-----------------+------------+---------------------+
| "Spurs"         | 2015       | "LaMarcus Aldridge" |
+-----------------+------------+---------------------+

// Traverses along with multiple edge types.
nebula> GO FROM "player100" OVER follow, serve YIELD follow.degree, serve.start_year;
+---------------+------------------+
| follow.degree | serve.start_year |
+---------------+------------------+
| 95            | __EMPTY__        |
+---------------+------------------+
| 95            | __EMPTY__        |
+---------------+------------------+
| __EMPTY__     | 1997             |
+---------------+------------------+

Nebula Graph displays different properties by columns. If there is no value for a property, the output is __EMPTY__.

// Returns player 100.
nebula> GO FROM "player100" OVER follow REVERSELY YIELD follow._dst AS destination;
+-------------+
| destination |
+-------------+
| "player101" |
+-------------+
| "player102" |
+-------------+
...

// This MATCH query shares the same semantics with the preceding GO query.
nebula> MATCH (v)<-[e:follow]- (v2) WHERE id(v) == 'player100' RETURN id(v2) AS destination;
+-------------+
| destination |
+-------------+
| "player101" |
+-------------+
| "player102" |
+-------------+
...

// Finds player 100's friends and the teams that they serve.
nebula> GO FROM "player100" OVER follow REVERSELY \
YIELD follow._dst AS id | \
GO FROM $-.id OVER serve \
WHERE $^.player.age > 20 \
YIELD $^.player.name AS FriendOf, $$.team.name AS Team;
+---------------------+-----------------+
| FriendOf            | Team            |
+---------------------+-----------------+
| "Tony Parker"       | "Spurs"         |
+---------------------+-----------------+
| "Tony Parker"       | "Hornets"       |
+---------------------+-----------------+
...

// This MATCH query shares the same semantics with the preceding GO query.
nebula> MATCH (v)<-[e:follow]- (v2)-[e2:serve]->(v3)  WHERE id(v) == 'player100' RETURN v2.name AS FriendOf, v3.name AS Team;
+---------------------+-----------------+
| FriendOf            | Team            |
+---------------------+-----------------+
| "Tony Parker"       | "Spurs"         |
+---------------------+-----------------+
| "Tony Parker"       | "Hornets"       |
+---------------------+-----------------+
...

nebula> GO FROM "player102" OVER follow BIDIRECT YIELD follow._dst AS both;
+-------------+
| both        |
+-------------+
| "player100" |
+-------------+
| "player101" |
+-------------+
...

// This MATCH query shares the same semantics with the preceding GO query.
nebula> MATCH (v) -[e:follow]-(v2) WHERE id(v)== "player102" RETURN id(v2) AS both;
+-------------+
| both        |
+-------------+
| "player101" |
+-------------+
| "player103" |
+-------------+
...

nebula> GO 1 TO 2 STEPS FROM "player100" OVER follow YIELD follow._dst AS destination;
+-------------+
| destination |
+-------------+
| "player101" |
+-------------+
| "player125" |
+-------------+
...

// This MATCH query shares the same semantics with the preceding GO query.
nebula> MATCH (v) -[e:follow*1..2]->(v2) WHERE id(v) == "player100" RETURN id(v2) AS destination;
+-------------+
| destination |
+-------------+
| "player100" |
+-------------+
| "player102" |
+-------------+

nebula> GO 2 STEPS FROM "player100" OVER follow \
YIELD follow._src AS src, follow._dst AS dst, $$.player.age AS age \
| GROUP BY $-.dst YIELD $-.dst AS dst, collect_set($-.src) AS src, collect($-.age) AS age
+-------------+----------------------------+----------+
| dst         | src                        | age      |
+-------------+----------------------------+----------+
| "player125" | ["player101"]              | [41]     |
+-------------+----------------------------+----------+
| "player100" | ["player125", "player101"] | [42, 42] |
+-------------+----------------------------+----------+
| "player102" | ["player101"]              | [33]     |
+-------------+----------------------------+----------+

nebula> $a = GO FROM "player100" OVER follow YIELD follow._src AS src, follow._dst AS dst; \
GO 2 STEPS FROM $a.dst OVER follow YIELD $a.src AS src, $a.dst, follow._src, follow._dst \
| ORDER BY $-.src | OFFSET 1 LIMIT 2;
+-------------+-------------+-------------+-------------+
| src         | $a.dst      | follow._src | follow._dst |
+-------------+-------------+-------------+-------------+
| "player100" | "player125" | "player100" | "player101" |
+-------------+-------------+-------------+-------------+
| "player100" | "player101" | "player100" | "player125" |
+-------------+-------------+-------------+-------------+

Last update: April 1, 2021