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 name have indexes, but the property age 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 name.

    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> [AS <alias>]];

<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: Define the output to be returned.

    • When you LOOKUP a Tag, the defined properties and VertexID are returned. If there is no YIELD clause, VertexID is returned.
    • When you LOOKUP an Edge type, the defined properties, SrcVertexID, DstVertexID, and rank are returned. If there is no YIELD clause, SrcVertexID, DstVertexID, and rank are returned.
  • AS: Set an alias.

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.
  • 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    |
+-------------+
| "player101" |
+-------------+

nebula> LOOKUP ON player \
        WHERE player.name == "Tony Parker" \
        YIELD properties(vertex).name AS name, properties(vertex).age AS age;
+-------------+---------------+-----+
| VertexID    | name          | age |
+-------------+---------------+-----+
| "player101" | "Tony Parker" | 36  |
+-------------+---------------+-----+

nebula> LOOKUP ON player \
        WHERE player.age  > 45;
+-------------+
| VertexID    |
+-------------+
| "player140" |
| "player144" |
+-------------+

nebula> LOOKUP ON player \
        WHERE player.name STARTS WITH "B" \
        AND player.age IN [22,30] \
        YIELD properties(vertex).name, properties(vertex).age;
+-------------+-------------------------+------------------------+
| VertexID    | properties(VERTEX).name | properties(VERTEX).age |
+-------------+-------------------------+------------------------+
| "player134" | "Blake Griffin"         | 30                     |
| "player149" | "Ben Simmons"           | 22                     |
+-------------+-------------------------+------------------------+

nebula> LOOKUP ON player \
        WHERE player.name == "Kobe Bryant"\
        YIELD 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 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 |
+-------------+-------------+---------+
| "player150" | "player143" | 0       |
| "player150" | "player137" | 0       |
| "player148" | "player136" | 0       |
...

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 properties(edge).degree AS Degree |\
        GO FROM $-.DstVID OVER serve \
        YIELD $-.DstVID, properties(edge).start_year, properties(edge).end_year, properties($$).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;
+-------------+
|  VertexID   |
+-------------+
| "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 follow(degree int);

nebula> CREATE EDGE INDEX 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;
+-------------+-------------+---------+
| SrcVID      | DstVID      | Ranking |
+-------------+-------------+---------+
| "player100" | "player101" | 0       |
+-------------+-------------+---------+

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 COUNT(*) AS Player_Number;
+---------------+
| Player_Number |
+---------------+
| 51            |
+---------------+

nebula> LOOKUP ON follow | \
        YIELD COUNT(*) AS Follow_Number;
+---------------+
| Follow_Number |
+---------------+
| 81            |
+---------------+

Note

You can also use SHOW STATS to count the numbers of vertices or edges.

Last update: November 2, 2021
Back to top