add note

updates after zone function redesign
vesoft-inc · Sep 8, 2023 · e6904e8 · e6904e8
1 parent 67e2551
commit e6904e8
Show file tree

Hide file tree

Showing 8 changed files with 109 additions and 224 deletions.
diff --git a/docs-2.0/3.ngql-guide/4.job-statements.md b/docs-2.0/3.ngql-guide/4.job-statements.md
@@ -48,11 +48,13 @@ nebula> SUBMIT JOB BALANCE DATA REMOVE 192.168.8.100:9779;
 +------------+
 ```
 
-## SUBMIT JOB BALANCE IN ZONE [REMOVE]
+## SUBMIT JOB BALANCE DATA IN ZONE [<zone_name>] [REMOVE]
 
-`SUBMIT JOB BALANCE IN ZONE`语句会启动一个任务在当前图空间中的所有 Zone 内部均衡分布分片副本。该命令会返回任务 ID。
+`SUBMIT JOB BALANCE DATA IN ZONE`语句会启动一个任务在当前图空间中的所有 Zone 内部均衡分布分片副本。如果只在指定的 Zone 内均衡分布分片副本，需要添加`<zone_name>`选项。
 
-`SUBMIT JOB BALANCE IN ZONE REMOVE`语句会启动一个任务清空当前图空间的 Zone 内指定的 Storage 节点。清空 Storage 节点前，需要确保 Zone 内剩余 Storage 节点数量可以满足设置的副本数。例如，如果设置了副本数为 3，那么在执行该命令前，需要确保剩余 Storage 节点数量大于等于 3。
+`SUBMIT JOB BALANCE DATA IN ZONE REMOVE`语句会启动一个任务清空当前图空间的 Zone 内指定的 Storage 节点。清空 Storage 节点前，需要确保 Zone 内剩余 Storage 节点数量可以满足设置的副本数。例如，如果设置了副本数为 3，那么在执行该命令前，需要确保剩余 Storage 节点数量大于等于 3。
+
+关于 Zone 的详情，请参见[管理 Zone](../4.deployment-and-installation/5.zone.md)。
 
 示例：
 
@@ -76,8 +78,6 @@ nebula> SUBMIT JOB BALANCE IN ZONE REMOVE 192.168.10.102:9779;
 +------------+
 ```
 
-关于 Zone 的详情，请参见[管理 Zone](../4.deployment-and-installation/5.zone.md)。
-
 
 {{ ent.ent_end }}
 

diff --git a/docs-2.0/3.ngql-guide/9.space-statements/1.create-space.md b/docs-2.0/3.ngql-guide/9.space-statements/1.create-space.md
@@ -10,7 +10,6 @@
 
 ### 创建图空间
 
