Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Lookup #575

Merged
merged 6 commits into from
Aug 4, 2021
Merged

Lookup #575

Changes from 2 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
0a59648
lookup
izhuxiaoqing Jul 29, 2021
7da3ea7
Update 5.lookup.md
izhuxiaoqing Jul 29, 2021
4d85533
Update 5.lookup.md
izhuxiaoqing Jul 29, 2021
6f5dd89
Update 5.lookup.md
izhuxiaoqing Jul 29, 2021
91a5cb7
Update 5.lookup.md
izhuxiaoqing Aug 2, 2021
0502a4f
Address Foesa's comment
izhuxiaoqing Aug 3, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
213 changes: 123 additions & 90 deletions docs-2.0/3.ngql-guide/7.general-query-statements/5.lookup.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,50 +1,57 @@
# LOOKUP

The `LOOKUP` statement retrieves data based on indexes.

You can use `LOOKUP` for the following purposes:
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.

- 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 native nGQL only.
This topic applies to native nGQL only.

## Prerequisites

Before using the `LOOKUP` statement, make sure that relative indexes are created. For how to create indexes, see [CREATE INDEX](../14.native-index-statements/1.create-native-index.md).
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 native index](../14.native-index-statements/4.rebuild-native-index.md) after creating the index to make it valid.

!!! caution

Indexes will weaken write performance for (90% or even more). Do not use indexes in a production environment. Please do not use indexes in a production environment at will, unless you know the impact of using indexes on the business.

izhuxiaoqing marked this conversation as resolved.
Show resolved Hide resolved
## Syntax

```ngql
LOOKUP ON {<vertex_tag> | <edge_type>} [WHERE <expression> [AND <expression> ...]] [YIELD <return_list>]
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>] ...]
<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](../8.clauses-and-options/where.md).
- The `YIELD` clause specifies the results to be returned and the format of the results.
- `WHERE <expression>`: filters data with specified conditions. Both `AND` and `OR` are supported between different expressions. For more information, see [WHERE](../8.clauses-and-options/where.md).

- `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 `LOOKUP` a tag.
- The source vertex ID, destination vertex ID, and rank of the edge is returned when `LOOKUP` an edge type.
- 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, expressions with field names on both sides of the operator are not supported, such as `tagName.prop1> tagName.prop2`.
- 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.
izhuxiaoqing marked this conversation as resolved.
Show resolved Hide resolved
- The `OR` and `XOR` operations are not supported.
- The `XOR` and `NOT` operations are not supported.

## Retrieve Vertices

The following example returns vertices whose name is `Tony Parker` and tagged with _player_.
The following example returns vertices whose `name` is `Tony Parker` and the tag is `player`.

```ngql
nebula> CREATE TAG INDEX index_player ON player(name(30), age);
Expand All @@ -63,13 +70,30 @@ nebula> LOOKUP ON player WHERE player.name == "Tony Parker";
| 101 |
------------

nebula> LOOKUP ON player WHERE player.name == "Tony Parker" \
//Use regex to retrieve vertices.
izhuxiaoqing marked this conversation as resolved.
Show resolved Hide resolved
nebula> LOOKUP ON player WHERE player.name =~ "^.{15,20}$" \
YIELD player.name, player.age;
+-------------+----------------------+------------+
| VertexID | player.name | player.age |
+-------------+----------------------+------------+
| "player147" | "Amar'e Stoudemire" | 36 |
+-------------+----------------------+------------+
| "player144" | "Shaquille O'Neal" | 47 |
+-------------+----------------------+------------+
...

nebula> LOOKUP ON player WHERE player.name CONTAINS toLower("L") \
YIELD player.name, player.age;
=======================================
| VertexID | player.name | player.age |
=======================================
| 101 | Tony Parker | 36 |
---------------------------------------
+-------------+---------------------+------------+
| VertexID | player.name | player.age |
+-------------+---------------------+------------+
| "player145" | "JaVale McGee" | 31 |
+-------------+---------------------+------------+
| "player144" | "Shaquille O'Neal" | 47 |
+-------------+---------------------+------------+
| "player102" | "LaMarcus Aldridge" | 33 |
+-------------+---------------------+------------+
...

nebula> LOOKUP ON player WHERE player.name == "Kobe Bryant" YIELD player.name AS name \
| GO FROM $-.VertexID OVER serve \
Expand All @@ -83,7 +107,7 @@ nebula> LOOKUP ON player WHERE player.name == "Kobe Bryant" YIELD player.name AS

## Retrieve Edges

The following example returns edges whose `degree` is 90 and the edge type is `follow`.
The following example returns edges whose `degree` is `90` and the edge type is `follow`.

```ngql
nebula> CREATE EDGE INDEX index_follow ON follow(degree);
Expand All @@ -96,96 +120,102 @@ nebula> REBUILD EDGE INDEX index_follow;
+------------+

