LOOKUP¶
The LOOKUP
statement traverses 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 topic applies to native nGQL only.
Precautions¶
- Correct use of indexes can speed up queries, but indexes can dramatically reduce the write performance. The performance reduction can be 90% or even more. DO NOT use indexes in production environments unless you are fully aware of their influences on your service.
-
If the specified property is not indexed when using the
LOOKUP
statement, Nebula Graph randomly selects one of the available indexes.For example, the tag
player
has two properties,name
andage
. Both the tagplayer
itself and the propertyage
have indexes, but the propertyname
has no indexes. When runningLOOKUP ON player WHERE player.age == 36 YIELD player.name;
, Nebula Graph randomly uses one of the indexes of the tagplayer
and the propertyage
.Legacy version compatibility
In the previous releases, if the specified property is not indexed when using the
LOOKUP
statement, Nebula Graph reports an error and does not use other indexes.
Prerequisites¶
Before using the LOOKUP
statement, make sure that at least one index is created. If there are already related vertices, edges, or properties before an index is created, the user must rebuild the index after creating the index to make it valid.
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>] ...];
WHERE <expression>
: filters data with specified conditions. BothAND
andOR
are supported between different expressions. For more information, see WHERE.
YIELD <return_list>
: 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 you
LOOKUP
a tag. - The source vertex ID, destination vertex ID, and rank of the edge are returned when
LOOKUP
an edge type.
- The Vertex ID is returned when you
Limitations of using WHERE
in LOOKUP
¶
The WHERE
clause in a LOOKUP
statement does not support the following operations:
$-
and$^
.- In relational expressions, operators are not supported to have field names on both sides, such as
tagName.prop1> tagName.prop2
. - Nested AliasProp expressions in operation expressions and function expressions are not supported.
- Range scan is not supported in the string-type index.
- The
XOR
andNOT
operations are not supported.
Retrieve Vertices¶
The following example returns vertices whose name
is Tony Parker
and the tag is 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 |
+-------------+-------------+---------+
| "player101" | "player102" | 0 |
+-------------+-------------+---------+
| "player133" | "player114" | 0 |
+-------------+-------------+---------+
| "player133" | "player144" | 0 |
+-------------+-------------+---------+
...
nebula> LOOKUP ON follow \
WHERE follow.degree == 90 \
YIELD follow.degree;
+-------------+-------------+---------+---------------+
| SrcVID | DstVID | Ranking | follow.degree |
+-------------+-------------+---------+---------------+
| "player101" | "player102" | 0 | 90 |
+-------------+-------------+---------+---------------+
| "player133" | "player114" | 0 | 90 |
+-------------+-------------+---------+---------------+
| "player133" | "player144" | 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 |
+-------------+------------------+----------------+--------------+
| "player105" | 2010 | 2018 | "Spurs" |
+-------------+------------------+----------------+--------------+
| "player105" | 2009 | 2010 | "Cavaliers" |
+-------------+------------------+----------------+--------------+
| "player105" | 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, 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); nebula> CREATE TAG INDEX player_index on player(); 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); The following statement retrieves the VID of all vertices with the tag `player`. It is similar to `MATCH (n:player) RETURN id(n) /*, n */`. nebula> LOOKUP ON player; +-------------+ | _vid | +-------------+ | "player100" | +-------------+ | "player101" | +-------------+
- 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); nebula> CREATE EDGE INDEX like_index on like(); nebula> REBUILD EDGE INDEX like_index; +------------+ | New Job Id | +------------+ | 88 | +------------+ nebula> INSERT EDGE like(likeness) \ VALUES "player100"->"player101":(95); The following statement retrieves all edges with the edge type `like`. It is similar to `MATCH (s)-[e:like]->(d) RETURN id(s), rank(e), id(d) /*, type(e) */`. nebula)> LOOKUP ON like; +-------------+----------+-------------+ | _src | _ranking | _dst | +-------------+----------+-------------+ | "player100" | 0 | "player101" | +-------------+----------+-------------+
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 |
+---------------+
nebula> LOOKUP ON like | \
YIELD COUNT(*) AS Like_Number;
+-------------+
| Like_Number |
+-------------+
| 1 |
+-------------+
Note
You can also use show-stats
to count the numbers of vertices or edges.