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. Both AND and OR 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 no YIELD 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.

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 and XOR 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)

Last update: May 20, 2021