[doc]ngql-bnf (vesoft-inc#1435)

* ngql-bnf

* add java

* wum

* wilson

* wum

* fix ranking

docs/manual-CN/1.overview/2.quick-start/3.supported-clients.md

@@ -4,3 +4,4 @@
 
 * [Go 客户端](https://github.com/vesoft-inc/nebula-go)
 * [Python 客户端](https://github.com/vesoft-inc/nebula-python)
+* [Java 客户端](https://github.com/vesoft-inc/nebula-java)

docs/manual-CN/2.query-language/1.data-types/data-types.md

@@ -37,9 +37,9 @@
 - 时间戳单位为秒
 - 插入数据的时候，支持插入方式
   - 调用函数 now()
-  - 时间字符串， 例如："2019-10-01 10:00:00"
+  - 时间字符串，例如："2019-10-01 10:00:00"
   - 直接输入时间戳，即从 1970-01-01 00:00:00 开始的秒数
-- 做数据存储的时候，会先将时间转化为**UTC 时间**，读取的时候会将存储的**UTC 时间**转换为**本地时间**给用户
+- 做数据存储的时候，会先将时间转化为 **UTC 时间**，读取的时候会将存储的 **UTC 时间**转换为**本地时间**给用户
 - 底层存储数据类型为: **int64**
 
 ## 示例

docs/manual-CN/2.query-language/1.data-types/type-conversion.md

@@ -8,8 +8,8 @@
 
 1. 以下类型均可隐式转换至 `bool` 类型：
 
-+ 当且仅当字符串长度为 0 时，可被隐式转换为 `false` ，否则为 `true`
-+ 当且仅当整型数值为 0 时，可被隐式转换为 `false` ，否则为 `true`
++ 当且仅当字符串长度为 `0` 时，可被隐式转换为 `false` ，否则为 `true`
++ 当且仅当整型数值为 `0` 时，可被隐式转换为 `false` ，否则为 `true`
 + 当且仅当浮点类型数值为 `0.0` 时，可被隐式转换为 `false` ，否则为 `true`
 
 2. `int` 类型可隐式转换为 `double` 类型

docs/manual-CN/2.query-language/2.functions-and-operators/order-by-function.md

@@ -3,7 +3,7 @@
 类似于 SQL，`ORDER BY` 可以进行升序 (`ASC`) 或降序 (`DESC`) 的排序来返回结果，并且它只能在 `PIPE` 语句 (`|`) 中使用。
 
 ```ngql
-ORDER BY <prop> ASC | DESC [, <prop> ASC | DESC ...]
+ORDER BY <expression> [ASC | DESC] [, <expression> [ASC | DESC] ...]
 ```
 
 如果没有指明 ASC 或 DESC，`ORDER BY` 将默认进行升序排序。

docs/manual-CN/2.query-language/2.functions-and-operators/set-operations.md

@@ -7,10 +7,10 @@
 `UNION ALL` 返回数据集 A 和 B 的并集（包含重复元素）。`UNION` 语法为
 
 ```ngql
-<left> UNION [DISTINCT | ALL] <right>
+<left> UNION [DISTINCT | ALL] <right> [ UNION [DISTINCT | ALL] <right> ...]
 ```
 
-`<left>` 和 `<right>` 必须列数相同，且数据类型相同。
+`<left>` 和 `<right>` 必须列数相同，且数据类型相同。如果数据类型不同，将按照[类型转换](../1.data-types/type-conversion.md)进行转换。
 
 ### 示例
 
@@ -28,7 +28,7 @@ nebula> GO FROM 1 OVER e1 \
         GO FROM 2 OVER e1
 ```
 
-以上语句返回点 `1` 和 `2` 关联的点，其中存在重复点。
+以上语句返回点 `1` 和 `2` 关联的所有点，其中存在重复点。
 
 `UNION` 亦可与 `YIELD` 同时使用，例如以下语句：
 
@@ -53,9 +53,9 @@ nebula> GO FROM 2,3 OVER e1 YIELD e1._dst AS id, e1.prop1 AS right_1, $$.tag.pro
 ```
 
 ```ngql
-nebula> GO FROM 1 OVER e1 YIELD e1._dst AS id, e1.prop1 AS left_1, $$.tag.prop2 AS left_2
-UNION /* DISTINCT */
-GO FROM 2,3 OVER e1 YIELD e1._dst AS id, e1.prop1 AS right_1, $$.tag.prop2 AS right_2
+nebula> GO FROM 1 OVER e1 YIELD e1._dst AS id, e1.prop1 AS left_1, $$.tag.prop2 AS left_2   \
+        UNION /* DISTINCT */     \
+        GO FROM 2,3 OVER e1 YIELD e1._dst AS id, e1.prop1 AS right_1, $$.tag.prop2 AS right_2
 ```
 
 以上语句返回

docs/manual-CN/2.query-language/4.statement-syntax/1.data-definition-statements/alter-tag-edge-syntax.md

@@ -1,8 +1,8 @@
 # 修改 Tag / Edge
 
 ```ngql
-ALTER {TAG | EDGE} tag_name | edge_name
-    [alter_definition [, alter_definition] ...]
+ALTER TAG | EDGE <tag_name> | <edge_name>
+    <alter_definition> [, alter_definition] ...]
     [ttl_definition [, ttl_definition] ... ]
 
 alter_definition:

docs/manual-CN/2.query-language/4.statement-syntax/1.data-definition-statements/drop-edge-syntax.md

@@ -1,7 +1,7 @@
 # DROP EDGE 语法
 
 ```ngql
-DROP EDGE edge_type_name
+DROP EDGE <edge_type_name>
 ```
 
 仅支持有 DROP 权限的用户进行此操作。

docs/manual-CN/2.query-language/4.statement-syntax/1.data-definition-statements/drop-space-syntax.md

@@ -1,7 +1,7 @@
 # DROP SPACE 语法
 
 ```ngql
-DROP SPACE space_name
+DROP SPACE <space_name<>
 ```
 
 仅支持有 DROP 权限的用户进行此操作。

docs/manual-CN/2.query-language/4.statement-syntax/2.data-query-and-manipulation-statements/delete-edge-syntax.md

@@ -3,7 +3,7 @@
  `DELETE EDGE` 语句用于删除边。给定一个 edge 类型，及其起点与终点，**Nebula Graph** 支持删除这条边及其相关属性和 ranking，也支持指定 ranking 删除边，语法如下：
 
 ```ngql
-DELETE EDGE <edge_type> <vid> -> <vid>@ranking [, <vid> -> <vid> ...]
+DELETE EDGE <edge_type> <vid> -> <vid>[@<ranking>] [, <vid> -> <vid> ...]
 ```
 
 系统内部会找出与这条边相关联的属性，并将其全部删除。整个过程当前还无法保证原子性，因此当遇到失败时请重试。

docs/manual-CN/2.query-language/4.statement-syntax/2.data-query-and-manipulation-statements/delete-vertex-syntax.md

@@ -3,7 +3,7 @@
 **Nebula Graph** 支持给定一个 vertex ID，删掉这个顶点和与它相关联的入边和出边，语法如下：
 
 ```ngql
-DELETE VERTEX $vid
+DELETE VERTEX <vid>
 ```
 
 系统内部会找出与这个顶点相关联的出边和入边，并将其全部删除，然后再删除点相关的信息。整个过程当前还无法保证原子性，因此当遇到失败时请重试。

docs/manual-CN/2.query-language/4.statement-syntax/2.data-query-and-manipulation-statements/go-syntax.md

@@ -6,13 +6,13 @@
 <!-- >请参考`FIND`的用法，它对应于SQL中的`SELECT`。 -->
 
 ```ngql
-  GO FROM <node_list>
-  OVER <edge_type_list>
-  WHERE (expression [ AND | OR expression ...])  
-  YIELD | YIELDS  [DISTINCT] <return_list>
+  GO [ <N> STEPS ] FROM <node_list>
+  OVER <edge_type_list> [REVERSELY]
+  [ WHERE <expression> [ AND | OR expression ...]) ]
+  YIELD | YIELDS [DISTINCT] <return_list>
 
 <node_list>
-   | vid [, vid ...]
+   | <vid> [, <vid> ...]
    | $-.id
 
 <edge_type_list>
@@ -22,10 +22,10 @@
     <col_name> [AS <col_alias>] [, <col_name> [AS <col_alias>] ...]
 ```
 
+* [ <N> STEPS ] 指定查询 N 跳
 * <node_list> 为逗号隔开的节点 ID，或特殊占位符 `$-.id` (参看 `PIPE` 用法)。
 * <edge_type_list> 为图遍历返回的边类型列表。
-* WHERE <filter_list> 指定被筛选的逻辑条件，WHERE 可用于起点，边及终点，同样支持逻辑关键词
- AND，OR，NOT，详情参见 WHERE 的用法。
+* [ WHERE <expression> ] 指定被筛选的逻辑条件，WHERE 可用于起点，边及终点，同样支持逻辑关键词 AND、OR、NOT，详情参见 WHERE 的用法。
 * YIELD [DISTINCT] <return_list> 以列的形式返回结果，并可对列进行重命名。详情参看 `YIELD`
  用法。`DISTINCT` 的用法与 SQL 相同。
 
@@ -43,6 +43,18 @@ nebula> GO FROM 101 OVER serve  \
 -------
 ```
 
+```ngql
+nebula> GO 2 STEPS FROM 103 OVER follow \
+  /* 返回点 103 的 2 度的好友 */
+===============
+| follow._dst |
+===============
+| 100         |
+---------------
+| 101         |
+---------------
+```
+
 ```ngql
 nebula> GO FROM 101 OVER serve  \
    WHERE serve.start_year > 1990       /* 筛选边 serve 的 start_year 属性  */ \

docs/manual-CN/2.query-language/4.statement-syntax/2.data-query-and-manipulation-statements/insert-edge-syntax.md

@@ -1,9 +1,9 @@
 # INSERT EDGE 语法
 
 ```ngql
-INSERT EDGE edge_name ( <prop_name_list> ) {VALUES | VALUE}
-<src_vid> -> <dst_vid>@ranking : ( <prop_value_list> )
-[, <src_vid> -> <dst_vid> : ( <prop_value_list> )]
+INSERT EDGE <edge_name> ( <prop_name_list> ) VALUES | VALUE
+<src_vid> -> <dst_vid>[@<ranking>] : ( <prop_value_list> )
+[, <src_vid> -> <dst_vid> : ( <prop_value_list> ), ...]
 
 <prop_name_list>:
   [ <prop_name> [, <prop_name> ] ...]

docs/manual-CN/2.query-language/4.statement-syntax/2.data-query-and-manipulation-statements/insert-vertex-syntax.md

@@ -1,7 +1,7 @@
 # INSERT VERTEX 语法
 
 ```ngql
-INSERT VERTEX tag_name[, tag_name] (prop_name_list[, prop_name_list])
+INSERT VERTEX <tag_name> [, <tag_name>, ...] (prop_name_list[, prop_name_list])
      {VALUES | VALUE} vid: (prop_value_list[, prop_value_list])
 
 prop_name_list:

docs/manual-CN/2.query-language/4.statement-syntax/2.data-query-and-manipulation-statements/update-vertex-edge-syntax.md

@@ -5,18 +5,18 @@
 ## 更新点
 
 ```ngql
-UPDATE VERTEX $vid SET $update_columns WHEN $condition YIELD $columns
+UPDATE VERTEX <vid> SET <update_columns> WHEN <condition> YIELD <columns>
 ```
 
 **注意：**`WHEN` 和 `YIELD` 是可选的。
 
-- `$vid` 表示需要更新的 vertex ID。
-- `$update_columns` 表示需要更新的 tag 上的 columns，比如 `tag1.col1 = $^.tag2.col2 + 1` 表示把这个点的 `tag1.col1` 更新成 `tag2.col2 + 1`。
+- `vid` 表示需要更新的 vertex ID。
+- `update_columns` 表示需要更新的 tag 上的 columns，比如 `tag1.col1 = $^.tag2.col2 + 1` 表示把这个点的 `tag1.col1` 更新成 `tag2.col2 + 1`。
 
     **注意：**  `$^`表示 `UPDATE` 中需要更新的点
 
-- `$condition` 是一些约束条件，只有满足这个条件，`UPDATE` 才会真正执行，支持表达式操作。
-- `$columns` 表示需要返回的 columns，此处 `YIELD` 可返回 update 以后最新的 columns 值。
+- `condition` 是一些约束条件，只有满足这个条件，`UPDATE` 才会真正执行，支持表达式操作。
+- `columns` 表示需要返回的 columns，此处 `YIELD` 可返回 update 以后最新的 columns 值。
 
 ### 示例
 
@@ -29,15 +29,15 @@ nebula> UPDATE VERTEX 101 SET course.credits = $^.course.credits + 1, building.n
 ## 更新边
 
 ```ngql
-UPDATE EDGE $edge SET $update_columns WHEN $condition YIELD $columns
+UPDATE EDGE <edge> SET <update_columns> WHEN <condition> YIELD <columns>
 ```
 
 **注意：**`WHEN` 和 `YIELD` 是可选的。
 
-- `$edge` 表示需要更新的 edge，edge 的格式为 `$src->$dst@$rank OF $type`。
-- `$update_columns` 表示需要更新的 edge 上的属性。
-- `$condition` 是一些约束条件，只有满足这个条件，update 才会真正执行，支持表达式操作。
-- `$columns` 表示需要返回的 columns，此处 YIELD 可返回 update 以后最新的 columns 值。
+- `edge` 表示需要更新的 edge，edge 的格式为 `$src->$dst@$rank OF $type`。
+- `update_columns` 表示需要更新的 edge 上的属性。
+- `condition` 是一些约束条件，只有满足这个条件，update 才会真正执行，支持表达式操作。
+- `columns` 表示需要返回的 columns，此处 YIELD 可返回 update 以后最新的 columns 值。
 
 ### 示例
 

docs/manual-CN/2.query-language/4.statement-syntax/2.data-query-and-manipulation-statements/where-syntax.md

@@ -3,7 +3,7 @@
 目前，`WHERE` 语句仅适用于 `GO` 语句。
 
 ```ngql
-WHERE (expression [ AND | OR expression ...])  
+WHERE <expression> [ AND | OR <expression> ...])  
 ```
 
 通常，筛选条件是关于节点、边的表达式的逻辑组合。

docs/manual-CN/2.query-language/4.statement-syntax/3.utility-statements/describe-syntax.md

@@ -1,9 +1,9 @@
 # DESCRIBE 语法
 
 ```ngql
-DESCRIBE SPACE space_name
-DESCRIBE TAG tag_name
-DESCRIBE EDGE edge_name
+DESCRIBE SPACE <space_name>
+DESCRIBE TAG <tag_name>
+DESCRIBE EDGE <edge_name>
 ```
 
 DESCRIBE 关键词的作用是获取关于 space, tag, edge 结构的信息。

docs/manual-EN/1.overview/2.quick-start/3.supported-clients.md

@@ -2,5 +2,6 @@
 
 Currently, **Nebula Graph** supports the following clients:
 
-* [Go 客户端](https://github.com/vesoft-inc/nebula-go)
-* [Python 客户端](https://github.com/vesoft-inc/nebula-python)
+* [Go Client](https://github.com/vesoft-inc/nebula-go)
+* [Python Client](https://github.com/vesoft-inc/nebula-python)
+* [Java Client](https://github.com/vesoft-inc/nebula-java)

docs/manual-EN/2.query-language/2.functions-and-operators/order-by-function.md

@@ -4,7 +4,7 @@ Similar with SQL, `ORDER BY` can be used to sort in ascending (`ASC`) or descend
 And it can only be used in the `PIPE`-syntax (`|`).
 
 ```ngql
-| ORDER BY <prop> ASC | DESC [, <prop> ASC | DESC ...]
+ORDER BY <expression> [ASC | DESC] [, <expression> [ASC | DESC] ...]
 ```
 
 By default, `ORDER BY` sorts the records in ascending order if no `ASC` or `DESC` is given.

docs/manual-EN/2.query-language/2.functions-and-operators/set-operations.md

@@ -4,13 +4,13 @@
 
 Operator `UNION DISTINCT` (or by short `UNION`) returns the union of two sets A and B (denoted by `A ⋃ B` in mathematics), with the distinct element belongs to set A or set B, or both.
 
-Meanwhile, operation `UNION ALL` returns the union set with duplicated elements. The `UNION`-syntax is
+Meanwhile, operation `UNION ALL` returns the union set with duplicated elements. The `UNION` syntax is
 
 ```ngql
-<left> UNION [DISTINCT | ALL] <right>
+<left> UNION [DISTINCT | ALL] <right> [ UNION [DISTINCT | ALL] <right> ...]
 ```
 
-where `<left>` and `<right>` must have the same number of columns and pair-wise data types.
+where `<left>` and `<right>` must have the same number of columns and pair-wise data types. If the data types are different, **Nebula Graph** will convert according to [Type Conversion](../1.data-types/type-conversion.md).
 
 ### Example
 
@@ -22,7 +22,7 @@ nebula> GO FROM 1 OVER e1 \
         GO FROM 2 OVER e1
 ```
 
-return the neighbors' id of vertex `1` and `2` (along with edge `e1`) without duplication.
+returns the neighbors' id of vertex `1` and `2` (along with edge `e1`) without duplication.
 
 While
 
@@ -60,7 +60,7 @@ And the following statement
 
 ```ngql
 nebula> GO FROM 1 OVER e1 YIELD e1._dst AS id, e1.prop1 AS left_1, $$.tag.prop2 AS left_2   \
-        UNION ALL   \
+        UNION /* DISTINCT */   \
         GO FROM 2,3 OVER e1 YIELD e1._dst AS id, e1.prop1 AS right_1, $$.tag.prop2 AS right_2
 ```
 
@@ -111,17 +111,15 @@ Operator `INTERSECT` returns the intersection of two sets A and B (denoted by A
 Alike `UNION`, `<left>` and `<right>` must have the same number of columns and data types.
 Besides, only the same line of `<left>` and `<right>` will be returned.
 
-### Example
-
-You can imagine
+For example, the following query
 
 ```ngql
 nebula> GO FROM 1 OVER e1 YIELD e1._dst AS id, e1.prop1 AS left_1, $$.tag.prop2 AS left_2
 INTERSECT
 GO FROM 2,3 OVER e1 YIELD e1._dst AS id, e1.prop1 AS right_1, $$.tag.prop2 AS right_2
 ```
 
-will return
+returns
 
 ```ngql
 =========================
@@ -135,7 +133,7 @@ will return
 
 The set subtraction (or difference), A - B, consists of elements that are in A but not in B. So the operation order matters.
 
-### Example
+For example, the following query
 
 ```ngql
 nebula> GO FROM 1 OVER e1 YIELD e1._dst AS id, e1.prop1 AS left_1, $$.tag.prop2 AS left_2
@@ -153,15 +151,15 @@ comes out
 --------------------------
 ```
 
-And if we reverse the `MINUS` order
+And if we reverse the `MINUS` order, the query
 
 ```ngql
 nebula> GO FROM 2,3 OVER e1 YIELD e1._dst AS id, e1.prop1 AS right_1, $$.tag.prop2 AS right_2
 MINUS
 GO FROM 1 OVER e1 YIELD e1._dst AS id, e1.prop1 AS left_1, $$.tag.prop2 AS left_2
 ```
 
-results in
+returns
 
 ```ngql
 ===========================

docs/manual-EN/2.query-language/4.statement-syntax/1.data-definition-statements/alter-tag-edge-syntax.md

@@ -1,8 +1,8 @@
 # Alter Tag/Edge Syntax
 
 ```ngql
-ALTER {TAG | EDGE} tag_name | edge_name
-    [alter_definition [, alter_definition] ...]
+ALTER TAG | EDGE <tag_name> | <edge_name>
+    <alter_definition> [, alter_definition] ...]
     [ttl_definition [, ttl_definition] ... ]
   
 alter_definition:

docs/manual-EN/2.query-language/4.statement-syntax/1.data-definition-statements/drop-edge-syntax.md

@@ -1,7 +1,7 @@
 # Drop Edge Syntax
 
 ```ngql
-DROP EDGE edge_type_name
+DROP EDGE <edge_type_name>
 ```
 
 You must have the DROP privilege for the edge type.

docs/manual-EN/2.query-language/4.statement-syntax/1.data-definition-statements/drop-space-syntax.md

@@ -1,7 +1,7 @@
 # Drop Space Syntax
 
 ```ngql
-DROP SPACE space_name
+DROP SPACE <space_name>
 ```
 
 You must have the DROP privilege for the graph space.

docs/manual-EN/2.query-language/4.statement-syntax/2.data-query-and-manipulation-statements/delete-edge-syntax.md

@@ -1,9 +1,9 @@
 # Delete Edge Syntax
 
-The `DELETE EDGE` statement is used to delete edges. Given an edge type, the source vertex and the dest vertex, **Nebula Graph** supports `DELETE` the edge, its associated properties and the edge ranking. You can also delete an edge with a certain rank. The syntax is as the follows:
+The `DELETE EDGE` statement is used to delete edges. Given an edge type, the source vertex and the dest vertex, **Nebula Graph** supports `DELETE` the edge, its associated properties and the edge ranking. You can also delete an edge with a certain rank. The syntax is as follows:
 
 ```ngql
-DELETE EDGE <edge_type> <vid> -> <vid>@ranking [, <vid> -> <vid> ...]
+DELETE EDGE <edge_type> <vid> -> <vid>[@<ranking>] [, <vid> -> <vid> ...]
 ```
 
 **Nebula Graph** will find the properties associated with the edge and delete all of them. Atomic operation is not guaranteed during the entire process for now, so please retry when failure occurs.