FETCH¶
The FETCH statement retrieves the properties of the specified vertices or edges.
OpenCypher Compatibility¶
This topic applies to native nGQL only.
Fetch vertex properties¶
Syntax¶
FETCH PROP ON {<tag_name>[, tag_name ...] | *}
<vid> [, vid ...]
[YIELD <return_list> [AS <alias>]];
| Parameter | Description |
|---|---|
tag_name |
The name of the tag. |
* |
Represents all the tags in the current graph space. |
vid |
The vertex ID. |
YIELD |
Define the output to be returned. The defined properties and VertexID are returned. For details, see YIELD. If there is no YIELD clause, vertices_ is returned by default, which contains all the information about the vertex. |
AS |
Set an alias. |
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"}) |
+----------------------------------------------------+
Fetch specific properties of a vertex¶
Use a YIELD clause to specify the properties to be returned.
nebula> FETCH PROP ON player "player100" \
YIELD properties(vertex).name AS name;
+-------------+--------------+
| VertexID | name |
+-------------+--------------+
| "player100" | "Tim Duncan" |
+-------------+--------------+
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"}) |
+-----------------------------------------------------------+
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.
# The following example creates a new tag t1.
nebula> CREATE TAG IF NOT EXISTS t1(a string, b int);
# The following example attaches t1 to the vertex "player100".
nebula> INSERT VERTEX t1(a, b) VALUE "player100":("Hello", 100);
# The following example fetches 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"}) |
+----------------------------------------------------------------------------+
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"}) |
+----------------------------------------------------------------------------+
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"}) |
+----------------------------------------------------------------------------+
Fetch edge properties¶
Syntax¶
FETCH PROP ON <edge_type> <src_vid> -> <dst_vid>[@<rank>] [, <src_vid> -> <dst_vid> ...]
[YIELD <output>]
| Parameter | 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, destination vertex, and rank. |
YIELD |
Define the output to be returned. The defined properties, SrcVertexID, DstVertexID, and rank are returned. For details, see YIELD. If there is no YIELD clause, edges_ is returned by default, which contains all the information about the edge. |
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}] |
+-----------------------------------------------------------------------+
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 properties(edge).start_year;
+-------------+------------+-------------+-----------------------------+
| serve._src | serve._dst | serve._rank | properties(EDGE).start_year |
+-------------+------------+-------------+-----------------------------+
| "player100" | "team204" | 0 | 1997 |
+-------------+------------+-------------+-----------------------------+
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}] |
+-----------------------------------------------------------------------+
Fetch properties based on edge rank¶
If there are multiple edges with the same edge type, source vertex, and destination vertex, you can specify the rank to fetch the properties on the correct edge.
# The following example inserts edges with different ranks and property values.
nebula> insert edge serve(start_year,end_year) \
values "player100"->"team204"@1:(1998, 2017);
nebula> insert edge serve(start_year,end_year) \
values "player100"->"team204"@2:(1990, 2018);
# By default, the FETCH statement returns the edge whose rank is 0.
nebula> FETCH PROP ON serve "player100" -> "team204";
+-----------------------------------------------------------------------+
| edges_ |
+-----------------------------------------------------------------------+
| [:serve "player100"->"team204" @0 {end_year: 2016, start_year: 1997}] |
+-----------------------------------------------------------------------+
# To fetch on an edge whose rank is not 0, set its rank in the FETCH statement.
nebula> FETCH PROP ON serve "player100" -> "team204"@1;
+-----------------------------------------------------------------------+
| edges_ |
+-----------------------------------------------------------------------+
| [:serve "player100"->"team204" @1 {end_year: 2017, start_year: 1998}] |
+-----------------------------------------------------------------------+
Use FETCH in composite queries¶
A common way to use FETCH is to combine it with native nGQL such as GO.
The following statement returns the degree values of the follow edges that start from vertex "player101".
nebula> GO FROM "player101" OVER follow \
YIELD src(edge) AS s, dst(edge) AS d \
| FETCH PROP ON follow $-.s -> $-.d \
YIELD properties(edge).degree;
+-------------+-------------+--------------+-------------------------+
| follow._src | follow._dst | follow._rank | properties(EDGE).degree |
+-------------+-------------+--------------+-------------------------+
| "player101" | "player100" | 0 | 95 |
| "player101" | "player102" | 0 | 90 |
| "player101" | "player125" | 0 | 95 |
+-------------+-------------+--------------+-------------------------+
Or you can use user-defined variables to construct similar queries.
nebula> $var = GO FROM "player101" OVER follow \
YIELD src(edge) AS s, dst(edge) AS d; \
FETCH PROP ON follow $var.s -> $var.d \
YIELD properties(edge).degree;
+-------------+-------------+--------------+-------------------------+
| follow._src | follow._dst | follow._rank | properties(EDGE).degree |
+-------------+-------------+--------------+-------------------------+
| "player101" | "player100" | 0 | 95 |
| "player101" | "player102" | 0 | 90 |
| "player101" | "player125" | 0 | 95 |
+-------------+-------------+--------------+-------------------------+
For more information about composite queries, see Composite queries (clause structure).
Last update: November 10, 2021