Merge branch 'master' into trace

docs/manual-CN/1.overview/2.quick-start/1.get-started.md

@@ -469,4 +469,4 @@ vesoft/nebula-console:nightly --addr=127.0.0.1 --port=3699
 * 您必须将IP地址和端口号更改为您自己的IP地址和端口号。
 * 您可以下在[这里](https://nebula-graph.oss-accelerate.aliyuncs.com/doc/nba.ngql)载 `nba.ngql` 文件。
 
-同样，您可以在 *data.ngql* 文件中放置数百或数千个 DML（数据操作语言）语句来插入数据。如果您要插入数百万条记录，建议使用 csv 导入工具（或 sst 提取工具）。
+同样，您可以在 *data.ngql* 文件中放置数百或数千个 DML（数据操作语言）语句来插入数据。如果您要插入数百万条记录，建议使用 [csv 导入工具](https://github.com/vesoft-inc/nebula-importer)（或 [sst 提取工具](../../3.build-develop-and-administration/3.deploy-and-administrations/server-administration/storage-service-administration/data-import/download-and-ingest-sst-file.md)）。

docs/manual-CN/1.overview/2.quick-start/2.FAQ.md

@@ -0,0 +1,145 @@
+# 常见问题
+
+本文档列出了 **Nebula Graph** 常见问题。
+
+- [常见问题](#%e5%b8%b8%e8%a7%81%e9%97%ae%e9%a2%98)
+  - [Trouble Shooting](#trouble-shooting)
+    - [graphd 的配置没有注册到 meta server](#graphd-%e7%9a%84%e9%85%8d%e7%bd%ae%e6%b2%a1%e6%9c%89%e6%b3%a8%e5%86%8c%e5%88%b0-meta-server)
+    - [当创建 tag 或者 edge 类型后，插入数据时报错](#%e5%bd%93%e5%88%9b%e5%bb%ba-tag-%e6%88%96%e8%80%85-edge-%e7%b1%bb%e5%9e%8b%e5%90%8e%e6%8f%92%e5%85%a5%e6%95%b0%e6%8d%ae%e6%97%b6%e6%8a%a5%e9%94%99)
+    - [使用 Docker 启动后，执行命令时报错](#%e4%bd%bf%e7%94%a8-docker-%e5%90%af%e5%8a%a8%e5%90%8e%e6%89%a7%e8%a1%8c%e5%91%bd%e4%bb%a4%e6%97%b6%e6%8a%a5%e9%94%99)
+    - [storaged 服务无法正常启动](#storaged-%e6%9c%8d%e5%8a%a1%e6%97%a0%e6%b3%95%e6%ad%a3%e5%b8%b8%e5%90%af%e5%8a%a8)
+    - [Connection Refused](#connection-refused)
+    - [进程异常 crash](#%e8%bf%9b%e7%a8%8b%e5%bc%82%e5%b8%b8-crash)
+    - [未找到日志和更改日志级别](#%e6%9c%aa%e6%89%be%e5%88%b0%e6%97%a5%e5%bf%97%e5%92%8c%e6%9b%b4%e6%94%b9%e6%97%a5%e5%bf%97%e7%ba%a7%e5%88%ab)
+    - [配置文件](#%e9%85%8d%e7%bd%ae%e6%96%87%e4%bb%b6)
+    - [运行时参数](#%e8%bf%90%e8%a1%8c%e6%97%b6%e5%8f%82%e6%95%b0)
+    - [Could not create logging file:... Too many open files](#could-not-create-logging-file-too-many-open-files)
+  - [General Information](#general-information)
+    - [查询返回时间解释](#%e6%9f%a5%e8%af%a2%e8%bf%94%e5%9b%9e%e6%97%b6%e9%97%b4%e8%a7%a3%e9%87%8a)
+
+## Trouble Shooting
+
+Trouble Shooting 部分列出了 **Nebula Graph** 操作中的常见错误。
+
+### graphd 的配置没有注册到 meta server
+
+用 `nebula.service` 脚本启动服务时，`graphd`、 `metad` 和 `storaged` 进程启动速度太快，可能会导致 graphd 的配置没有注册到 meta server。restart 的时候也有此问题。
+
+beta 版本用户可以先启动 metad，再启动 storaged 和 graphd 来避免此问题。我们将在下一个版本解决此问题。
+
+先启动 metad：
+
+```bash
+nebula> scripts/nebula.service start metad
+[INFO] Starting nebula-metad...
+[INFO] Done
+```
+
+再启动 storaged 和 graphd：
+
+```bash
+nebula> scripts/nebula.service start storaged
+[INFO] Starting nebula-storaged...
+[INFO] Done
+nebula> scripts/nebula.service start graphd
+[INFO] Starting nebula-graphd...
+[INFO] Done
+```
+
+### 当创建 tag 或者 edge 类型后，插入数据时报错
+
+可能原因， `load_data_interval_secs` 设置了从 meta server 获取元数据时间间隔。更改方式:
+
+如果 meta 注册过配置，请在 console 中运行以下命令查看参数 `load_data_interval_secs` 的值。
+
+```ngql
+nebula> GET CONFIGS storage:load_data_interval_secs
+nebula> GET CONFIGS graph:load_data_interval_secs
+```
+
+如果值过大，运行以下命令将值更改为 1s
+
+   ```ngql
+   nebula> UPDATE CONFIGS storage:load_data_interval_secs=1
+   nebula> UPDATE CONFIGS graph:load_data_interval_secs=1
+   ```
+
+> 注意，更改不会立即生效，需在下个周期生效。
+
+### 使用 Docker 启动后，执行命令时报错
+
+可能的原因是 Docker 的 IP 地址和默认配置中的监听地址不一致(默认是 172.17.0.2)，因此这里需要修改默认配置中的监听地址。
+
+1. 首先在容器中执行 `ifconfig` 命令，查看您的容器地址，这里假设您的容器地址是172.17.0.3，那么就意味着您需要修改默认配置的IP地址。
+2. 然后进入配置目录(cd /usr/local/nebula/etc), 查找所有IP地址配置的位置(grep "172.17.0.2" . -r)。
+3. 修改上一步查到的所有IP地址为您的容器地址(172.17.0.3)。
+4. 最后重新启动所有服务(/usr/local/nebula/scripts/nebula.service start all)。
+
+### storaged 服务无法正常启动
+
+同一台主机先后用于单机测试和集群测试，storaged 服务无法正常启动（终端上显示的 storaged 服务的监听端口是红色的）。查看 storged 服务的日志(/usr/local/nebula/nebula-storaged.ERROR)，若发现 "wrong cluster" 的报错信息，则可能的出错原因是单机测试和集群测试时的 Nebula Graph 生成的 cluster id 不一致，需要删除 Nebula Graph 安装目录(/usr/local/nebula)下的 cluster.id 文件和 data 目录后，重启服务。
+
+### Connection Refused
+
+```txt
+E1121 04:49:34.563858   256 GraphClient.cpp:54] Thrift rpc call failed: AsyncSocketException: connect failed, type = Socket not open, errno = 111 (Connection refused): Connection refused
+```
+
+检查服务是否存在
+
+```bash
+$ /usr/local/nebula/scripts/nebula.service status all
+```
+
+### 进程异常 crash
+
+1. 检查硬盘空间 `df -h`
+1. 检查内存是否足够 `free -h`
+
+### 未找到日志和更改日志级别
+
+日志文件默认在 `/usr/local/nebula/logs/` 下。
+
+参见[这里](docs/manual-CN/3.build-develop-and-administration/3.deploy-and-administrations/server-administration/configuration-statements/log.md)
+
+### 配置文件
+
+配置文件默认在 `/usr/local/nebula/etc/` 下。
+
+### 运行时参数
+
+在 Nebula console 中运行
+
+```ngql
+nebula> SHOW CONFIGS;
+```
+
+参见[这里](docs/manual-CN/3.build-develop-and-administration/3.deploy-and-administrations/server-administration/configuration-statements/configs-syntax.md)
+
+### `Could not create logging file:... Too many open files`
+
+1. 检查硬盘空间 `df -h`
+1. 检查日志目录 `/usr/local/nebula/logs/`
+1. 修改允许打开的最大文件数 `ulimit -n 65536`
+
+## General Information
+
+General Information 部分列出了关于 **Nebula Graph** 的概念性问题。
+
+### 查询返回时间解释
+
+```ngql
+nebula> GO FROM 101 OVER follow
+===============
+| follow._dst |
+===============
+| 100         |
+---------------
+| 102         |
+---------------
+| 125         |
+---------------
+Got 3 rows (Time spent: 7431/10406 us)
+```
+
+以上述查询为例，Time spent 中前一个数字 `7431` 为数据库本身所花费的时间，即 query engine 从 console 收到这条查询语句，到存储拿到数据，并进行一系列计算所花的时间；后一个数字 `10406` 是从客户端角度看花费的时间，即 console 从发送请求，到收到响应，并将结果输出到屏幕的时间。

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/1.overview/3.design-and-architecture/3.query-engine.md

@@ -0,0 +1,43 @@
+# 查询引擎设计
+
+在 **Nebula Graph** 中，Query Engine 用来处理 **Nebula Graph** 查询语言语句（nGQL）。本篇文章将带你了解 Nebula Query Engine 的架构。
+
+![image](https://user-images.githubusercontent.com/42762957/70886505-9470a100-2016-11ea-8258-047f480a8d4b.png)
+
+上图为查询引擎的架构图，如果你对 SQL 的执行引擎比较熟悉，那么对上图一定不会陌生。**Nebula Graph** 的 Query Engine 架构图和现代 SQL 的执行引擎类似，只是在查询语言解析器和具体的执行计划有所区别。
+
+## Session Manager
+
+**Nebula Graph** 权限管理采用基于角色的权限控制（Role Based Access Control）。客户端第一次连接到 Query Engine 时需作认证，当认证成功之后 Query Engine 会创建一个新 session，并将该 session ID 返回给客户端。所有的 session 统一由 Session Manager 管理。session 会记录当前的 graph space 信息及对该 space 的权限。此外，session 还会记录一些会话相关的配置信息，并临时保存同一 session 内的跨多个请求的一些信息。
+
+客户端连接结束之后 session 会关闭，或者如果长时间没通信会切换为空闲状态。这个空闲时长是可以配置的。
+
+客户端的每次请求都必须带上此 session ID，否则 Query Engine 会拒绝此请求。
+
+Storage Engine 不管理 session，Query Engine 在访问存储引擎时，会带上 session 信息。
+
+## Parser
+
+Query Engine 解析来自客户端的 nGQL 语句，分析器（parser）主要基于著名的 flex / bison 工具集。字典文件（lexicon）和语法规则（syntax）在 **Nebula Graph** 源代码的 `src/parser` 目录下。设计上，nGQL 的语法非常接近 SQL，目的是降低学习成本。
+
+图数据库目前没有统一的查询语言国际标准，一旦 ISO/IEC 的图查询语言（GQL）委员会发布 GQL 国际标准，nGQL 会尽快去实现兼容。
+
+Parser 构建产出的抽象语法树（Abstract Syntax Tree，简称 AST）会交给下一模块：Execution Planner。
+
+## Execution Planner
+
+执行计划器（Execution Planner）负责将抽象树 AST 解析成一系列执行动作 action（可执行计划）。action 为最小可执行单元。例如，典型的 action 可以是获取某个节点的所有邻节点，或者获得某条边的属性，或基于特定过滤条件筛选节点或边。
+
+当抽象树 AST 被转换成执行计划时，所有 ID 信息会被抽取出来以便执行计划的复用。这些 ID 信息会放置在当前请求 context 中，context 也会保存变量和中间结果。
+
+## Optimization
+
+经由 Execution Planner 产生的执行计划会交给优化框架 Optimization Framework。优化框架中注册有多个 Optimizer。Optimizer 会依次被调用对执行计划进行优化，这样每个 Optimizer 都有机会修改（优化）执行计划。
+
+最后，优化过的执行计划可能和原始执行计划完全不一样，但是优化后的执行结果必须和原始执行计划的结果一样。
+
+## Execution
+
+Query Engine 最后一步是去执行优化后的执行计划，这步是执行框架（Execution Framework）完成的。执行层的每个执行器一次只处理一个执行计划，计划中的 action 会依次执行。执行器也会做一些有限的局部优化，比如：决定是否并发执行。
+
+针对不同 action，执行器将通过客户端与 meta service 或 storage engine 进行通信。

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: