FETCH¶

The FETCH statement retrieves the properties of the specified vertices or edges.

OpenCypher Compatibility¶

This topic applies to nGQL extensions only.

Fetch vertex properties¶

Syntax¶

FETCH PROP ON {<tag_name>[, tag_name ...] | *} 
<vid> [, vid ...] 
[YIELD <output>]

The descriptions of the fields are as follows.

Field	Description
`tag_name`	The name of the tag.
`*`	Represents all the tags in the current graph space.
`vid`	The vertex ID.
`output`	Specifies the information to be returned. For more information, see `YIELD`. If there is no `YIELD` clause, `FETCH` returns all the matched information.

Fetch vertex properties by one tag¶

Specify a tag in the FETCH statement to fetch the vertex properties by that tag.

nebula> FETCH PROP ON player "player100";
+----------------------------------------------------+
| vertices_                                          |
+----------------------------------------------------+
| ("player100" :player{age: 42, name: "Tim Duncan"}) |
+----------------------------------------------------+
Got 1 rows (time spent 913/1629 us)

Fetch specific properties of a vertex¶

Use a YIELD clause to specify the properties to be returned.

nebula> FETCH PROP ON player "player100" \
        YIELD player.name;
+-------------+--------------+
| VertexID    | player.name  |
+-------------+--------------+
| "player100" | "Tim Duncan" |
+-------------+--------------+
Got 1 rows (time spent 2933/5931 us)

Fetch properties of multiple vertices¶

Specify multiple VIDs (vertex IDs) to fetch properties of multiple vertices. Separate the VIDs with commas.

nebula> FETCH PROP ON player "player101", "player102", "player103";
+-----------------------------------------------------------+
| vertices_                                                 |
+-----------------------------------------------------------+
| ("player101" :player{age: 36, name: "Tony Parker"})       |
+-----------------------------------------------------------+
| ("player102" :player{age: 33, name: "LaMarcus Aldridge"}) |
+-----------------------------------------------------------+
| ("player103" :player{age: 32, name: "Rudy Gay"})          |
+-----------------------------------------------------------+
Got 3 rows (time spent 1786/3135 us)

Fetch vertex properties by multiple tags¶

Specify multiple tags in the FETCH statement to fetch the vertex properties by the tags. Separate the tags with commas.

// Create a new tag t1.
nebula> CREATE TAG t1(a string, b int);
Execution succeeded (time spent 4153/5296 us)

// Attach t1 to vertex "player100".
nebula> INSERT VERTEX t1(a, b) VALUE "player100":("Hello", 100);
Execution succeeded (time spent 1703/2321 us)

// Fetch the properties of vertex "player100" by the tags player and t1.
nebula> FETCH PROP ON player, t1 "player100";
+----------------------------------------------------------------------------+
| vertices_                                                                  |
+----------------------------------------------------------------------------+
| ("player100" :t1{a: "Hello", b: 100} :player{age: 42, name: "Tim Duncan"}) |
+----------------------------------------------------------------------------+
Got 1 rows (time spent 1788/2560 us)

You can combine multiple tags with multiple VIDs in a FETCH statement.

nebula> FETCH PROP ON player, t1 "player100", "player103";
+----------------------------------------------------------------------------+
| vertices_                                                                  |
+----------------------------------------------------------------------------+
| ("player100" :t1{a: "Hello", b: 100} :player{age: 42, name: "Tim Duncan"}) |
+----------------------------------------------------------------------------+
| ("player103" :player{age: 32, name: "Rudy Gay"})                           |
+----------------------------------------------------------------------------+
Got 2 rows (time spent 2971/3748 us)

Fetch vertex properties by all tags¶

Set an asterisk symbol (*) to fetch properties by all tags in the current graph space.

nebula> FETCH PROP ON * "player100", "player106", "team200";
+----------------------------------------------------------------------------+
| vertices_                                                                  |
+----------------------------------------------------------------------------+
| ("player106" :player{age: 25, name: "Kyle Anderson"})                      |
+----------------------------------------------------------------------------+
| ("team200" :team{name: "Warriors"})                                        |
+----------------------------------------------------------------------------+
| ("player100" :t1{a: "Hello", b: 100} :player{age: 42, name: "Tim Duncan"}) |
+----------------------------------------------------------------------------+
Got 3 rows (time spent 2620/4863 us)

Fetch edge properties¶

Syntax¶

FETCH PROP ON <edge_type> <src_vid> -> <dst_vid>[@<rank>] [, <src_vid> -> <dst_vid> ...]
[YIELD <output>]

The descriptions of the fields are as follows.

Field	Description
`edge_type`	The name of the edge type.
`src_vid`	The VID of the source vertex. It specifies the start of an edge.
`dst_vid`	The VID of the destination vertex. It specifies the end of an edge.
`rank`	The rank of the edge. It is optional and defaults to 0. It distinguishes an edge from other edges with the same edge type, source vertex, and destination vertex.
`output`	Specifies the information to be returned. For more information, see `YIELD`. If there is no `YIELD` clause, `FETCH` returns all the matched information.

