Merge branch 'master' into zone/group

CONTRIBUTING.md

@@ -6,11 +6,11 @@
 
 可以从以下方面进行贡献：
 
-- 修正拼写错误或格式（标点，空格，缩进，代码块等）
-- 修正或更新不适当或过时的描述
-- 提交新文档
-- 提交或解决文档[issues](https://github.com/vesoft-inc/nebula-docs-cn/issues)
-- 审阅他人提交的 PR
+- 修正拼写错误或格式（标点，空格，缩进，代码块等）。
+- 修正或更新不适当或过时的描述。
+- 提交新文档。
+- 提交或解决文档 [issue][_issues]。
+- 审阅他人提交的 PR。
 
 ## 必须遵循的 Markdown 规范
 
@@ -22,5 +22,8 @@
 
 可以选择以下方式进行贡献：
 
-- 在 [GitHub](https://github.com/vesoft-inc/nebula-docs-cn/issues) 提交 issue。
-- Fork 文档，在本地分支上更改或添加新内容，然后向主分支提交 PR。
+- 在 GitHub 提交 [issue][_issues]。
+- [Fork](https://github.com/vesoft-inc/nebula-docs-cn/fork) 文档，在本地分支上更改或添加新内容，然后向主分支提交 PR。
+
+
+[_issues]: https://github.com/vesoft-inc/nebula-docs-cn/issues

docs-2.0/1.introduction/1.what-is-nebula-graph.md

@@ -38,7 +38,7 @@ Nebula Graph支持严格的角色访问控制和LDAP（Lightweight Directory Acc
 
 ### 生态多样化
 
-Nebula Graph开放了越来越多的原生工具，例如[Nebula Graph Studio](https://github.com/vesoft-inc/nebula-studio)、[Nebula Console](https://github.com/vesoft-inc/nebula-console)、[Nebula Exchange](https://github.com/vesoft-inc/nebula-spark-utils/tree/v2.0.0/nebula-exchange)等，更多工具可以查看 [生态工具概览](../20.appendix/6.eco-tool-version.md)。
+Nebula Graph开放了越来越多的原生工具，例如[Nebula Graph Studio](https://github.com/vesoft-inc/nebula-studio)、[Nebula Console](https://github.com/vesoft-inc/nebula-console)、[Nebula Exchange](https://github.com/vesoft-inc/nebula-exchange)等，更多工具可以查看 [生态工具概览](../20.appendix/6.eco-tool-version.md)。
 
 此外，Nebula Graph还具备与Spark、Flink、HBase等产品整合的能力，在这个充满挑战与机遇的时代，大大增强了自身的竞争力。
 

docs-2.0/1.introduction/2.data-model.md

@@ -1,20 +1,20 @@
 # 数据模型
 
-本文介绍Nebula Graph的数据模型。数据模型是一种组织数据并说明它们如何相互关联的模型(schema)。
+本文介绍Nebula Graph的数据模型。数据模型是一种组织数据并说明它们如何相互关联的模型（schema）。
 
 ## 数据模型
 
 Nebula Graph数据模型使用6种基本的数据模型：
 
-- 图空间(Space）
+- 图空间（Space）
 
   图空间用于隔离不同团队或者项目的数据。不同图空间的数据是相互隔离的，可以指定不同的存储副本数、权限、分片等。
 
 - 点（Vertex）
 
   点用来保存实体对象，特点如下：
 
-  - 点是用点标识符（`VID`）标识的。`VID`在同一图空间中唯一。VID 是一个 int64, 或者 fixed_string(N)。
+  - 点是用点标识符（`VID`）标识的。`VID`在同一图空间中唯一。VID 是一个 int64，或者 fixed_string(N)。
   - 点必须有至少一个Tag，也可以有多个Tag。但不能没有Tag。
 
 - 边（Edge）
@@ -25,7 +25,7 @@ Nebula Graph数据模型使用6种基本的数据模型：
   - 边是有方向的，不存在无向边。
   - 四元组 `<起点VID、Edge type、边排序值(Rank)、终点VID>` 用于唯一标识一条边。边没有EID。
   - 一条边有且仅有一个Edge type。
-  - 一条边有且仅有一个rank。其为int64, 默认为0。
+  - 一条边有且仅有一个rank。其为int64，默认为0。
 
 - 标签（Tag）
 
@@ -51,17 +51,17 @@ Nebula Graph使用有向属性图模型，指点和边构成的图，这些边
 
 | 类型 | 名称 | 属性名（数据类型） | 说明 |
 | :--- | :--- | :---| :--- |
-|Tag|  **player**      | name （string） <br>age （int）  | 表示球员。  |
-|Tag|   **team** |  name （string） |  表示球队。 |
-|Edge type|  **serve**  |  start_year （int） <br> end_year （int） | 表示球员的行为。<br>该行为将球员和球队联系起来，方向是从球员到球队。  |
-|Edge type|  **follow**  | degree（int）  | 表示球员的行为。<br>该行为将两个球员联系起来，方向是从一个球员到另一个球员。  |
+|Tag|  **player**      | name (string) <br>age（int）  | 表示球员。  |
+|Tag|   **team** |  name (string) |  表示球队。 |
+|Edge type|  **serve**  |  start_year (int) <br> end_year (int) | 表示球员的行为。<br>该行为将球员和球队联系起来，方向是从球员到球队。  |
+|Edge type|  **follow**  | degree (int)  | 表示球员的行为。<br>该行为将两个球员联系起来，方向是从一个球员到另一个球员。  |
 
 !!! Note
 
     Nebula Graph 中没有无向边，只支持有向边。
 
 !!! compatibility
 
-    由于 Nebula Graph {{ nebula.release }} 的数据模型中，允许存在"悬挂边"，因此在增删时，用户需自行保证“一条边所对应的起点和终点”的存在性。详见[INSERT VERTEX](../3.ngql-guide/12.vertex-statements/1.insert-vertex.md), [DELETE VERTEX](../3.ngql-guide/12.vertex-statements/4.delete-vertex.md), [INSERT EDGE](../3.ngql-guide/13.edge-statements/1.insert-edge.md), [DELETE EDGE](../3.ngql-guide/13.edge-statements/4.delete-edge.md)。
+    由于 Nebula Graph {{ nebula.release }} 的数据模型中，允许存在"悬挂边"，因此在增删时，用户需自行保证“一条边所对应的起点和终点”的存在性。详见[INSERT VERTEX](../3.ngql-guide/12.vertex-statements/1.insert-vertex.md)、[DELETE VERTEX](../3.ngql-guide/12.vertex-statements/4.delete-vertex.md)、[INSERT EDGE](../3.ngql-guide/13.edge-statements/1.insert-edge.md)、[DELETE EDGE](../3.ngql-guide/13.edge-statements/4.delete-edge.md)。
 
     不支持 openCypher 中的 MERGE 语句。

docs-2.0/1.introduction/3.nebula-graph-architecture/3.graph-service.md

@@ -20,7 +20,7 @@ Graph 服务主要负责处理查询请求，包括解析查询语句、校验
 
 Parser 模块收到请求后，通过 Flex（词法分析工具）和 Bison（语法分析工具）生成的词法语法解析器，将语句转换为抽象语法树（AST），在语法解析阶段会拦截不符合语法规则的语句。
 
-例如`GO FROM "Tim" OVER like WHERE like.likeness > 8.0 YIELD like._dst`语句转换的 AST 如下。
+例如`GO FROM "Tim" OVER like WHERE properties(edge).likeness > 8.0 YIELD dst(edge)`语句转换的 AST 如下。
 
 ![AST](https://docs-cdn.nebula-graph.com.cn/docs-2.0/1.introduction/2.nebula-graph-architecture/parser-ast-tree.png)
 
@@ -38,7 +38,7 @@ Validator 模块对生成的 AST 进行语义校验，主要包括：
 
     校验引用的变量是否存在或者引用的属性是否属于变量。
 
-    例如语句`$var = GO FROM "Tim" OVER like YIELD like._dst AS ID; GO FROM $var.ID OVER serve YIELD serve._dst`，Validator 模块首先会检查变量 `var` 是否定义，其次再检查属性 `ID` 是否属于变量 `var`。
+    例如语句`$var = GO FROM "Tim" OVER like YIELD dst(edge) AS ID; GO FROM $var.ID OVER serve YIELD dst(edge)`，Validator 模块首先会检查变量 `var` 是否定义，其次再检查属性 `ID` 是否属于变量 `var`。
 
 - 校验类型推断
 
@@ -50,13 +50,13 @@ Validator 模块对生成的 AST 进行语义校验，主要包括：
 
     查询语句中包含 `*` 时，校验子句时需要将 `*` 涉及的Schema都进行校验。
 
-    例如语句`GO FROM "Tim" OVER * YIELD like._dst, like.likeness, serve._dst`，校验`OVER`子句时需要校验所有的 Edge type，如果 Edge type 包含 `like`和`serve`，该语句会展开为`GO FROM "Tim" OVER like,serve YIELD like._dst, like.likeness, serve._dst`。
+    例如语句`GO FROM "Tim" OVER * YIELD dst(edge), properties(edge).likeness, dst(edge)`，校验`OVER`子句时需要校验所有的 Edge type，如果 Edge type 包含 `like`和`serve`，该语句会展开为`GO FROM "Tim" OVER like,serve YIELD dst(edge), properties(edge).likeness, dst(edge)`。
 
 - 校验输入输出
 
     校验管道符（|）前后的一致性。
 
-    例如语句`GO FROM "Tim" OVER like YIELD like._dst AS ID | GO FROM $-.ID OVER serve YIELD serve._dst`，Validator 模块会校验 `$-.ID` 在管道符左侧是否已经定义。
+    例如语句`GO FROM "Tim" OVER like YIELD dst(edge) AS ID | GO FROM $-.ID OVER serve YIELD dst(edge)`，Validator 模块会校验 `$-.ID` 在管道符左侧是否已经定义。
 
 校验完成后，Validator 模块还会生成一个默认可执行，但是未进行优化的执行计划，存储在目录 `src/planner` 内。
 

docs-2.0/1.introduction/3.vid.md

@@ -28,7 +28,7 @@
 
 - 可以使用`LOOKUP`或者`MATCH`语句，来通过属性索引查找对应的VID;
 
-- 性能上，直接通过VID找到点的语句性能最高，例如`DELETE xxx WHERE id(xxx) == "player100"`, 或者`GO FROM "player100"`等语句。通过属性先查找VID，再进行图操作的性能会变差，例如`LOOKUP | GO FROM $-.ids`等语句，相比前者多了一次内存或硬盘的随机读（`LOOKUP`）以及一次序列化（`|`）。
+- 性能上，直接通过VID找到点的语句性能最高，例如`DELETE xxx WHERE id(xxx) == "player100"`，或者`GO FROM "player100"`等语句。通过属性先查找VID，再进行图操作的性能会变差，例如`LOOKUP | GO FROM $-.ids`等语句，相比前者多了一次内存或硬盘的随机读（`LOOKUP`）以及一次序列化（`|`）。
 
 ## VID生成建议
 
@@ -50,16 +50,15 @@ VID的数据类型必须在[创建图空间](../3.ngql-guide/9.space-statements/
 
 ## "查询起始点"(`start vid`)与全局扫描
 
-绝大多数情况下，Nebula Graph 的查询语句(`MATCH`, `GO`, `LOOKUP`)的执行计划，必须要通过一定方式找到查询起始点的 VID (`start vid`)。
+绝大多数情况下，Nebula Graph 的查询语句（`MATCH`、`GO`、`LOOKUP`）的执行计划，必须要通过一定方式找到查询起始点的 VID（`start vid`）。
 
 定位 `start vid` 只有两种方式：
 
 1. 例如 `GO FROM "player100" OVER` 是在语句中显式的指明 `start vid` 是 "player100";
 
-2. 例如, `LOOKUP ON player WHERE player.name == "Tony Parker"` 或者 `MATCH (v:player {name:"Tony Parker"}) `，是通过属性 `player.name` 的索引来定位到 `start vid`；
+2. 例如 `LOOKUP ON player WHERE player.name == "Tony Parker"` 或者 `MATCH (v:player {name:"Tony Parker"}) `，是通过属性 `player.name` 的索引来定位到 `start vid`；
 
 
 !!! caution "不能在没有 `start vid` 情况下进行全局扫描"
 
     例如 `match (n) return n;` 会返回错误，因为此时无法定位到 `start vid`；这是一个全局扫描，因此被禁止。
-

docs-2.0/14.client/4.nebula-java-client.md

@@ -101,7 +101,7 @@ try {
     ResultSet resp = session.execute(insertEdges);
 
     // query
-    String query = "GO FROM \"Bob\" OVER like " + "YIELD $$.person.name, $$.person.age, like.likeness";
+    String query = "GO FROM \"Bob\" OVER like " + "YIELD properties($$).name, properties($$).age, properties(edge).likeness";
     ResultSet resp = session.execute(query);
     printResult(resp);
 }finally {

docs-2.0/15.contribution/how-to-contribute.md

@@ -110,7 +110,8 @@ Nebula Graph项目有很多[仓库](https://github.com/vesoft-inc)，以[nebula-
 
   !!! Note
 
-        由于一个PR通常包含多个commit，在合并至master时容易被挤压（squash），因此强烈建议创建一个独立的分支进行更改。合并后，这个分支可以被丢弃，因此可以使用上述rebase命令将本地master与upstream同步。此外，如果直接将commit提交至 master，用户可以需要在master分支使用hard reset，例如：
+        由于一个PR通常包含多个commits，最终合入upstream/master分支时，我们会将这些commits挤压（squash）成一个commit进行合并。因此强烈建议创建一个独立的分支进行更改，这样在合入时才容易被挤压。合并后，这个分支可以被丢弃。如果未创建单独的分支，而是直接将commits提交至origin/master，在合入时，可能会出现问题。
+        若未创建单独的分支（或是origin/master合并了其他的分支等），导致origin/master和upstream/master不一致时，用户可以使用hard reset强制两者进行一致。例如：
 
         ```bash
         git fetch upstream

docs-2.0/2.quick-start/4.nebula-graph-crud.md

@@ -269,34 +269,37 @@ Execution succeeded (time spent 5858/6870 us)
 
     ```ngql
     GO [[<M> TO] <N> STEPS ] FROM <vertex_list>
-    OVER <edge_type_list> [REVERSELY] [BIDIRECT]
-    [WHERE <expression> [AND | OR expression ...])]
-    YIELD [DISTINCT] <return_list>;
+    OVER <edge_type_list> [{REVERSELY | BIDIRECT}]
+    [ WHERE <conditions> ]
+    [YIELD [DISTINCT] <return_list>]
+    [| GROUP BY {col_name | expr | position} YIELD <col_name>]
+    [| ORDER BY <expression> [{ASC | DESC}]]
+    [| LIMIT [<offset_value>,] <number_rows>];
     ```
 
 - `FETCH`
 
   - 查询Tag属性
 
     ```ngql
-    FETCH PROP ON {<tag_name> | <tag_name_list> | *} <vid_list>
-    [YIELD [DISTINCT] <return_list>];
+    FETCH PROP ON {<tag_name>[, tag_name ...] | *} 
+    <vid> [, vid ...] 
+    [YIELD <return_list> [AS <alias>]]; 
     ```
 
   - 查询边属性
 
     ```ngql
-    FETCH PROP ON <edge_type> <src_vid> -> <dst_vid>[@<rank>]
-    [, <src_vid> -> <dst_vid> ...]
-    [YIELD [DISTINCT] <return_list>];
+    FETCH PROP ON <edge_type> <src_vid> -> <dst_vid>[@<rank>] [, <src_vid> -> <dst_vid> ...]
+    [YIELD <output>];
     ```
 
 - `LOOKUP`
 
     ```ngql
-    LOOKUP ON {<tag_name> | <edge_type>} 
-    WHERE <expression> [AND expression ...])]
-    [YIELD <return_list>];
+    LOOKUP ON {<vertex_tag> | <edge_type>} 
+    [WHERE <expression> [AND <expression> ...]] 
+    [YIELD <return_list> [AS <alias>]];
     ```
 
 - `MATCH`
@@ -324,14 +327,15 @@ Execution succeeded (time spent 5858/6870 us)
 - 从VID为`player100`的球员开始，沿着边`follow`查找年龄大于或等于35岁的球员，并返回他们的姓名和年龄，同时重命名对应的列。
 
     ```ngql
-    nebula> GO FROM "player100" OVER follow WHERE $$.player.age >= 35 \
-            YIELD $$.player.name AS Teammate, $$.player.age AS Age;
-    +---------------+-----+
-    | Teammate      | Age |
-    +---------------+-----+
-    | "Tony Parker" | 36  |
-    +---------------+-----+
-    Got 1 rows (time spent 8206/9335 us)
+    nebula> GO FROM "player100" OVER follow WHERE properties($$).age >= 35 \
+            YIELD properties($$).name AS Teammate, properties($$).age AS Age;
+    +-----------------+-----+
+    | Teammate        | Age |
+    +-----------------+-----+
+    | "Tony Parker"   | 36  |
+    +-----------------+-----+
+    | "Manu Ginobili" | 41  |
+    +-----------------+-----+
     ```
 
     |子句/符号|说明|
@@ -345,15 +349,18 @@ Execution succeeded (time spent 5858/6870 us)
   - 使用管道符
 
     ```ngql
-    nebula> GO FROM "player100" OVER follow YIELD follow._dst AS id | \
-            GO FROM $-.id OVER serve YIELD $$.team.name AS Team, \
-            $^.player.name AS Player;
-    +-----------+---------------+
-    | Team      | Player        |
-    +-----------+---------------+
-    | "Nuggets" | "Tony Parker" |
-    +-----------+---------------+
-    Got 1 rows (time spent 5055/8203 us)
+    nebula> GO FROM "player100" OVER follow YIELD dst(edge) AS id | \
+            GO FROM $-.id OVER serve YIELD properties($$).name AS Team, \
+            properties($^).name AS Player;
+    +-----------+-----------------+
+    | Team      | Player          |
+    +-----------+-----------------+
+    | "Spurs"   | "Tony Parker"   |
+    +-----------+-----------------+
+    | "Hornets" | "Tony Parker"   |
+    +-----------+-----------------+
+    | "Spurs"   | "Manu Ginobili" |
+    +-----------+-----------------+
     ```
   
     |子句/符号|说明|
@@ -369,15 +376,18 @@ Execution succeeded (time spent 5858/6870 us)
         当复合语句作为一个整体提交给服务器时，其中的临时变量会在语句结束时被释放。
 
     ```ngql
-    nebula> $var = GO FROM "player100" OVER follow YIELD follow._dst AS id; \
-            GO FROM $var.id OVER serve YIELD $$.team.name AS Team, \
-            $^.player.name AS Player;
-    +---------+-------------+
-    | Team    | Player      |
-    +---------+-------------+
-    | Nuggets | Tony Parker |
-    +---------+-------------+
-    Got 1 rows (time spent 3103/3711 us)
+    nebula> $var = GO FROM "player100" OVER follow YIELD dst(edge) AS id; \
+            GO FROM $var.id OVER serve YIELD properties($$).name AS Team, \
+            properties($^).name AS Player;
+    +-----------+-----------------+
+    | Team      | Player          |
+    +-----------+-----------------+
+    | "Spurs"   | "Tony Parker"   |
+    +-----------+-----------------+
+    | "Hornets" | "Tony Parker"   |
+    +-----------+-----------------+
+    | "Spurs"   | "Manu Ginobili" |
+    +-----------+-----------------+
     ```
 
 ### `FETCH`语句示例
@@ -391,7 +401,6 @@ nebula> FETCH PROP ON player "player100";
 +----------------------------------------------------+
 | ("player100" :player{age: 42, name: "Tim Duncan"}) |
 +----------------------------------------------------+
-Got 1 rows (time spent 2006/2406 us)
 ```
 
 !!! Note
@@ -463,7 +472,7 @@ Got 1 rows (time spent 2006/2406 us)
     Got 1 rows (time spent 2205/2800 us)
     ```
 
-- 用`UPSERT`插入一个VID为`player111`的点。
+- 用`INSERT`插入一个VID为`player111`的点，然后用`UPSERT`更新它。
 
     ```ngql
     nebula> INSERT VERTEX player(name, age) VALUES "player111":("Ben Simmons", 22);