Skip to content

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 and age. Both the tag player itself and the property age have indexes, but the property name has no indexes. When running LOOKUP ON player WHERE player.age == 36 YIELD player.name;, Nebula Graph randomly uses one of the indexes of the tag player and the property age.

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

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 and NOT 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.

Last update: September 9, 2021
Back to top