update general query statements (#631)

* update general query statements * Update 5.lookup.md
vesoft-inc · Aug 31, 2021 · d03d834 · d03d834
1 parent 0a77f61
commit d03d834
Show file tree

Hide file tree

Showing 6 changed files with 107 additions and 91 deletions.
diff --git a/docs-2.0/3.ngql-guide/7.general-query-statements/2.match.md b/docs-2.0/3.ngql-guide/7.general-query-statements/2.match.md
@@ -156,11 +156,11 @@ You can use the VID to match a vertex. The `id()` function can retrieve the VID
 
 ```ngql
 nebula> MATCH (v) WHERE id(v) == 'player101' RETURN v;
-+---------------------------------------------------+
-| v                                                 |
-+---------------------------------------------------+
-| (player101) player.name:Tony Parker,player.age:36 |
-+---------------------------------------------------+
++-----------------------------------------------------+
+| v                                                   |
++-----------------------------------------------------+
+| ("player101" :player{age: 36, name: "Tony Parker"}) |
++-----------------------------------------------------+
 ```
 
 To match multiple VIDs, use `WHERE id(v) IN [vid_list]`.
@@ -717,6 +717,8 @@ nebula> MATCH p=(v:player{name:"Tim Duncan"})-[*..2]->(v2) \
 +----------------------------------------------------------------------+--------+
 ```
 
-## Performance tips
+!!! Performance
+
+    In Nebula Graph {{ nebula.release }}, the `MATCH` statement has initially optimized for resource usage and performance.
 
-In Nebula Graph {{ nebula.release }}, the `MATCH` statement is not optimized for resource usage and performance. Simpler operations can be replaced by `GO`, `LOOKUP`, `|`, and `FETCH`.
+    Simpler operations can be replaced by `GO`, `LOOKUP`, `|`, and `FETCH`.
diff --git a/docs-2.0/3.ngql-guide/7.general-query-statements/5.lookup.md b/docs-2.0/3.ngql-guide/7.general-query-statements/5.lookup.md
@@ -14,18 +14,28 @@ The `LOOKUP` statement traverses data based on indexes. You can use `LOOKUP` for
 
 This topic applies to native nGQL only.
 
-## Prerequisites
+## 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.
 
-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.
+  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 `age`.
 
-!!! caution
+  !!! compatibility "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
 
-    Correct use of indexes can speed up queries, but indexes can dramatically reduce the write performance. The performance reduction can be as much as 90% or even more. **DO NOT** use indexes in production environments unless you are fully aware of their influences on your service.
+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](../14.native-index-statements/4.rebuild-native-index.md) after creating the index to make it valid.
 
 ## 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>] ...];
@@ -44,6 +54,7 @@ LOOKUP ON {<vertex_tag> | <edge_type>} [WHERE <expression> [AND <expression> ...
 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.
@@ -62,40 +73,27 @@ nebula> REBUILD TAG INDEX index_player;
 | 15         |
 +------------+
 
-nebula> LOOKUP ON player WHERE player.name == "Tony Parker";
+nebula> LOOKUP ON player \
+        WHERE player.name == "Tony Parker";
 ============
 | VertexID |
 ============
 | 101      |
 ------------
 
-# The following example uses regex to retrieve vertices.
-nebula> LOOKUP ON player WHERE player.name =~ "^.{15,20}$" \
+nebula> LOOKUP ON player \
+        WHERE player.name == "Tony Parker" \
         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 |
-+-------------+---------------------+------------+
-| "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 \
+=======================================
+| 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 |
@@ -118,7 +116,8 @@ nebula> REBUILD EDGE INDEX index_follow;
 | 62         |
 +------------+
 
-nebula> LOOKUP ON follow WHERE follow.degree == 90;
+nebula> LOOKUP ON follow \
+        WHERE follow.degree == 90;
 +-------------+-------------+---------+
 | SrcVID      | DstVID      | Ranking |
 +-------------+-------------+---------+
@@ -130,7 +129,9 @@ nebula> LOOKUP ON follow WHERE follow.degree == 90;
 +-------------+-------------+---------+
 ...
 
-nebula> LOOKUP ON follow WHERE follow.degree == 90 YIELD follow.degree;
+nebula> LOOKUP ON follow \
+        WHERE follow.degree == 90 \
+        YIELD follow.degree;
 +-------------+-------------+---------+---------------+
 | SrcVID      | DstVID      | Ranking | follow.degree |
 +-------------+-------------+---------+---------------+
@@ -142,8 +143,10 @@ nebula> LOOKUP ON follow WHERE follow.degree == 90 YIELD follow.degree;
 +-------------+-------------+---------+---------------+
 ...
 
-nebula> LOOKUP ON follow WHERE follow.degree == 60 YIELD follow.degree AS Degree \
-        | GO FROM $-.DstVID OVER serve \
+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 |
@@ -176,9 +179,10 @@ For example, if there is a `player` tag with a `name` property and an `age` prop
     | 66         |
     +------------+
 
-    nebula> INSERT VERTEX player(name,age) VALUES "player100":("Tim Duncan", 42), "player101":("Tony Parker", 36);
+    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 */.
+    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;
     +-------------+
@@ -204,9 +208,10 @@ For example, if there is a `player` tag with a `name` property and an `age` prop
     | 88         |
     +------------+
 
-    nebula> INSERT EDGE like(likeness) values "player100"->"player101":(95);
+    nebula> INSERT EDGE like(likeness) \
+            VALUES "player100"->"player101":(95);
 
-    # 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) */.
+    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;
     +-------------+----------+-------------+
@@ -221,14 +226,16 @@ For example, if there is a `player` tag with a `name` property and an `age` prop
 The following example shows how to count the number of vertices tagged with `player` and edges of the `like` edge type.
 
 ```ngql
-nebula> LOOKUP ON player | YIELD COUNT(*) AS Player_Number;
+nebula> LOOKUP ON player |\
+        YIELD COUNT(*) AS Player_Number;
 +---------------+
 | Player_Number |
 +---------------+
 | 2             |
 +---------------+
 
-nebula> LOOKUP ON like | YIELD COUNT(*) AS Like_Number;
+nebula> LOOKUP ON like | \
+        YIELD COUNT(*) AS Like_Number;
 +-------------+
 | Like_Number |
 +-------------+
@@ -239,4 +246,3 @@ nebula> LOOKUP ON like | YIELD COUNT(*) AS Like_Number;
 !!! note
 
     You can also use [`show-stats`](./6.show/14.show-stats.md) to count the numbers of vertices or edges.
-
diff --git a/docs-2.0/3.ngql-guide/7.general-query-statements/6.show/15.show-tags-edges.md b/docs-2.0/3.ngql-guide/7.general-query-statements/6.show/15.show-tags-edges.md
@@ -32,4 +32,4 @@ nebula> SHOW EDGES;
 +---------+
 | "serve" |
 +---------+
-```
+```
diff --git a/docs-2.0/3.ngql-guide/7.general-query-statements/6.show/6.show-hosts.md b/docs-2.0/3.ngql-guide/7.general-query-statements/6.show/6.show-hosts.md
@@ -25,35 +25,35 @@ nebula> SHOW HOSTS;
 +-------------+-------+----------+--------------+----------------------------------+-----------------------------+
 
 nebula> SHOW HOSTS GRAPH;
-+-----------+------+----------+---------+--------------+---------------------------------------------+
-| Host      | Port | Status   | Role    | Git Info Sha | Version                                     |
-+-----------+------+----------+---------+--------------+---------------------------------------------+
-| "graphd"  | 9669 | "ONLINE" | "GRAPH" | "5368115"    | "5368115, Build Time: Jul 19 2021 02:31:12" |
-+-----------+------+----------+---------+--------------+---------------------------------------------+
-| "graphd1" | 9669 | "ONLINE" | "GRAPH" | "5368115"    | "5368115, Build Time: Jul 19 2021 02:31:12" |
-+-----------+------+----------+---------+--------------+---------------------------------------------+
-| "graphd2" | 9669 | "ONLINE" | "GRAPH" | "5368115"    | "5368115, Build Time: Jul 19 2021 02:31:12" |
-+-----------+------+----------+---------+--------------+---------------------------------------------+
++-----------+------+----------+---------+---------------+------------------------------------------+
+| Host      | Port | Status   | Role    | Git Info Sha | Version                                   |
++-----------+------+----------+---------+--------------+-------------------------------------------+
+| "graphd"  | 9669 | "ONLINE" | "GRAPH" | "c397299c"   | "2.5.0, Build Time: Aug 19 2021 11:20:18" |
++-----------+------+----------+---------+--------------+-------------------------------------------+
+| "graphd1" | 9669 | "ONLINE" | "GRAPH" | "c397299c"   | "2.5.0, Build Time: Aug 19 2021 11:20:18" |
++-----------+------+----------+---------+--------------+-------------------------------------------+
+| "graphd2" | 9669 | "ONLINE" | "GRAPH" | "c397299c"   | "2.5.0, Build Time: Aug 19 2021 11:20:18" |
++-----------+------+----------+---------+--------------+-------------------------------------------+
 
 nebula> SHOW HOSTS STORAGE;
-+-------------+------+----------+-----------+--------------+---------------------------------------------+
-| Host        | Port | Status   | Role      | Git Info Sha | Version                                     |
-+-------------+------+----------+-----------+--------------+---------------------------------------------+
-| "storaged0" | 9779 | "ONLINE" | "STORAGE" | "0dfa699"    | "0dfa699, Build Time: Jul 19 2021 02:22:45" |
-+-------------+------+----------+-----------+--------------+---------------------------------------------+
-| "storaged1" | 9779 | "ONLINE" | "STORAGE" | "0dfa699"    | "0dfa699, Build Time: Jul 19 2021 02:22:45" |
-+-------------+------+----------+-----------+--------------+---------------------------------------------+
-| "storaged2" | 9779 | "ONLINE" | "STORAGE" | "0dfa699"    | "0dfa699, Build Time: Jul 19 2021 02:22:45" |
-+-------------+------+----------+-----------+--------------+---------------------------------------------+
++-------------+------+----------+-----------+--------------+-------------------------------------------+
+| Host        | Port | Status   | Role      | Git Info Sha | Version                                   |
++-------------+------+----------+-----------+--------------+-------------------------------------------+
+| "storaged0" | 9779 | "ONLINE" | "STORAGE" | "5b83e5cb"   | "2.5.0, Build Time: Aug 19 2021 10:30:28" |
++-------------+------+----------+-----------+--------------+-------------------------------------------+
+| "storaged1" | 9779 | "ONLINE" | "STORAGE" | "5b83e5cb"   | "2.5.0, Build Time: Aug 19 2021 10:30:28" |
++-------------+------+----------+-----------+--------------+-------------------------------------------+
+| "storaged2" | 9779 | "ONLINE" | "STORAGE" | "5b83e5cb"   | "2.5.0, Build Time: Aug 19 2021 10:30:28" |
++-------------+------+----------+-----------+--------------+-------------------------------------------+
 
 nebula> SHOW HOSTS META;
-+----------+------+----------+--------+--------------+---------------------------------------------+
-| Host     | Port | Status   | Role   | Git Info Sha | Version                                     |
-+----------+------+----------+--------+--------------+---------------------------------------------+
-| "metad2" | 9559 | "ONLINE" | "META" | "0dfa699"    | "0dfa699, Build Time: Jul 19 2021 02:23:49" |
-+----------+------+----------+--------+--------------+---------------------------------------------+
-| "metad0" | 9559 | "ONLINE" | "META" | "0dfa699"    | "0dfa699, Build Time: Jul 19 2021 02:23:49" |
-+----------+------+----------+--------+--------------+---------------------------------------------+
-| "metad1" | 9559 | "ONLINE" | "META" | "0dfa699"    | "0dfa699, Build Time: Jul 19 2021 02:23:49" |
-+----------+------+----------+--------+--------------+---------------------------------------------+
++----------+------+----------+--------+--------------+-------------------------------------------+
+| Host     | Port | Status   | Role   | Git Info Sha | Version                                   |
++----------+------+----------+--------+--------------+-------------------------------------------+
+| "metad2" | 9559 | "ONLINE" | "META" | "5b83e5cb"   | "2.5.0, Build Time: Aug 19 2021 10:30:28" |
++----------+------+----------+--------+--------------+-------------------------------------------+
+| "metad0" | 9559 | "ONLINE" | "META" | "5b83e5cb"   | "2.5.0, Build Time: Aug 19 2021 10:30:28" |
++----------+------+----------+--------+--------------+-------------------------------------------+
+| "metad1" | 9559 | "ONLINE" | "META" | "5b83e5cb"   | "2.5.0, Build Time: Aug 19 2021 10:30:28" |
++----------+------+----------+--------+--------------+-------------------------------------------+
 ```
diff --git a/docs-2.0/3.ngql-guide/7.general-query-statements/6.show/8.show-indexes.md b/docs-2.0/3.ngql-guide/7.general-query-statements/6.show/8.show-indexes.md
@@ -12,18 +12,26 @@ SHOW {TAG | EDGE} INDEXES;
 
 ```ngql
 nebula> SHOW TAG INDEXES;
-+------------------+
-| Names            |
-+------------------+
-| "play_age_0"     |
-+------------------+
-| "player_index_0" |
-+------------------+
++------------------+--------------+-----------------+
+| Index Name       | By Tag       | Columns         |
++------------------+--------------+-----------------+
+| "fix"            | "fix_string" | ["p1"]          |
++------------------+--------------+-----------------+
+| "player_index_0" | "player"     | ["name"]        |
++------------------+--------------+-----------------+
+| "player_index_1" | "player"     | ["name", "age"] |
++------------------+--------------+-----------------+
+| "var"            | "var_string" | ["p1"]          |
++------------------+--------------+-----------------+
 
 nebula> SHOW EDGE INDEXES;
-+----------------+
-| Names          |
-+----------------+
-| "index_follow" |
-+----------------+
++----------------+----------+---------+
+| Index Name     | By Edge  | Columns |
++----------------+----------+---------+
+| "follow_index" | "follow" | []      |
++----------------+----------+---------+
 ```
+
+!!! Compatibility "Legacy version compatibility"
+
+    In Nebula Graph 2.0.1, `SHOW TAG/EDGE INDEXES` only returns `Names`.
diff --git a/docs-2.0/3.ngql-guide/7.general-query-statements/7.unwind.md b/docs-2.0/3.ngql-guide/7.general-query-statements/7.unwind.md
@@ -7,7 +7,7 @@ The `UNWIND` statement splits a list into separated rows.
 ## Syntax
 
 ```ngql
-UNWIND <list> AS <alias> <RETURN clause>
+UNWIND <list> AS <alias> <RETURN clause>;
 ```
 
 ## Split a list
-Original file line number
+Diff line change
@@ Expand Up / @@ -32,4 +32,4 @@ nebula> SHOW EDGES; @@
     +---------+
     | "serve" |
     +---------+
-    ```
+    ```