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 can be greatly reduced. 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, NebulaGraph randomly selects one of the available indexes.For example, the tag
player
has two properties,name
andage
. Both the tagplayer
itself and the propertyname
have indexes, but the propertyage
has no indexes. When runningLOOKUP ON player WHERE player.age == 36 YIELD player.name;
, NebulaGraph randomly uses one of the indexes of the tagplayer
and the propertyname
.Legacy version compatibility
Before the release 2.5.0, if the specified property is not indexed when using the
LOOKUP
statement, NebulaGraph 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 [DISTINCT] <return_list> [AS <alias>];
<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
: Define the output to be returned. For details, seeYIELD
.
DISTINCT
: Aggregate the output results and return the de-duplicated result set.
AS
: Set an alias.
Limitations of using WHERE
in LOOKUP
¶
The WHERE
clause in a LOOKUP
statement does not support the following operations:
$-
and$^
.- Filter
rank()
. - 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.
- The
XOR
operation is not supported. - String operations other than
STARTS WITH
are not supported. - Graph patterns.
Retrieve vertices¶
The following example returns vertices whose name
is Tony Parker
and the tag is player
.
nebula> CREATE TAG INDEX IF NOT EXISTS 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" \
YIELD id(vertex);
+---------------+
| id(VERTEX) |
+---------------+
| "player101" |
+---------------+
nebula> LOOKUP ON player \
WHERE player.name == "Tony Parker" \
YIELD properties(vertex).name AS name, properties(vertex).age AS age;
+---------------+-----+
| name | age |
+---------------+-----+
| "Tony Parker" | 36 |
+---------------+-----+
nebula> LOOKUP ON player \
WHERE player.age > 45 \
YIELD id(vertex);
+-------------+
| id(VERTEX) |
+-------------+
| "player144" |
| "player140" |
+-------------+
nebula> LOOKUP ON player \
WHERE player.name STARTS WITH "B" \
AND player.age IN [22,30] \
YIELD properties(vertex).name, properties(vertex).age;
+-------------------------+------------------------+
| properties(VERTEX).name | properties(VERTEX).age |
+-------------------------+------------------------+
| "Ben Simmons" | 22 |
| "Blake Griffin" | 30 |
+-------------------------+------------------------+
nebula> LOOKUP ON player \
WHERE player.name == "Kobe Bryant"\
YIELD id(vertex) AS VertexID, properties(vertex).name AS name |\
GO FROM $-.VertexID OVER serve \
YIELD $-.name, properties(edge).start_year, properties(edge).end_year, properties($$).name;
+---------------+-----------------------------+---------------------------+---------------------+
| $-.name | properties(EDGE).start_year | properties(EDGE).end_year | properties($$).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 IF NOT EXISTS index_follow ON follow(degree);
nebula> REBUILD EDGE INDEX index_follow;
+------------+
| New Job Id |
+------------+
| 62 |
+------------+
nebula> LOOKUP ON follow \
WHERE follow.degree == 90 YIELD edge AS e;
+----------------------------------------------------+
| e |
+----------------------------------------------------+
| [:follow "player109"->"player125" @0 {degree: 90}] |
| [:follow "player118"->"player120" @0 {degree: 90}] |
| [:follow "player118"->"player131" @0 {degree: 90}] |
...
nebula> LOOKUP ON follow \
WHERE follow.degree == 90 \
YIELD properties(edge).degree;
+-------------+-------------+---------+-------------------------+
| SrcVID | DstVID | Ranking | properties(EDGE).degree |
+-------------+-------------+---------+-------------------------+
| "player150" | "player143" | 0 | 90 |
| "player150" | "player137" | 0 | 90 |
| "player148" | "player136" | 0 | 90 |
...
nebula> LOOKUP ON follow \
WHERE follow.degree == 60 \
YIELD dst(edge) AS DstVID, properties(edge).degree AS Degree |\
GO FROM $-.DstVID OVER serve \
YIELD $-.DstVID, properties(edge).start_year, properties(edge).end_year, properties($$).name;
+-------------+-----------------------------+---------------------------+---------------------+
| $-.DstVID | properties(EDGE).start_year | properties(EDGE).end_year | properties($$).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 IF NOT EXISTS player(name string,age int); nebula> CREATE TAG INDEX IF NOT EXISTS 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 YIELD id(vertex); +-------------+ | id(VERTEX) | +-------------+ | "player100" | | "player101" | ...
- The following example shows how to retrieve the source Vertex IDs, destination vertex IDs, and ranks of all edges of the
follow
edge type.nebula> CREATE EDGE IF NOT EXISTS follow(degree int); nebula> CREATE EDGE INDEX IF NOT EXISTS follow_index on follow(); nebula> REBUILD EDGE INDEX follow_index; +------------+ | New Job Id | +------------+ | 88 | +------------+ nebula> INSERT EDGE follow(degree) \ VALUES "player100"->"player101":(95); The following statement retrieves all edges with the edge type `follow`. It is similar to `MATCH (s)-[e:follow]->(d) RETURN id(s), rank(e), id(d) /*, type(e) */`. nebula)> LOOKUP ON follow YIELD edge AS e; +-----------------------------------------------------+ | e | +-----------------------------------------------------+ | [:follow "player105"->"player100" @0 {degree: 70}] | | [:follow "player105"->"player116" @0 {degree: 80}] | | [:follow "player109"->"player100" @0 {degree: 80}] | ...
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 follow
edge type.
nebula> LOOKUP ON player YIELD id(vertex)|\
YIELD COUNT(*) AS Player_Number;
+---------------+
| Player_Number |
+---------------+
| 51 |
+---------------+
nebula> LOOKUP ON follow YIELD edge AS e| \
YIELD COUNT(*) AS Follow_Number;
+---------------+
| Follow_Number |
+---------------+
| 81 |
+---------------+
Note
You can also use SHOW STATS
to count the numbers of vertices or edges.