nebula> LOOKUP ON follow WHERE follow.degree == 90;
=============================
| SrcVID | DstVID | Ranking |
=============================
| 100 | 106 | 0 |
-----------------------------
+-------------+-------------+---------+
| 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 |
=============================================
| 100 | 106 | 0 | 90 |
---------------------------------------------
+-------------+-------------+---------+---------------+
| 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 |
================================================================
| 105 | 2010 | 2018 | Spurs |
----------------------------------------------------------------
| 105 | 2009 | 2010 | Cavaliers |
----------------------------------------------------------------
| 105 | 2018 | 2019 | Raptors |
----------------------------------------------------------------
+-------------+------------------+----------------+--------------+
| $-.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 or the edge type, or its property.
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`.
- The following example shows how to retrieve the VID of all vertices tagged with `player`.

```ngql
nebula> CREATE TAG player(name string,age int);
Execution succeeded (time spent 3235/3865 us)
```ngql
nebula> CREATE TAG player(name string,age int);

nebula> CREATE TAG INDEX player_index on player();
Execution succeeded (time spent 3486/4124 us)
nebula> CREATE TAG INDEX player_index on player();

nebula> REBUILD TAG INDEX player_index;
+------------+
| New Job Id |
+------------+
| 66 |
+------------+
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> 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 of player. It is similar to MATCH (n:player) RETURN id(n) /*, n */.

nebula> LOOKUP ON player;
+-------------+
| _vid |
+-------------+
| "player100" |
+-------------+
| "player101" |
+-------------+
```

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.

The following example shows how to retrieve the source Vertex IDs, destination vertex IDs, and ranks of all edges of the `like` edge type.
```ngql
nebula> CREATE EDGE like(likeness int);

```ngql
nebula)> CREATE EDGE like(likeness int);
Execution succeeded (time spent 3710/4483 us)
nebula> CREATE EDGE INDEX like_index on like();

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> REBUILD EDGE INDEX like_index;
+------------+
| New Job Id |
+------------+
| 88 |
+------------+
nebula> INSERT EDGE like(likeness) values "player100"->"player101":(95);

nebula)> INSERT EDGE like(likeness) values "player100"->"player101":(95);
Execution succeeded (time spent 1638/2351 us)
# The following statement retrieves all edges with the edge type of 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" |
+-------------+----------+-------------+
Got 1 rows (time spent 1163/1748 us)
```
nebula)> LOOKUP ON like;
+-------------+----------+-------------+
| _src | _ranking | _dst |
+-------------+----------+-------------+
| "player100" | 0 | "player101" |
+-------------+----------+-------------+
```

## Count the numbers of vertices or edges

Expand All @@ -198,13 +228,16 @@ nebula> LOOKUP ON player | YIELD COUNT(*) AS 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)
```

!!! note

You can also use [`show-stats`](./6.show/14.show-stats.md) to count the numbers of vertices or edges.