Fetch all properties of an edge¶

The following statement fetches all the properties of the serve edge that connects vertex "player100" and vertex "team204".

nebula> FETCH PROP ON serve "player100" -> "team204";
+-----------------------------------------------------------------------+
| edges_                                                                |
+-----------------------------------------------------------------------+
| [:serve "player100"->"team204" @0 {end_year: 2016, start_year: 1997}] |
+-----------------------------------------------------------------------+
Got 1 rows (time spent 1048/1632 us)

Fetch specific properties of an edge¶

Use a YIELD clause to fetch specific properties of an edge.

nebula> FETCH PROP ON serve "player100" -> "team204" YIELD serve.start_year;
+-------------+------------+-------------+------------------+
| serve._src  | serve._dst | serve._rank | serve.start_year |
+-------------+------------+-------------+------------------+
| "player100" | "team204"  | 0           | 1997             |
+-------------+------------+-------------+------------------+
Got 1 rows (time spent 1834/2863 us)

Fetch properties of multiple edges¶

Specify multiple edge patterns (<src_vid> -> <dst_vid>[@<rank>]) to fetch properties of multiple edges. Separate the edge patterns with commas.

nebula> FETCH PROP ON serve "player100" -> "team204", "player133" -> "team202";
+-----------------------------------------------------------------------+
| edges_                                                                |
+-----------------------------------------------------------------------+
| [:serve "player100"->"team204" @0 {end_year: 2016, start_year: 1997}] |
+-----------------------------------------------------------------------+
| [:serve "player133"->"team202" @0 {end_year: 2011, start_year: 2002}] |
+-----------------------------------------------------------------------+
Got 2 rows (time spent 1466/2441 us)

Fetch properties based on edge rank¶

If there are multiple edges that have different ranks but the same edge type, source vertex, destination vertex, specify the rank to fetch the properties on the correct edge.

// Insert edges with different ranks and property values.
nebula> insert edge serve(start_year,end_year) \
        values "player100"->"team204"@1:(1998, 2017);
Execution succeeded (time spent 1679/3192 us)

nebula> insert edge serve(start_year,end_year) \
        values "player100"->"team204"@2:(1990, 2018);
Execution succeeded (time spent 1091/1608 us)

// By default, FETCH returns the edge with rank 0.
nebula> FETCH PROP ON serve "player100" -> "team204";
+-----------------------------------------------------------------------+
| edges_                                                                |
+-----------------------------------------------------------------------+
| [:serve "player100"->"team204" @0 {end_year: 2016, start_year: 1997}] |
+-----------------------------------------------------------------------+
Got 1 rows (time spent 2031/2739 us)

// To fetch on an edge with rank other than 0, set its rank in FETCH.
nebula> FETCH PROP ON serve "player100" -> "team204"@1;
+-----------------------------------------------------------------------+
| edges_                                                                |
+-----------------------------------------------------------------------+
| [:serve "player100"->"team204" @1 {end_year: 2017, start_year: 1998}] |
+-----------------------------------------------------------------------+
Got 1 rows (time spent 1049/1711 us)

Use FETCH in composite queries¶

A common way to use FETCH is to combine it with nGQL extensions such as GO. The following statement returns the degree values of outgoing follow edges that start from vertex "player101".

nebula> GO FROM "player101" OVER follow \
        YIELD follow._src AS s, follow._dst AS d | \
        FETCH PROP ON follow $-.s -> $-.d \
        YIELD follow.degree;
+-------------+-------------+--------------+---------------+
| follow._src | follow._dst | follow._rank | follow.degree |
+-------------+-------------+--------------+---------------+
| "player101" | "player100" | 0            | 95            |
+-------------+-------------+--------------+---------------+
| "player101" | "player102" | 0            | 90            |
+-------------+-------------+--------------+---------------+
| "player101" | "player125" | 0            | 95            |
+-------------+-------------+--------------+---------------+
Got 3 rows (time spent 3047/3880 us)

Or you can use user-defined variables to construct similar queries.

nebula> $var = GO FROM "player101" OVER follow \
        YIELD follow._src AS s, follow._dst AS d; \
        FETCH PROP ON follow $var.s -> $var.d \
        YIELD follow.degree;
+-------------+-------------+--------------+---------------+
| follow._src | follow._dst | follow._rank | follow.degree |
+-------------+-------------+--------------+---------------+
| "player101" | "player100" | 0            | 95            |
+-------------+-------------+--------------+---------------+
| "player101" | "player102" | 0            | 90            |
+-------------+-------------+--------------+---------------+
| "player101" | "player125" | 0            | 95            |
+-------------+-------------+--------------+---------------+
Got 3 rows (time spent 1891/2509 us)

For more information about composite queries, see Composite queries (clause structure).

Last update: March 29, 2021