update Zone

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

@@ -25,25 +25,43 @@
 
 ![The demo dataset](dataset-for-crud.png)
 
-## 检查 Nebula Graph 集群的机器状态
+## 管理 Nebula Graph 集群的 Storage 节点
+
+首先将 Storage 节点加入 Nebula Graph 集群。更多管理集群命令请参见 [管理集群（Zone）](../4.deployment-and-installation/5.zone.md)。
+
+!!! compatibility
+
+    从 3.0 版本开始，在配置文件中添加的 Storage 节点无法直接读写，配置文件的作用仅仅是将 Storage 节点注册至 Meta 服务中。必须使用`ADD HOSTS`命令后，才能正常读写 Storage 节点。
+
+```ngql
+ADD HOSTS <ip>:<port> [,<ip>:<port> ...] [INTO NEW ZONE "<new_zone_name>"];
+```
+
+示例：
+
+```ngql
+nebula> ADD HOSTS 192.168.10.100:9779, 192.168.10.101:9779, 192.168.10.102:9779;
+```
 
-!!! Note
 
-    首先建议检查机器状态，确保所有的 Storage 服务连接到了 Meta 服务。执行命令`SHOW HOSTS`查看机器状态。
+
+## 检查 Nebula Graph 集群的机器状态
+
+Storage 服务加入集群后，可以执行命令`SHOW HOSTS`查看机器状态。
 
 ```ngql
 nebula> SHOW HOSTS;
-+-------------+-----------+-----------+--------------+----------------------+------------------------+
-| Host        | Port      | Status    | Leader count | Leader distribution  | Partition distribution |
-+-------------+-----------+-----------+--------------+----------------------+------------------------+
-| "storaged0" | 9779      | "ONLINE"  | 0            | "No valid partition" | "No valid partition"   |
-| "storaged1" | 9779      | "ONLINE"  | 0            | "No valid partition" | "No valid partition"   |
-| "storaged2" | 9779      | "ONLINE"  | 0            | "No valid partition" | "No valid partition"   |
-| "Total"     | __EMPTY__ | __EMPTY__ | 0            | __EMPTY__            | __EMPTY__              |
-+-------------+-----------+-----------+--------------+----------------------+------------------------+
++------------------+------+----------+--------------+----------------------+------------------------+
+| Host             | Port | Status   | Leader count | Leader distribution  | Partition distribution |
++------------------+------+----------+--------------+----------------------+------------------------+
+| "192.168.10.100" | 9779 | "ONLINE" | 0            | "No valid partition" | "No valid partition"   |
+| "192.168.10.101" | 9779 | "ONLINE" | 0            | "No valid partition" | "No valid partition"   |
+| "192.168.10.102" | 9779 | "ONLINE" | 0            | "No valid partition" | "No valid partition"   |
+| "Total"          |      |          | 0            |                      |                        |
++------------------+------+----------+--------------+----------------------+------------------------+
 ```
 
-在返回结果中，查看** Status **列，可以看到所有 Storage 服务都在线。
+在返回结果中，查看 **Status** 列，可以看到所有 Storage 服务都在线。
 
 ### 异步实现创建和修改
 
@@ -75,7 +93,11 @@ nebula> SHOW HOSTS;
     [replica_factor = <replica_number>,]
     vid_type = {FIXED_STRING(<N>) | INT64}
     )
+    [ON zone_list]
     [COMMENT = '<comment>'];
+
+    zone_list:
+    "zone_name" [,"zone_name" ...]
     ```
 
     参数详情请参见 [CREATE SPACE](../3.ngql-guide/9.space-statements/1.create-space.md)。

docs-2.0/20.appendix/0.FAQ.md

@@ -73,9 +73,13 @@ Nebula Graph {{ nebula.release }} 的数据模型中，由于设计允许图中
 
 从 Nebula Graph 3.0 开始，查询语句`LOOKUP`、`GO`、`FETCH`必须用`YIELD`子句指定输出结果。详情请参见[YIELD](../3.ngql-guide/8.clauses-and-options/yield.md)。
 
+### 如何处理错误信息 `Zone not enough!`
+
+从 3.0 版本开始，在配置文件中添加的 Storage 节点无法直接读写，配置文件的作用仅仅是将 Storage 节点注册至 Meta 服务中。必须使用`ADD HOSTS`命令后，才能正常读写 Storage 节点。详情参见[管理逻辑机架（Zone）](../4.deployment-and-installation/5.zone.md)。
+
 ### 如何处理错误信息 `To get the property of the vertex in 'v.age', should use the format 'var.tag.prop'`
 
-从 3.0 版本开始，`pattern`支持同时匹配多个 Tag，所以返回属性时，需要额外指定 Tag 名称。即从`RETURN 变量名.属性名`改为`RETURN 变量名.Tag.属性名`。
+从 3.0 版本开始，`pattern`支持同时匹配多个 Tag，所以返回属性时，需要额外指定 Tag 名称。即从`RETURN 变量名.属性名`改为`RETURN 变量名.Tag名.属性名`。
 
 ### 返回消息中 `time spent` 的含义是什么？
 

docs-2.0/3.ngql-guide/9.space-statements/1.create-space.md

@@ -16,8 +16,11 @@ CREATE SPACE [IF NOT EXISTS] <graph_space_name> (
     [replica_factor = <replica_number>,]
     vid_type = {FIXED_STRING(<N>) | INT[64]}
     )
-    [ON <group_name>]
+    [ON zone_list]
     [COMMENT = '<comment>'];
+
+zone_list:
+    "zone_name" [,"zone_name" ...]
 ```
 
 |参数|说明|
