vesoft-inc · whitewum · Sep 6, 2021 · Aug 19, 2021 · Aug 19, 2021 · Aug 19, 2021
diff --git a/docs-2.0/1.introduction/3.nebula-graph-architecture/4.storage-service.md b/docs-2.0/1.introduction/3.nebula-graph-architecture/4.storage-service.md
@@ -118,7 +118,7 @@ Nebula Graph使用强类型Schema。
 
 ## 数据分片
 
-由于超大规模关系网络的节点数量高达百亿到千亿，而边的数量更会高达万亿，即使仅存储点和边两者也远大于一般服务器的容量。因此需要有方法将图元素切割，并存储在不同逻辑分片（Partition）上。Nebula Graph 采用边分割的方式
+由于超大规模关系网络的节点数量高达百亿到千亿，而边的数量更会高达万亿，即使仅存储点和边两者也远大于一般服务器的容量。因此需要有方法将图元素切割，并存储在不同逻辑分片（Partition）上。Nebula Graph 采用边分割的方式。
 
 ![data partitioning](https://www-cdn.nebula-graph.com.cn/nebula-blog/DataModel02.png)
 

diff --git a/docs-2.0/1.introduction/3.vid.md b/docs-2.0/1.introduction/3.vid.md
@@ -42,8 +42,24 @@ VID的生成工作完全交给应用端，有一些通用的建议：
 
 - 如果个别记录的主键特别长，但绝大多数记录的主键都很短的情况，不要将`FIXED_STRING(<N>)`的`N`设置成超大，这会浪费大量内存和硬盘，也会降低性能。此时可通过BASE64，MD5，hash编码加拼接的方式来生成。
 
-- 如果用hash方式生成int64 VID，在有10亿个点的情况下，发生碰撞的概率大约是1/10。边的数量与碰撞的概率无关。
+- 如果用hash方式生成int64 VID：在有10亿个点的情况下，发生hash冲突的概率大约是1/10。边的数量与碰撞的概率无关。
 
 ## 定义和修改VID的数据类型
 
 VID的数据类型必须在[创建图空间](../3.ngql-guide/9.space-statements/1.create-space.md)时定义，且一旦定义无法修改。
+
+## "查询起始点"(`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`；
+
+
+!!! caution 不能在没有 `start vid` 情况下进行全局扫描；
+
+    例如 `match (n) return n;` 会返回错误，因为此时无法定位到 `start vid`；这是一个全局扫描，因此被禁止。
+
diff --git a/docs-2.0/20.appendix/0.FAQ.md b/docs-2.0/20.appendix/0.FAQ.md
@@ -32,25 +32,41 @@ Nebula Graph一直在持续开发，功能或操作的行为可能会有变化
 
 ## 关于执行
 
-### 使用GO和MATCH执行相同语义的查询，查询结果为什么不同？
+### 关于悬挂边
 
-路径的类型不同，导致查询结果可能会不同。
+悬挂边 (Dangling edge) 是指一条边的起点或者终点在数据库中不存在。
 
-- `GO`语句采用的是`walk`类型，遍历时点和边可以重复。
+Nebula Graph {{ nebula.release }} 的数据模型中，允许存在"悬挂边"；也没有 openCypher 中的 MERGE 语句。对于悬挂边的保证完全依赖应用层面。详见[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)。
 
-- `MATCH`语句兼容openCypher，采用的是`trail`类型，遍历时只有点可以重复，边不可以重复。
-
-例如下图。
 
-![路径示例](../images/path1.png)
+### 如何处理错误信息 `[ERROR (-1005)]: Used memory hits the high watermark(0.800000) of total system memory.`
 
-从点A开始查询距离5跳的点，都会查询到点C（`A->B->C->D->E->C`），查询6跳的点时，`GO`语句会查询到点D（`A->B->C->D->E->C->D`），因为边`C->D`可以重复查询，而`MATCH`语句查询为空，因为边不可以重复。
+报错原因：Nebula Graph的`system_memory_high_watermark_ratio`参数指定了内存高水位报警机制的触发阈值，默认为`0.8`。系统内存占用率高于该值会触发报警机制，Nebula Graph会停止接受查询。
 
-所以使用`GO`和`MATCH`执行相同语义的查询，可能会出现`MATCH`语句的查询结果比`GO`语句少。
+解决方案：
 
-关于路径的详细说明，请参见[维基百科](https://en.wikipedia.org/wiki/Path_(graph_theory)#Walk,_trail,_path)。
+* 清理系统内存，使其降低到阈值以下。
+* [修改Graph配置](../5.configurations-and-logs/1.configurations/1.configurations.md)。在所有Graph服务器的配置文件中增加`system_memory_high_watermark_ratio`参数，为其设置一个大于`0.8`的值，例如`0.9`。
+
+  !!! note
 
-### 返回消息中`time spent`的含义是什么？
+        仅Graph服务支持`system_memory_high_watermark_ratio`，Storage和Meta服务不支持该参数。
+
+### 如何处理错误信息 `Storage Error E_RPC_FAILURE`
+
+报错原因通常为Graph服务向Storage服务请求了过多的数据，导致Storage服务超时。请尝试以下解决方案：
+
+* [修改配置文件](../5.configurations-and-logs/1.configurations/3.graph-config.md): 在`nebula-graphd.conf`文件中修改`--storage_client_timeout_ms`参数的值，以增加Storage client的连接超时时间。该值的单位为毫秒（ms）。例如，设置`--storage_client_timeout_ms=60000`。如果`nebula-graphd.conf`文件中未配置该参数，请手动增加。提示：请在配置文件开头添加--local_config=true再重启服务。
+* 优化查询语句：减少全库扫描型的查询，无论是否用`LIMIT`限制了返回结果的数量；用 GO 语句改写 MATCH 语句（前者有优化，后者无优化）。
+* 检查Storaged是否发生的 OOM。(`dmesg |grep nebula`)。
+* 为 Storage 服务器提供性能更好的SSD或者内存。
+* 重试请求。
+
+### 如何处理错误信息 `The leader has changed. Try again later`
+
+已知问题，通常需要重试 1-N 次(N==partition数量)。原因为 meta client 更新leader缓存需要1-2个心跳或者通过错误触发强制更新。
+
+### 返回消息中 `time spent` 的含义是什么？
 
 将命令`SHOW SPACES`返回的消息作为示例：
 
@@ -72,14 +88,38 @@ Got 1 rows (time spent 1235/1934 us)
 
 不要这样设置。
 
-Storage服务使用Raft协议（多数表决），为保证可用性，要求出故障的副本数量不能达到一半。
+Storage 服务使用 Raft 协议（多数表决），为保证可用性，要求出故障的副本数量不能达到一半。
 
 当机器数量为1时，`replica_factor`只能设置为`1`。
 
 当机器数量足够时，如果`replica_factor=2`，当其中一个副本故障时，就会导致系统无法正常工作；如果`replica_factor=4`，只能有一个副本可以出现故障，这和`replica_factor=3`是一样。以此类推，所以`replica_factor`设置为奇数即可。
 
 建议在生产环境中设置`replica_factor=3`，测试环境中设置`replica_factor=1`，不要使用偶数。
 
+### 是否支持停止或者中断慢查询
+
+支持。
+
+详情请参见[终止查询](../3.ngql-guide/18.operation-and-maintenance-statements/6.kill-query.md)。
+
+### 使用`GO`和`MATCH`执行相同语义的查询，查询结果为什么不同？
+
+路径的类型不同，导致查询结果可能会不同。
+
+- `GO`语句采用的是`walk`类型，遍历时点和边可以重复。
+
+- `MATCH`语句兼容openCypher，采用的是`trail`类型，遍历时只有点可以重复，边不可以重复。
+
+例如下图。
+
+![路径示例](../images/path1.png)
+
+从点A开始查询距离5跳的点，都会查询到点C（`A->B->C->D->E->C`），查询6跳的点时，`GO`语句会查询到点D（`A->B->C->D->E->C->D`），因为边`C->D`可以重复查询，而`MATCH`语句查询为空，因为边不可以重复。
+
+所以使用`GO`和`MATCH`执行相同语义的查询，可能会出现`MATCH`语句的查询结果比`GO`语句少。
+
+关于路径的详细说明，请参见[维基百科](https://en.wikipedia.org/wiki/Path_(graph_theory)#Walk,_trail,_path)。
+
 ### 如何处理错误信息`[ERROR (-7)]: SyntaxError: syntax error near`？
 
 大部分情况下，查询语句需要有`YIELD`或`RETURN`，请检查查询语句是否包含。
@@ -137,7 +177,7 @@ Storage服务使用Raft协议（多数表决），为保证可用性，要求出
 
 检查输入的VID是否超过限制长度。详情请参见[create space](../3.ngql-guide/9.space-statements/1.create-space.md)。
 
-### 如何处理错误信息`edge conflict`或`vertex conflict`
+### 如何处理错误信息 `edge conflict` 或 `vertex conflict`
 
 Storage服务在毫秒级时间内多次收到插入或者更新同一点或边的请求时，可能返回该错误。请稍后重试。
 
@@ -160,13 +200,13 @@ Storage服务在毫秒级时间内多次收到插入或者更新同一点或边
 
 报错原因通常为metad服务状态异常，或是metad和graphd服务所在机器网络不通。请尝试以下解决方案：
 
-- 在metad所在服务器查看下metad服务状态，如果服务状态异常，可以重新启动metad服务。
+- 在metad所在服务器查看下 metad 服务状态，如果服务状态异常，可以重新启动metad服务。
 
 - 在报错服务器下使用`telnet meta-ip:port`查看网络状态。
 
 - 检查配置文件中的端口配置，如果端口号与连接时使用的不同，改用配置文件中的端口或者修改配置。
 
-### 如何处理`nebula-graph.INFO`错误日志`StorageClientBase.inl:214] Request to "x.x.x.x":9779 failed: N6apache6thrift9transport19TTransportExceptionE: Timed Out`
+### 如何处理 `nebula-graph.INFO` 中错误日志 `StorageClientBase.inl:214] Request to "x.x.x.x":9779 failed: N6apache6thrift9transport19TTransportExceptionE: Timed Out`
 
 报错原因可能是查询的数据量比较大，storaged 处理超时。请尝试以下解决方法：
 
@@ -175,19 +215,17 @@ Storage服务在毫秒级时间内多次收到插入或者更新同一点或边
 - 增加Graph服务与Storage服务的RPC连接超时时间，在`nebula-storaged.conf`文件里面修改`--storage_client_timeout_ms`参数的值。该值的单位为毫秒（ms），默认值为60000毫秒。
 <!--提示：请在配置文件开头添加--local_config=true再重启服务。-->
 
-### 如何处理`nebula-storaged.INFO`错误日志`MetaClient.cpp:65] Heartbeat failed, status:Wrong cluster!`或者 `nebula-metad.INFO`含有错误日志`HBProcessor.cpp:54] Reject wrong cluster host "x.x.x.x":9771!`
+### 如何处理 `nebula-storaged.INFO` 中错误日志 `MetaClient.cpp:65] Heartbeat failed, status:Wrong cluster!` 或者 `nebula-metad.INFO` 含有错误日志`HBProcessor.cpp:54] Reject wrong cluster host "x.x.x.x":9771!`
 
 报错的原因可能是用户修改了 metad 的 ip 或者端口信息，或者 storage 之前加入过其他集群。请尝试以下解决方法：
 
 用户到storage部署的机器所在的安装目录（默认安装目录为 `/usr/local/nebula`）下面将`cluster.id`文件删除，然后重启 storaged 服务。
 
-### 是否支持停止或者中断慢查询
-
-支持。详情请参见[终止查询](../3.ngql-guide/18.operation-and-maintenance-statements/6.kill-query.md)。
-
 ### 能不能用中文字符做标识符，比如图空间、Tag、Edge type、属性、索引的名称？
 
-不能。图空间、Tag、Edge type、属性以及索引的名称都需由大小写英文字母、数字或下划线组成，暂不支持使用中文字符。
+不能。
+
+图空间、Tag、Edge type、属性以及索引的名称都需由大小写英文字母、数字或下划线组成，暂不支持使用中文字符。
 
 同时，上述标识符区分大小写，且不可使用[关键字和保留字](../3.ngql-guide/1.nGQL-overview/keywords-and-reserved-words.md) 。
 
@@ -200,22 +238,11 @@ nebula > MATCH (s)-[e]->() WHERE id(s) == "given" RETURN count(e); #出度
 nebula > MATCH (s)<-[e]-() WHERE id(s) == "given" RETURN count(e); #入度
 ```
 
-### 是否有办法快速获取所有点的出度和入度？
+### 是否有办法快速获取“所有”点的出度和入度？
 
-没有直接命令。可以使用 [Nebula Algorithm](../nebula-algorithm.md)。
+没有直接命令。
 
-### 如何处理错误信息`[ERROR (-1005)]: Used memory hits the high watermark(0.800000) of total system memory.`
-
-报错原因：Nebula Graph的`system_memory_high_watermark_ratio`参数指定了内存高水位报警机制的触发阈值，默认为`0.8`。系统内存占用率高于该值会触发报警机制，Nebula Graph会停止接受查询。
-
-解决方案：
-
-* 清理系统内存，使其降低到阈值以下。
-* [修改Graph配置](../5.configurations-and-logs/1.configurations/1.configurations.md)。在所有Graph服务器的配置文件中增加`system_memory_high_watermark_ratio`参数，为其设置一个大于`0.8`的值，例如`0.9`。
-
-  !!! note
-
-        仅Graph服务支持`system_memory_high_watermark_ratio`，Storage和Meta服务不支持该参数。
+可以使用 [Nebula Algorithm](../nebula-algorithm.md)。
 
 ### [ERROR (-1005)]: Schema not exist: xxx
 
@@ -225,12 +252,6 @@ nebula > MATCH (s)<-[e]-() WHERE id(s) == "given" RETURN count(e); #入度
 
 - Tag或Edge type的名称是否为关键字，如果是关键字，请使用反引号（\`）将它们括起来。详情请参见[关键字](../3.ngql-guide/1.nGQL-overview/keywords-and-reserved-words.md)。
 
-### 关于悬挂边
-
-悬挂边 (Dangling edge) 是指一条边的起点或者终点在数据库中不存在。
-
-Nebula Graph {{ nebula.release }} 的数据模型中，允许存在"悬挂边"；也没有 openCypher 中的 MERGE 语句。对于悬挂边的保证完全依赖应用层面。详见[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)。
-
 ## 关于运维
 
 ### 日志文件过大时如何回收日志？
@@ -241,7 +262,9 @@ Nebula Graph使用 [glog](https://github.com/google/glog) 打印日志。glog
 
 ### 如何查看Nebula Graph版本
 
-安装方式不同，查看版本的方法也不同，说明如下：
+服务运行时: `nebula-console` 中执行命令 `SHOW HOSTS META`，详见[SHOW HOSTS](../3.ngql-guide/7.general-query-statements/6.show/6.show-hosts.md)
+
+服务未运行时:
 
 - 编译安装
 
@@ -287,9 +310,9 @@ Nebula Graph {{ nebula.release }} 未提供运维命令以实现自动扩缩容
 
 storaged扩缩容之后，还需要运行[Balance Data 和 Balance Leader 命令](../8.service-tuning/load-balance.md)。
 
-### 修改Host名称后，旧的Host一直显示`OFFLINE`怎么办？
+### 修改Host名称后，旧的Host一直显示 `OFFLINE` 怎么办？
 
-`OFFLINE`状态的Host将在一天后自动删除。
+`OFFLINE` 状态的 Host 将在一天后自动删除。
 
 ## 关于连接
 
@@ -305,6 +328,8 @@ storaged扩缩容之后，还需要运行[Balance Data 和 Balance Leader 命令
 
 如果修改过配置文件中预设的端口，请找出实际使用的端口并在防火墙中开放它们。
 
+周边工具各自使用不用的端口，请参考各工具文档。
+
 ### 如何测试端口是否已开放
 
 用户可以使用如下telnet命令检查端口状态：

diff --git a/docs-2.0/20.appendix/6.eco-tool-version.md b/docs-2.0/20.appendix/6.eco-tool-version.md
@@ -163,3 +163,4 @@ Docker Compose可以快速部署Nebula Graph集群。如何使用请参见[Docke
 
   - [Chaos Test](https://github.com/vesoft-inc/nebula-chaos)
 
+- Backup & Restore
diff --git a/docs-2.0/20.appendix/write-tools.md b/docs-2.0/20.appendix/write-tools.md
@@ -6,7 +6,7 @@
 - 使用 [studio 导入](../nebula-studio/quick-start/st-ug-import-data.md): 可以用过浏览器导入本机多个 csv 文件，单个文件不超过 100 MB，格式有限制； 
 - 使用 [importer 导入](../nebula-importer/use-importer.md): 导入单机多个 csv 文件，大小没有限制，格式灵活；
 - 使用 [Exchange 导入](../nebula-exchange/about-exchange/ex-ug-what-is-exchange.md): 从 Neo4j, Hive, MySQL等多种源分布式导入，需要有 Spark 集群；
-- 使用 [Spark-connector](../spark-connector/sc-ug-what-is-spark-connector.md)/[Flink-connector](../nebula-flink/nf-ug-what-is-flink-connector.md) 导入：有相应组件(Spark/Flink)，撰写少量代码；
+- 使用 [Spark-connector](../nebula-spark-connector.md)/[Flink-connector](../nebula-flink-connector.md) 导入：有相应组件(Spark/Flink)，撰写少量代码；
 - 使用 [C++/GO/Java/Python SDK](../20.appendix/6.eco-tool-version.md)：编写程序的方式导入，需要有一定编程和调优能力。
 
 下图给出了几种方式的定位：

diff --git a/docs-2.0/3.ngql-guide/12.vertex-statements/1.insert-vertex.md b/docs-2.0/3.ngql-guide/12.vertex-statements/1.insert-vertex.md
@@ -23,8 +23,8 @@ prop_value_list:
 
   !!! Note
 
-        - `IF NOT EXISTS` 仅检测 VID + Tag 的值是否相同，不会检测属性值。
-        - `IF NOT EXISTS` 会先读取一次数据是否存在，因此对性能会有明显影响。
+      - `IF NOT EXISTS` 仅检测 VID + Tag 的值是否相同，不会检测属性值。
+      - `IF NOT EXISTS` 会先读取一次数据是否存在，因此对性能会有明显影响。
 
 - `tag_name`：点关联的Tag（点类型）。Tag必须提前创建，详情请参见[CREATE TAG](../10.tag-statements/1.create-tag.md)。
 

diff --git a/docs-2.0/4.deployment-and-installation/1.resource-preparations.md b/docs-2.0/4.deployment-and-installation/1.resource-preparations.md
@@ -147,7 +147,7 @@
       // 安装GCC。安装到opt目录需要写权限，用户也可以修改为其他目录。
       $ ./third-party/install-gcc.sh --prefix=/opt
 
-      // 启用GCC。
+      // 启用 GCC。
       $ source /opt/vesoft/toolset/gcc/7.5.0/enable
       ```
 

diff --git a/...yment-and-installation/3.upgrade-nebula-graph/upgrade-nebula-from-200-to-250.md b/...yment-and-installation/3.upgrade-nebula-graph/upgrade-nebula-from-200-to-250.md
@@ -23,7 +23,7 @@ Nebula Graph v2.0.x升级至v{{nebula.release}}，只需要使用v{{nebula.relea
       若安装时指定路径，那么升级时也需要指定路径
 
       ```bash
-      $ sudo rpm  -Uivh --prefix=<installation_path> <package_name> 
+      $ sudo rpm  -Uvh --prefix=<installation_path> <package_name> 
       ```
    - DEB包
 

diff --git a/....0/4.deployment-and-installation/6.deploy-text-based-index/3.deploy-listener.md b/....0/4.deployment-and-installation/6.deploy-text-based-index/3.deploy-listener.md
@@ -74,9 +74,9 @@ ADD LISTENER ELASTICSEARCH <listener_ip:port> [,<listener_ip:port>, ...]
 
     请在一个语句里完整地添加所有 listener。例如：
 
-```ngql
-nebula> ADD LISTENER ELASTICSEARCH 192.168.8.5:9789,192.168.8.6:9789;
-```
+    ```ngql
+    nebula> ADD LISTENER ELASTICSEARCH 192.168.8.5:9789,192.168.8.6:9789;
+    ```
 
 ## 查看 listener
 

diff --git a/docs-2.0/5.configurations-and-logs/1.configurations/1.configurations.md b/docs-2.0/5.configurations-and-logs/1.configurations/1.configurations.md
@@ -2,6 +2,10 @@
 
 Nebula Graph基于[gflags](https://gflags.github.io/gflags/)库打造了系统配置，多数配置项都是其中的flags。Nebula Graph服务启动时，默认会从[配置文件](#_4)中获取配置信息，文件中没有的配置项应用默认值。
 
+!!! enterpriseonly
+
+    性能、参数、查询语句的调优方式及服务。
+
 !!! note
 
     * 由于配置项数多且可能随着Nebula Graph的开发发生变化，文档不会介绍所有配置项。按下文说明可在命令行获取配置项的详细说明。

diff --git a/docs-2.0/5.configurations-and-logs/1.configurations/3.graph-config.md b/docs-2.0/5.configurations-and-logs/1.configurations/3.graph-config.md
@@ -25,7 +25,7 @@ Graph服务提供了两份初始配置文件`nebula-graphd.conf.default`和`nebu
 | `pid_file`        | `pids/nebula-graphd.pid`| 记录进程ID的文件。   |
 |`enable_optimizer` |`true`                   | 是否启用优化器。|
 | `system_memory_high_watermark_ratio` | - |内存高水位报警机制的触发阈值，默认为`0.8`。系统内存占用率高于该值会触发报警机制，Nebula Graph会停止接受查询。初始配置文件中未设置该参数，使用需手动添加。|
-| `timezone_name` | - | 指定Nebula Graph的时区。初始配置文件中未设置该参数，使用需手动添加。系统默认值为`UTC+00:00:00`。格式请参见[Specifying the Time Zone with TZ](https://www.gnu.org/software/libc/manual/html_node/TZ-Variable.html "Click to view the timezone-related content in the GNU C Library manual")。例如，东八区的设置方式为`--timezone_name=CST-8`。 |
+| `timezone_name` | - | 指定Nebula Graph的时区。初始配置文件中未设置该参数，使用需手动添加。系统默认值为`UTC+00:00:00`。格式请参见[Specifying the Time Zone with TZ](https://www.gnu.org/software/libc/manual/html_node/TZ-Variable.html "Click to view the timezone-related content in the GNU C Library manual")。例如，东八区的设置方式为`--timezone_name=UTC+08:00`。 |
 | `local_config` | `true` | 是否从配置文件获取配置信息。 |
 
 !!! Note
Original file line number	Diff line number	Diff line change
Expand Up		@@ -163,3 +163,4 @@ Docker Compose可以快速部署Nebula Graph集群。如何使用请参见[Docke

		- [Chaos Test](https://github.com/vesoft-inc/nebula-chaos)

		- Backup & Restore
-Original file line number
+Diff line change
@@ Expand Up @@
           若安装时指定路径，那么升级时也需要指定路径
           ```bash
-          $ sudo rpm  -Uivh --prefix=<installation_path> <package_name>
+          $ sudo rpm  -Uvh --prefix=<installation_path> <package_name>
           ```
        - DEB包
@@ Expand Down @@