Skip to content

LOOKUP

OpenCypher compatibility

This page applies to nGQL extensions only.

Syntax

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.

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.
  • Range scan is not supported in the string-type index.
  • 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)

FAQ

Error code 411

[ERROR (-8)]: Unknown error(411):

Error code 411 shows there is no valid index for the current WHERE filter. Nebula Graph uses the left matching mode to select indexes. That is, columns in the WHERE filter must be in the first N columns of the index. For example:

nebula> CREATE TAG INDEX example_index ON TAG t(p1, p2, p3);  -- Create an index for the first 3 properties of tag t
nebula> LOOKUP ON t WHERE p2 == 1 and p3 == 1; -- Not supported
nebula> LOOKUP ON t WHERE p1 == 1;  -- Supported
nebula> LOOKUP ON t WHERE p1 == 1 and p2 == 1;  -- Supported
nebula> LOOKUP ON t WHERE p1 == 1 and p2 == 1 and p3 == 1;  -- Supported

No valid index found

No valid index found

If your query filter contains a string type field, Nebula Graph selects the index that matches all the fields. For example:

nebula> CREATE TAG t1 (c1 string, c2 int);
nebula> CREATE TAG INDEX i1 ON t1 (c1, c2);
nebula> LOOKUP ON t1 WHERE t1.c1 == "a"; -- Index i1 is invalid
nebula> LOOKUP ON t1 WHERE t1.c1 == "a" and t1.c2 == 1;  -- Index i1 is valid
Last update: March 26, 2021
Back to top