@@ -27,7 +30,7 @@ CREATE SPACE [IF NOT EXISTS] <graph_space_name> (
 |`partition_num`|指定图空间的分片数量。建议设置为 5 倍的集群硬盘数量。例如集群中有 3 个硬盘，建议设置 15 个分片。默认值为 100。|
 |`replica_factor`|指定每个分片的副本数量。建议在生产环境中设置为 3，在测试环境中设置为 1。由于需要基于多数表决，副本数量必须是**奇数**。默认值为 1。|
 |`vid_type`|必选参数。指定点 ID 的数据类型。可选值为`FIXED_STRING(<N>)`和`INT64`。`INT`等同于`INT64`。`FIXED_STRING(<N>)`表示数据类型为字符串，最大长度为`N`，超出长度会报错；`INT64`表示数据类型为整数。|
-|`ON <group_name>`|指定图空间所属的 Group。详情请参见 [Group&Zone](../../7.data-security/5.zone.md)。|
+|`zone_list`|指定图空间所属的 Zone 列表，将在这些 Zone 中创建分片和对应副本。副本数量不能超过指定 Zone 数量。不指定`zone_list`时，默认属于所有 Zone。详情请参见 [Zone](../../7.data-security/5.zone.md)。|
 |`COMMENT`|图空间的描述。最大为 256 字节。默认无描述。|
 
 !!! caution
@@ -58,7 +61,7 @@ CREATE SPACE <new_graph_space_name> AS <old_graph_space_name>;
 
 |参数|说明|
 |:---|:---|
-|`<new_graph_space_name>`|目标图空间名称。该图空间必须未创建。图空间名称支持 1~4 字节的 UTF-8 编码字符，包括英文字母（区分大小写）、数字、中文等，但是不包括除下划线外的特殊字符。使用保留关键字时，需要用反引号（\`）包围，详情参见[关键字和保留字](../../3.ngql-guide/1.nGQL-overview/keywords-and-reserved-words.md)。创建时会克隆`<old_graph_space_name>`图空间的 Schema，包括图空间本身参数（分片数量、副本数量等），以及 Tag、Edge type 和原生索引。|
+|`<new_graph_space_name>`|目标图空间名称。该图空间必须未创建。图空间名称支持 1~4 字节的 UTF-8 编码字符，包括英文字母（区分大小写）、数字、中文等，但是不包括除下划线外的特殊字符。使用保留关键字时，需要用反引号（\`）包围，详情参见[关键字和保留字](../../3.ngql-guide/1.nGQL-overview/keywords-and-reserved-words.md)。创建时会克隆`<old_graph_space_name>`图空间的 Schema，包括图空间本身参数（分片数量、副本数量等）、Tag、Edge type、原生索引和 Zone。|
 |`<old_graph_space_name>`|原始图空间名称。该图空间必须已存在。|
 
 ## 示例

docs-2.0/4.deployment-and-installation/5.zone.md

@@ -0,0 +1,147 @@
+# 管理逻辑机架（Zone）
+
+Nebula Graph 提供 Zone 功能，可以管理集群中的 Storage 节点，实现资源隔离。
+
+## 背景信息
+
+!!! compatibility
+
+    从 3.0 版本开始，在配置文件中添加的 Storage 节点无法直接读写，配置文件的作用仅仅是将 Storage 节点注册至 Meta 服务中。必须使用`ADD HOSTS`命令后，才能正常读写 Storage 节点。
+
+用户可以将 Storage 节点加入某个 Zone 中，创建图空间时指定 Zone，就会在 Zone 内的 Storage 节点上创建及存储图空间。分片及其副本会均匀存储在各个 Zone 中。如下图所示。
+
+![Zone 示意图](zone.png)
+
+6 台启动 Storage 服务的机器两两组合，加入 3 个 Zone。指定这三个 Zone 创建图空间 S1，分片及其副本会均匀存储在 Zone1~Zone3。
+
+## 适用场景
+
+- 期望将图空间创建在某些指定的 Storage 节点上，从而达到资源隔离的目的。
+
+- 集群滚动升级。需要停止一个或多个服务器并更新，然后重新投入使用，直到集群中所有的节点都更新为新版本。
+
+## 基本语法
+
+### ADD HOSTS...INTO NEW ZONE
+
+将 Storage 节点加入新建 Zone。
+
+```ngql
+ADD HOSTS <ip>:<port> [,<ip>:<port> ...] [INTO NEW ZONE "<new_zone_name>"];
+```
+
+示例：
+
+```ngql
+nebula> ADD HOSTS 192.168.10.100:9779, 192.168.10.101:9779, 192.168.10.102:9779;
+```
+
+未使用`INTO NEW ZONE "<new_zone_name>"`时，每个 Storage 节点会默认自动创建并加入名称格式为`default_zone_<host>_<port>`的独立 Zone 中。
+
+```ngql
+nebula> SHOW ZONES;
++------------------------------------+------------------+------+
+| Name                               | Host             | Port |
++------------------------------------+------------------+------+
+| "default_zone_192.168.10.100_9779" | "192.168.10.100" | 9779 |
+| "default_zone_192.168.10.101_9779" | "192.168.10.101" | 9779 |
+| "default_zone_192.168.10.102_9779" | "192.168.10.102" | 9779 |
++------------------------------------+------------------+------+
+```
+
+### ADD HOSTS...INTO ZONE
+
+将 Storage 节点加入已创建的 Zone。
+
+!!! note
+
+    加入之后请使用 [BALANCE DATA](../3.ngql-guide/18.operation-and-maintenance-statements/2.balance-syntax.md) 命令实现负载均衡。
+
+```ngql
+ADD HOSTS <ip>:<port> [,<ip>:<port> ...] INTO ZONE "<zone_name>";
+```
+
+### DROP HOSTS
+
+从集群中删除 Storage 节点。
+
+!!! note
+
+    无法直接删除正在使用的 Storage 节点，需要先删除关联的图空间，才能删除 Storage 节点。
+
+```ngql
+DROP HOSTS <ip>:<port> [,<ip>:<port> ...];
+```
+
+### SHOW ZONES
+
+查看所有 Zone。
+
+```ngql
+SHOW ZONES;
+```
+
+### DESC ZONE
+
+查看指定 Zone。
+
+```ngql
+DESCRIBE ZONE "<zone_name>";
+DESC ZONE "<zone_name>";
+```
+
+### RENAME ZONE
+
+重命名 Zone。
+
+```ngql
+RENAME ZONE "<old_name>" TO "<new_name>";
+```
+
+### DROP ZONE
+
+删除 Zone。
+
+!!! note
+
+    Zone 中没有分片时，才可以删除该 Zone。
+
+```ngql
+DROP ZONE "<zone_name>";
+```
+
+### MERGE ZONE...INTO
+
+将多个 Zone 中的 Storage 节点合并至新建 Zone。
+
+!!! note
+
+    合并时将检查所有图空间分片的分布情况，防止同一个分片的不同副本因为合并导致分布在同一个 Zone 中。
+
+```ngql
+MERGE ZONE "<zone_name>" [,"<zone_name>" ...] INTO "<new_zone_name>";
+```
+
+示例：
+
+```ngql
+MERGE ZONE "default_zone_192.168.10.100_9779","default_zone_192.168.10.101_9779","default_zone_192.168.10.102_9779" INTO "merge_zone";
+```
+
+### DIVIDE ZONE
+
+将一个 Zone 中的所有 Storage 节点分离至多个新建 Zone。
+
+!!! note
+
+    分离之后请使用 [BALANCE DATA](../3.ngql-guide/18.operation-and-maintenance-statements/2.balance-syntax.md) 命令实现负载均衡。
+
+```ngql
+DIVIDE ZONE "<zone_name>" INTO "<new_zone_name>"(<ip>:<port>) ["<new_zone_name>"(<ip>:<port>) ...];
+```
+
+示例：
+
+```ngql
+DIVIDE ZONE "merge_zone" INTO "zone1"(192.168.10.100:9779) "zone2"(192.168.10.101:9779) "zone3"(192.168.10.102:9779);
+```