LOOKUP¶
The LOOKUP
statement retrieves data based on indexes.
You can use LOOKUP
for the following purposes:
- Search for the specific data based on conditions defined by the
WHERE
clause. - List vertices with a tag: retrieve the VID of all vertices with a tag.
- List edges with an edge type: retrieve the source Vertex IDs, destination vertex IDs, and ranks of all edges with an edge type.
- Count the number of vertices or edges with a tag or an edge type.
OpenCypher compatibility¶
This page applies to nGQL extensions only.
Prerequisites¶
Before using the LOOKUP
statement, make sure that relative indexes are created. For how to create indexes, see CREATE INDEX.
Syntax¶
LOOKUP ON {<vertex_tag> | <edge_type>} [WHERE <expression> [AND <expression> ...]] [YIELD <return_list>]
<return_list>
<prop_name> [AS <col_alias>] [, <prop_name> [AS <prop_alias>] ...]
- The
WHERE
clause filters data with the specified conditions. BothAND
andOR
are supported between different expressions. For more information, see WHERE. - The
YIELD
clause specifies the results to be returned and the format of the results. - If there is a
WHERE
clause but noYIELD
clause:- The Vertex ID is returned when
LOOKUP
a tag. - The source vertex ID, destination vertex ID, and rank of the edge is returned when
LOOKUP
an edge type.
- The Vertex ID is returned when
Limitations of using WHERE
in LOOKUP
¶
The WHERE
clause in a LOOKUP
statement does not support the following operations:
$-
and$^
.- In relational expressions, expressions with field names on both sides of the operator are not supported, such as
tagName.prop1> tagName.prop2
. - Nested AliasProp expressions in operation expressions and function expressions are not supported.
- Expressions that match string-type index, such as
starts with
ends with
contains
. - The
OR
andXOR
operations are not supported.
Retrieve Vertices¶
The following example returns vertices whose name is Tony Parker
and tagged with player.
nebula> CREATE TAG INDEX index_player ON player(name(30), age);
nebula> REBUILD TAG INDEX index_player;
+------------+
| New Job Id |
+------------+
| 15 |
+------------+
nebula> LOOKUP ON player WHERE player.name == "Tony Parker";
============
| VertexID |
============
| 101 |
------------
nebula> LOOKUP ON player WHERE player.name == "Tony Parker" \
YIELD player.name, player.age;
=======================================
| VertexID | player.name | player.age |
=======================================
| 101 | Tony Parker | 36 |
---------------------------------------
nebula> LOOKUP ON player WHERE player.name == "Kobe Bryant" YIELD player.name AS name \
| GO FROM $-.VertexID OVER serve \
YIELD $-.name, serve.start_year, serve.end_year, $$.team.name;
==================================================================
| $-.name | serve.start_year | serve.end_year | $$.team.name |
==================================================================
| Kobe Bryant | 1996 | 2016 | Lakers |
------------------------------------------------------------------
Retrieve Edges¶
The following example returns edges whose degree
is 90 and the edge type is follow
.
nebula> CREATE EDGE INDEX index_follow ON follow(degree);
nebula> REBUILD EDGE INDEX index_follow;
+------------+
| New Job Id |
+------------+
| 62 |
+------------+
nebula> LOOKUP ON follow WHERE follow.degree == 90;
=============================
| SrcVID | DstVID | Ranking |
=============================
| 100 | 106 | 0 |
-----------------------------
nebula> LOOKUP ON follow WHERE follow.degree == 90 YIELD follow.degree;
=============================================
| SrcVID | DstVID | Ranking | follow.degree |
=============================================
| 100 | 106 | 0 | 90 |
---------------------------------------------
nebula> LOOKUP ON follow WHERE follow.degree == 60 YIELD follow.degree AS Degree \
| GO FROM $-.DstVID OVER serve \
YIELD $-.DstVID, serve.start_year, serve.end_year, $$.team.name;
================================================================
| $-.DstVID | serve.start_year | serve.end_year | $$.team.name |
================================================================
| 105 | 2010 | 2018 | Spurs |
----------------------------------------------------------------
| 105 | 2009 | 2010 | Cavaliers |
----------------------------------------------------------------
| 105 | 2018 | 2019 | Raptors |
----------------------------------------------------------------
List vertices or edges with a tag or an edge type¶
To list vertices or edges with a tag or an edge type, at least one index must exist on the tag or the edge type, or its property.
For example, if there is a player
tag with a name
property and an age
property, to retrieve the VID of all vertices tagged with player
, there has to be an index on the player
tag itself, the name
property, or the age
property.
The following example shows how to retrieve the VID of all vertices tagged with player
.
nebula> CREATE TAG player(name string,age int);
Execution succeeded (time spent 3235/3865 us)
nebula> CREATE TAG INDEX player_index on player();
Execution succeeded (time spent 3486/4124 us)
nebula> REBUILD TAG INDEX player_index;
+------------+
| New Job Id |
+------------+
| 66 |
+------------+
nebula> INSERT VERTEX player(name,age) VALUES "player100":("Tim Duncan", 42), "player101":("Tony Parker", 36);
Execution succeeded (time spent 1695/2268 us)
nebula> LOOKUP ON player;
+-------------+
| _vid |
+-------------+
| "player100" |
+-------------+
| "player101" |
+-------------+
Got 2 rows (time spent 1514/2070 us)
The following example shows how to retrieve the source Vertex IDs, destination vertex IDs, and ranks of all edges of the like
edge type.
nebula)> CREATE EDGE like(likeness int);
Execution succeeded (time spent 3710/4483 us)
nebula)> CREATE EDGE INDEX like_index on like();
Execution succeeded (time spent 3422/4026 us)
nebula> REBUILD EDGE INDEX like_index;
+------------+
| New Job Id |
+------------+
| 88 |
+------------+
nebula)> INSERT EDGE like(likeness) values "player100"->"player101":(95);
Execution succeeded (time spent 1638/2351 us)
nebula)> LOOKUP ON like;
+-------------+----------+-------------+
| _src | _ranking | _dst |
+-------------+----------+-------------+
| "player100" | 0 | "player101" |
+-------------+----------+-------------+
Got 1 rows (time spent 1163/1748 us)
Count the numbers of vertices or edges¶
The following example shows how to count the number of vertices tagged with player
and edges of the like
edge type.
nebula> LOOKUP ON player | YIELD COUNT(*) AS Player_Number;
+---------------+
| Player_Number |
+---------------+
| 2 |
+---------------+
Got 1 rows (time spent 1158/1864 us)
nebula> LOOKUP ON like | YIELD COUNT(*) AS Like_Number;
+-------------+
| Like_Number |
+-------------+
| 1 |
+-------------+
Got 1 rows (time spent 1190/1970 us)