-{{comm.comm_begin}}
 
 ```ngql
 CREATE SPACE [IF NOT EXISTS] <graph_space_name> (
@@ -30,33 +29,6 @@ CREATE SPACE [IF NOT EXISTS] <graph_space_name> (
 |`vid_type`|必选参数。指定点 ID 的数据类型。可选值为`FIXED_STRING(<N>)`和`INT64`。`INT`等同于`INT64`。<br>`FIXED_STRING(<N>)`表示数据类型为定长字符串，长度为`N`字节，超出长度会报错。例如，UTF-8中，一个中文字符的长度为三个字节，如果设置`N`为 12，那么`vid_type`为最多 4 个中文字符。<br>`INT64`表示数据类型为整数。|
 |`COMMENT`|图空间的描述。最大为 256 字节。默认无描述。|
 
-{{comm.comm_end}}
-
-{{ent.ent_begin}}
-
-```ngql
-CREATE SPACE [IF NOT EXISTS] <graph_space_name> (
- [partition_num = <partition_number>,]
- [replica_factor = <replica_number>,]
- vid_type = {FIXED_STRING(<N>) | INT[64]}
- )
- [COMMENT = '<comment>']
- [ON <zone_list>'];
-```
-
-|参数|说明|
-|:---|:---|
-|`IF NOT EXISTS`|检测待创建的图空间是否存在，只有不存在时，才会创建图空间。仅检测图空间的名称，不会检测具体属性。|
-|`<graph_space_name>`|1、在{{nebula.name}}实例中唯一标识一个图空间。<br/>2、图空间名称设置后无法被修改。<br/>3、不能以数字开头；支持 1~4 字节的 UTF-8 编码字符，包括英文字母（区分大小写）、数字、中文等，但是不包括除下划线外的特殊字符；使用特殊字符、保留关键字或数字开头时，需要用反引号（\`）包围且不能使用英文句号（`.`）。详情参见[关键字和保留字](../../3.ngql-guide/1.nGQL-overview/keywords-and-reserved-words.md)。<br/>**注意**：如果以中文为图空间命名，报`SyntaxError`错误时，需使用反引号（\`）包围中文字符。|
-|`partition_num`|指定图空间的分片数量。建议设置为集群中硬盘数量的 20 倍（HDD 硬盘建议为 2 倍）。例如集群中有 3 个硬盘，建议设置 60 个分片。默认值为 10。|
-|`replica_factor`|指定每个分片的副本数量。建议在生产环境中设置为 3，在测试环境中设置为 1。由于需要基于多数表决，副本数量必须是**奇数**。默认值为 1。|
-|`vid_type`|必选参数。指定点 ID 的数据类型。可选值为`FIXED_STRING(<N>)`和`INT64`。`INT`等同于`INT64`。<br>`FIXED_STRING(<N>)`表示数据类型为定长字符串，长度为`N`字节，超出长度会报错。例如，UTF-8中，一个中文字符的长度为三个字节，如果设置`N`为 12，那么`vid_type`为最多 4 个中文字符。<br>`INT64`表示数据类型为整数。|
-|`COMMENT`|图空间的描述。最大为 256 字节。默认无描述。|
-|`zone_list`|指定图空间所属的 Zone 列表，分片副本将分布在这些 Zone 中。副本数量不能超过指定 Zone 数量。不指定`zone_list`时，分片副本默认分布在所有 Zone 中。详情请参见 [管理 Zone](../../4.deployment-and-installation/5.zone.md)。|
-
-{{ent.ent_end}}
-
-
 !!! caution
 
  - 如果将副本数设置为 1，用户将无法使用 [SUBMIT JOB BALANCE](../../8.service-tuning/load-balance.md) 命令为{{nebula.name}}的存储服务平衡负载或扩容。
@@ -83,6 +55,18 @@ CREATE SPACE [IF NOT EXISTS] <graph_space_name> (
 
  `graph_space_name`, `partition_num`, `replica_factor`, `vid_type`, `comment` 设置后就无法改变。除非 [`DROP SPACE`](./5.drop-space.md)，并重新`CREATE SPACE`。
 
+
+{{ent.ent_begin}}
+
+创建图空间时，系统会自动识别 Meta 配置文件中`--zone_list`的值，即是否开启 Zone 功能：
+
+ - 如果值为空，代表不开启 Zone 功能，此时创建图空间时，不会指定图空间的 Zone。
+ - 如果值不为空，且`--zone_list`中的 Zone 的数量等于通过`replica_factor`指定的分片副本数时，图空间的各分片副本会均匀分布在`--zone_list`中指定的 Zone 中。当指定的分片副本数不等于 Zone 的数量时，会导致创建图空间失败。
+
+有关 Zone 的更多信息，请参见[Zone](../../4.deployment-and-installation/5.zone.md)。
+
+{{ent.ent_end}}
+
 ### 克隆图空间
 
 ```ngql

diff --git a/...-installation/2.compile-and-install-nebula-graph/deploy-nebula-graph-cluster.md b/...-installation/2.compile-and-install-nebula-graph/deploy-nebula-graph-cluster.md
@@ -270,6 +270,14 @@
  --port=9779
  ```
 
+{{ent.ent_begin}}
+### (可选) 配置 Zone
+
+Zone 是 Storage 节点的逻辑机架。用户可以通过配置 Zone 并将指定 Storage 节点加入到 Zone 中，同时配置 Graph 服务定向访问指定 Zone，来实现资源隔离和数据的定向访问，从而减少流量消耗以节约成本。
+
+详情请参见[Zone](../../4.deployment-and-installation/5.zone.md)。
+{{ent.ent_end}}
+
 ### 启动集群
 
 依次启动**各个服务器**上的对应进程。

diff --git a/docs-2.0/4.deployment-and-installation/5.zone.md b/docs-2.0/4.deployment-and-installation/5.zone.md
@@ -5,11 +5,15 @@ Zone 是{{nebula.name}}中存储（Storage）节点的逻辑机架，它将多
 
 ## 原理介绍
 
-用户可以将 Storage 节点加入某个 Zone 中，创建图空间时指定 Zone 的列表，就会在这些 Zone 内的 Storage 节点上创建及存储图空间。分片副本会均匀存储在各个 Zone 中。如下图所示。
+在{{nebula.name}}中，用户可以设置多个 Zone，每个 Zone 包含一个或多个 Storage 节点。之后，在创建图空间指定数据被切分的分片数及各分片的副本数，同时指定图空间中各分片副本数将存储在哪些 Zone 时，就会在这些 Zone 内的 Storage 节点上创建及存储图空间数据。需要注意的是，**指定的分片副本数和设置的 Zone 数量必须相等，否则无法创建图空间**。
+
+当图空间指定 Zone 后，{{nebula.name}}会将图空间数据的各分片副本均匀存储在指定的 Zone 中，并且每个 Zone 中包含完整的图空间数据分片。因为{{nebula.name}}中的分片副本是通过 [Raft](../1.introduction/3.nebula-graph-architecture/4.storage-service.md#raft_1) 协议实现强一致性，其限制分片副本数必须为奇数，因此 Zone 的数量也必须为奇数。
+
+以下图为例，创建图空间时指定的数据切分为 3 分片，各分片副本数为 3，Zone 的数量也为 3；6 台启动 Storage 服务的机器两两组合，加入这 3 个 Zone。在创建图空间时，{{nebula.name}}会将图空间数据的各分片副本均匀存储在 zone1 ~ zone3 中，并且每个 Zone 中包含完整的图空间数据分片（part_1 ~ part_3）。
 
 ![Zone 示意图](https://docs-cdn.nebula-graph.com.cn/figures/zone1.png)
 
-在上图中，6 台启动 Storage 服务的机器两两组合，加入 3 个 Zone。当指定这三个 Zone 创建分片副本数为 3 的图空间 S1 时，分片副本会均匀存储在 Zone1 ~ Zone3。
+同时，为了减少查询时的流量消耗，可以配置 Graph 服务访问指定的单个 Zone。当 Graph 服务访问指定的 Zone 时，Graph 服务会定向访问指定 Zone 中的分片副本数据。
 
 ## 适用场景
 
@@ -22,22 +26,28 @@ Zone 是{{nebula.name}}中存储（Storage）节点的逻辑机架，它将多
 ## 注意事项
 
 - 如果当前集群中有数据，需要先清空集群数据，再开启 Zone 功能。有关如何开启 Zone 功能，请参见下文**开启 Zone**。
-- 一个 Storage 节点只能属于一个 Zone，但一个 Zone 可以包含多个不同的 Storage 节点。
-- 不支持删除 Zone。
+- 开启 Zone 功能后：
+ - Storage 节点必须归属于一个 Zone。
+ - 一个 Storage 节点只能属于一个 Zone，一个 Zone 可以包含多个不同的 Storage 节点。
+ - Storage 节点的数量必须大于或等于 Zone 的数量。
+- Zone 的数量必须为奇数，并且必须等于分片副本数。
+- 不支持变更 Zone 的数量，即不支持增加或减少 Zone。
 - 不支持修改 Zone 的名称。
 
 ## 开启 Zone 
 
-1. 在配置文件`nebula-metad.conf`中，手动添加`--zone_list`字段，并设置其值为需要添加的 Zone 的名称，如`--assigned_zone=zone1, zone2, zone3`。
+1. 在配置文件`nebula-metad.conf`中，设置`--zone_list`的值为需要添加的 Zone 的名称，如`--assigned_zone=zone1, zone2, zone3`。
 
  !!! danger
 
   一旦`--zone_list`的值配置完并启动 Meta 服务后，不允许被修改，否则再次重启 Meta 服务会失败。
 
  !!! note
 
-  如果 Zone 的名称使用特殊字符（不包括下划线）、保留关键字，或数字开头时，在查询语句中指定 Zone 名称时需要用反引号（`）包围；Zone 名称中不能使用英文句号（.）；多个 Zone 名称之间使用英文逗号（,）分隔。
-
+  - 当`--zone_list`为空时，表示不开启 Zone 功能。
+  - `--zone_list`中指定的 Zone 的数量必须为奇数，并且必须小于或等于 Storage 节点的数量。
+  - 如果 Zone 的名称使用特殊字符（不包括下划线）、保留关键字，或数字开头时，在查询语句中指定 Zone 名称时需要用反引号（`）包围；Zone 名称中不能使用英文句号（.）；多个 Zone 名称之间使用英文逗号（,）分隔。
+
  关于 Meta 配置文件的详情，参见 [Meta 服务配置](../5.configurations-and-logs/1.configurations/2.meta-config.md)。
 
 2. 重启 Meta 服务。
@@ -46,26 +56,27 @@ Zone 是{{nebula.name}}中存储（Storage）节点的逻辑机架，它将多
 ## 定向访问指定 Zone 
 
 1. 开启 Zone。详情见上文**开启 Zone**。
+
 2. 在配置文件`nebula-graphd.conf`中，添加以下配置：
 
- 1. 添加`--assigned_zone`字段，并设置其值为需要访问的 Zone 的名称，如`--assigned_zone=zone1`。
+ 1. 设置`--assigned_zone`的值为需要访问的 Zone 的名称，如`--assigned_zone=zone1`。
 
  !!! note
 
- - 不同的 Graph 服务可以设置不同的`--assigned_zone`值，但`--assigned_zone`的值必须是`--zone_list`中的一个。
- - `--assigned_zone`的值是一个字符串，不支持使用英文逗号（,）分隔。
- - 当`--assigned_zone`的值为空时，表示访问所有 Zone。
+  - 不同的 Graph 服务可以设置不同的`--assigned_zone`值，但`--assigned_zone`的值必须是`--zone_list`中的一个。
+  - `--assigned_zone`的值是一个字符串，不支持使用英文逗号（,）分隔。
+  - 当`--assigned_zone`的值为空时，表示访问所有 Zone。
 
- 2. 设置`--enable_intra_zone_routing=true`，以开启定向访问指定 Zone 的功能。
+ 2. 设置`--prioritize_intra_zone_routing`的值为`true`，以开启定向访问指定 Zone 的功能。
 
  !!! caution
 
- 不同的 Graph 服务中的`--enable_intra_zone_routing`值建议保持一致，否则会导致 Storage 节点的负载不均衡及未知风险。
+  不同的 Graph 服务中的`--prioritize_intra_zone_routing`值建议保持一致，否则会导致 Storage 节点的负载不均衡及未知风险。
+
+ 关于 Graph 的配置，参见 [Graph 服务配置](../5.configurations-and-logs/1.configurations/3.graph-config.md)。
 
 3. 重启 Graph 服务。
 
-
-关于 Graph 的配置，参见 [Graph 服务配置](../5.configurations-and-logs/1.configurations/3.graph-config.md)。
 
 ## Zone 命令
 
@@ -82,15 +93,16 @@ nebula> SHOW ZONES;
 +--------+-----------------+------+
 | "az1" | "192.168.8.111" | 9779 |
 | "az1" | "192.168.8.112" | 9779 |
-| "az2" | "" | 0  |
-| "az3" | "" | 0 |
+| "az2" | "192.168.8.113" | 9779 |
+| "az3" | "192.168.8.114" | 9779 | 
 +--------+-----------------+------+
 ```
 
 !!! note
- 在当前图空间中，执行`SHOW ZONES`返回是所有的 Zone 信息，而不是当前图空间所在的 Zone 信息。信息中的`Host`和`Port`字段是指定 Zone 中的 Storage 节点的 IP 和端口。
 
-### 查看指定 Zone
+ 信息中的`Host`和`Port`字段是指定 Zone 中的 Storage 节点的 IP 和端口。
+
+### 查看指定 Zone 信息
 
 ```ngql
 DESCRIBE ZONE <zone_name>;
@@ -104,37 +116,15 @@ nebula> DESC ZONE az1
 | Hosts | Port |
 +-----------------+------+
 | "192.168.8.111" | 7779 |
-| "192.168.8.111" | 9779 |
+| "192.168.8.112" | 9779 |
 +-----------------+------+
 ```
 
 ### 在 Zone 中创建图空间
 
-```ngql
-CREATE SPACE IF NOT EXISTS (
- [partition_num = <partition_number>,]
- [replica_factor = <replica_number>,]
- vid_type = {FIXED_STRING(<N>) | INT[64]}
- )
- [COMMENT = '<comment>'] 
- [ON <zone_list>];
-```
-
-!!! note
-
- - 创建图空间时指定的 Zone 必须是 Meta 配置文件中`--zone_list`值中的一个或者多个，否则无法创建图空间。
- - 创建图空间时指定的 Zone 必须包含至少一个 Storage 节点，否则无法创建图空间。
- - 创建图空间时指定的分片副本数必须小于等于 Zone 的数量，否则无法创建图空间。
-
-!!! caution
+在 Zone 中创建图空间的语法同[创建图空间](../3.ngql-guide/9.space-statements/1.create-space.md)中的语法，只是在创建图空间时，系统会自动识别 Meta 配置文件中`--zone_list`的值，如果其值不为空并且值中的 Zone 的数量等于通过`replica_factor`指定的分片副本数时，图空间的各分片副本会均匀分布在`--zone_list`中指定的 Zone 中。当指定的分片副本数不等于 Zone 的数量时，会导致创建图空间失败。
 
- 不建议在开启 Zone 功能并为 Graph 服务配置了访问指定 Zone（设置`--assigned_zone`）的情况下，创建图空间时不指定 Zone。这样会导致无法查询到分布在其他 Zone 中的分片副本数据，因为 Graph 服务只会访问指定 Zone 中的分片副本数据，而创建图空间时不指定 Zone 会使分片副本分布在其他 Zone 中。 
-
-示例：
-
-```ngql
-nebula> CREATE SPACE IF NOT EXISTS my_space_1 (vid_type=FIXED_STRING(30)) on az1
-```
+如果`--zone_list`的值为空，代表不开启 Zone 功能，此时创建图空间时，不会指定图空间的 Zone。
 
 ### 查看图空间的 Zone 信息
 
@@ -156,19 +146,44 @@ nebula> DESC SPACE my_space_1
 ### 将 Storage 节点加入 Zone
 
 ```ngql
-ADD HOSTS <ip>:<port> [,<ip>:<port> ...] INTO ZONE <new_zone_name>;
+ADD HOSTS <ip>:<port> [,<ip>:<port> ...] INTO ZONE <zone_name>;
 ```
 
+!!! note
+
+ - 开启 Zone 功能后，执行`ADD HOSTS`命令时必须指定`INTO ZONE`子句，否则会导致添加 Storage 节点失败。
+ - 一个 Storage 节点只能属于一个 Zone，一个 Zone 可以包含多个不同的 Storage 节点。
+
 示例：
 
 ```ngql
 nebula> ADD HOSTS 192.168.8.111:9779,192.168.8.112:9779 INTO ZONE az1;
 ```
 
+### 负载均衡 Zone 中的 Storage 节点
+
+```ngql
+BALANCE DATA IN ZONE [<zone_name>];
+```
+
+!!! note
+
+ 执行该命令前，需要先指定图空间。
+
+当开启 Zone 后，执行`BALANCE DATA IN ZONE`命令时，会在当前图空间中的所有 Zone 内均衡分布分片副本。如果通过`<zone_name>`选项指定了某个 Zone 时，则会在指定的 Zone 内的 Storage 节点中均衡分布分片副本。
+
+
+示例：
+
+```ngql
+nebula> USE my_space_1;
+nebula> BALANCE IN ZONE;
+```
+
 ### 迁移 Zone 中的 Storage 节点数据至其他 Storage 节点
 
 ```ngql
-BALANCE IN ZONE REMOVE <ip>:<port> [,<ip>:<port> ...]
+BALANCE DATA IN ZONE REMOVE <ip>:<port> [,<ip>:<port> ...]
 ```
 
 !!! note
@@ -205,28 +220,14 @@ DROP HOSTS <ip>:<port> [,<ip>:<port> ...];
 
 !!! note
 
- 无法直接删除正在使用的 Storage 节点，需要先删除关联的图空间，才能删除 Storage 节点。
+ - 无法直接删除正在使用的 Storage 节点，需要先删除关联的图空间，才能删除 Storage 节点。
+ - 移除 Storage 节点后，确保剩余 Storage 节点数量足够满足设置的 Zone 数量，否则会导致图空间无法正常使用。
 
 示例：
 
 ```ngql
 nebula> DROP HOSTS 192.168.8.111:9779;
 ```
 
-### 负载均衡 Zone 中的 Storage 节点
 
-```ngql
-BALANCE IN ZONE;
-```
-
-!!! note
-
- 执行该命令前，需要先指定图空间。
-
-示例：
-
-```ngql
-nebula> USE my_space_1;
-nebula> BALANCE IN ZONE;
-```
 
diff --git a/docs-2.0/4.deployment-and-installation/manage-storage-host.md b/docs-2.0/4.deployment-and-installation/manage-storage-host.md
@@ -31,6 +31,12 @@ nebula> ADD HOSTS "<hostname>":<port> [,"<hostname>":<port> ...];
 
  - 确保新增的 Storage 主机没有被其他集群使用过，否则会导致添加 Storage 节点失败。
 
+{{ent.ent_begin}}
+
+向开启了 Zone 功能的集群中增加 Storage 主机时，需要指定`INTO ZONE`选项，否则会导致添加 Storage 节点失败。详情参见[管理 Zone](5.zone.md)。
+
+{{ent.ent_end}}
+
 ## 删除 Storage 主机
 
 从集群中删除 Storage 主机。

diff --git a/docs-2.0/5.configurations-and-logs/1.configurations/2.meta-config.md b/docs-2.0/5.configurations-and-logs/1.configurations/2.meta-config.md
@@ -113,7 +113,7 @@ Meta 服务提供了两份初始配置文件`nebula-metad.conf.default`和`nebul
 
 | 名称 | 预设值 | 说明 | 是否支持运行时动态修改 |
 | :-------------------- | :----- | :------------------- | :--------------------- |
-| `enable_zones` | `false` | 是否开启 Zone 功能。详情参见[管理 Zone](../../4.deployment-and-installation/5.zone.md)。 | 不支持 |
+| `zone_list` | 空 | 当值不为空时，即开启 Zone 功能。详情参见[管理 Zone](../../4.deployment-and-installation/5.zone.md)。 | 不支持 |
 
 {{ ent.ent_end }}
 

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
@@ -183,4 +183,13 @@ Graph 服务提供了两份初始配置文件`nebula-graphd.conf.default`和`neb
 |`enable_http2_routing` |`false` |是否为 RPC 通信启用 HTTP2。启用后会轻微影响性能。|支持|
 |`stream_timeout_ms` |`30000` | HTTP 流的超时时间。单位：毫秒。|支持|
 
+
+## Zone 配置
+
+| 名称 | 预设值 | 说明 | 是否支持运行时动态修改 |
+| :-------------------- | :----- | :------------------- | :--------------------- |
+| `assigned_zone` | 空 | 当开启 Zone 功能时，设置一个已存在的 Zone 名称以定向访问该 Zone。详情参见[管理 Zone](../../4.deployment-and-installation/5.zone.md)。 | 不支持 |
+| `prioritize_intra_zone_routing` | `false` | 当值为`true`并在`assigned_zone`中指定了 Zone，将优先读该 Zone 内的副本数据，如果该 Zone 内没有数据，再根据`stick_to_intra_zone_on_failure`判断是否读取其他 Zone 的数据。<br/>当值为`false`时，将读取 Leader 副本数据。 | 不支持 |
+|`stick_to_intra_zone_on_failure`|`false`|当值为`true`时，如果`assigned_zone`中指定的 Zone 内没有数据，将不会读取其他 Zone 的数据。<br/>为`false`时，将读取 Leader 副本数据。|不支持|
+
 {{ ent.ent_end }}