group&zone

docs-2.0/3.ngql-guide/18.operation-and-maintenance-statements/2.balance-syntax.md

@@ -6,8 +6,8 @@ The `BALANCE` statements are listed as follows.
 
 |Syntax|Description|
 |-|-|
-|`BALANCE DATA`|Starts a task to balance the distribution of storage partitions in a Nebula Graph cluster. It returns the task ID (`balance_id`). |
+|`BALANCE DATA`|Starts a task to balance the distribution of storage partitions in a Nebula Graph cluster or a Group. It returns the task ID (`balance_id`). |
 |`BALANCE DATA <balance_id>`|Shows the status of the `BALANCE DATA` task.|
 |`BALANCE DATA STOP`|Stops the `BALANCE DATA` task.|
 |`BALANCE DATA REMOVE <host_list>`|Scales in the Nebula Graph cluster and detaches specific storage hosts.|
-|`BALANCE LEADER`|Balances the distribution of storage raft leaders in a Nebula Graph cluster.|
+|`BALANCE LEADER`|Balances the distribution of storage raft leaders in a Nebula Graph cluster or a Group.|

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

@@ -16,6 +16,7 @@ CREATE SPACE [IF NOT EXISTS] <graph_space_name> (
     [replica_factor = <replica_number>,]
     vid_type = {FIXED_STRING(<N>) | INT[64]}
     )
+    [ON <group_name>]
     [COMMENT = '<comment>'];
 ```
 
@@ -26,6 +27,7 @@ CREATE SPACE [IF NOT EXISTS] <graph_space_name> (
 |`partition_num`|Specifies the number of partitions in each replica. The suggested number is five times the number of the hard disks in the cluster. For example, if you have 3 hard disks in the cluster, we recommend that you set 15 partitions. The default value is 100.|
 |`replica_factor`|Specifies the number of replicas in the cluster. The suggested number is 3 in a production environment and 1 in a test environment. The replica number must be an **odd number** for the need of quorum-based voting. The default value is 1.|
 |`vid_type`|A required parameter. Specifies the VID type in a graph space. Available values are `FIXED_STRING(N)` and `INT64`. `INT` equals to `INT64`. `FIXED_STRING(<N>)` specifies the VID as a string, while `INT64` specifies it as an integer. `N` represents the maximum length of the VIDs. If you set a VID that is longer than `N` characters, Nebula Graph throws an error.|
+|`ON <group_name>`|Specifies the Group to which a space belongs. For more information, see [Group&Zone](../../7.data-security/5.zone.md).|
 |`COMMENT`|The remarks of the graph space. The maximum length is 256 bytes. By default, there is no comments on a space.|
 
 !!! caution

docs-2.0/7.data-security/5.zone.md

@@ -0,0 +1,173 @@
+# Group&Zone
+
+The Group&Zone feature groups the nodes where Storage services are located (also called Storage nodes) to isolate resources.
+
+## Background
+
+Storage nodes can be added to a Zone, and multiple Zones form a Group. If you specify a Group when creating a space, the space will be created and stored on the Storage nodes within the Group. Data partitions and replicas are stored evenly in each Zone as shown below.
+
+![Group&Zone sketch map](zone1.png)
+
+Suppose that 8 Storage nodes are divided into 4 Zones, with each one having 2 Storage nodes, and then add Zone1, Zone2, and Zone3 to Group1，add Zone3, Zone4 to Group2.
+
+After specifying Group1 when you create a space called S1, data partitions and replicas will be stored evenly on the nodes in Zone1, Zone2, and Zone3, and will not be stored on the node in Zone4.
+
+After specifying Group2 when you create another space called S2, data partitions and replicas will be stored evenly on the nodes in Zone3 and Zone4, and will not be stored on the nodes in Zone1 and Zone2.
+
+The above example briefly introduces the Zone feature. Resources are isolated by rational planning of Zones and Groups.
+
+## Scenario
+
+- Create a space on specified Storage nodes to isolate resources.
+
+- Perform rolling upgrade of a cluster in which you need to stop one or more nodes before the cluster is upgraded, and then restart the nodes until all services on the nodes in the cluster are updated to the latest version.
+
+## Note
+
+- A Zone is a collection of Storage nodes, and each Storage node can only be added to one Zone.
+
+- Replicas can be restored in a Zone, and only one replica of the same partition can exist in a Zone.
+
+- Many Zones form a Group where resources are isolated.
+
+- A Zone can be added to multiple Groups.
+
+- If you specify a Group when creating a space, replicas in the space will be distributed evenly in each Zone within the Group.
+
+- You can create multiple spaces using a Group，but note that the number of Zones in the Group needs to be greater than or equal to the number of replicas (`replica_factor`) specified when creating a space.
+
+## Syntax
+
+### ADD ZONE
+
+Create a Zone and add Storage nodes to the Zone.
+
+```ngql
+ADD ZONE <zone_name> <host1>:<port1> [,<host2>:<port2>...];
+```
+
+For example:
+
+```ngql
+nebula> ADD ZONE zone1 192.168.8.111:9779, 192.168.8.129:9779;
+```
+
+### ADD HOST...INTO ZONE
+
+Add a Storage node to a created Zone.
+
+!!! note
+
+    Use the [BALANCE](../3.ngql-guide/18.operation-and-maintenance-statements/2.balance-syntax.md) command to perform loading balancing after the Storage node is added to a created Zone.
+
+```ngql
+ADD HOST <host1>:<port1> INTO ZONE <zone_name>;
+```
+
+### DROP HOST...FROM ZONE
+
+Delete a Storage node from a Zone.
+
+!!! note
+
+    You cannot delete a Storage node that is being used in a Group. Delete the related space before the Storage node is deleted.
+
+```ngql
+DROP HOST <host1>:<port1> FROM ZONE <zone_name>;
+```
+
+### SHOW ZONES
+
+View all Zones
+
+```ngql
+SHOW ZONES;
+```
+
+### DESCRIBE ZONE
+
+View a specified Zone.
+
+```ngql
+DESCRIBE ZONE <zone_name>;
+DESC ZONE <zone_name>;
+```
+
+### DROP ZONE
+
+Delete a Zone.
+
+!!! note
+
+    You cannot delete a Zone that has been added to a Group. Remove the Zone from the Group or delete the Group before the Zone is deleted.
+
+```ngql
+DROP ZONE <zone_name>;
+```
+
+### ADD GROUP
+
+Create a Group and add one or more Zones to the Group.
+
+```ngql
+ADD GROUP <group_name> <zone_name> [,<zone_name>...];
+```
+
+For example:
+
+```ngql
+nebula> ADD GROUP group1 zone1,zone2;
+```
+
+### ADD ZONE...INTO GROUP
+
+Add a Zone to a created Group.
+
+!!! note
+
+    Use the [BALANCE](../3.ngql-guide/18.operation-and-maintenance-statements/2.balance-syntax.md) command to perform loading balancing after the Zone is added to a created Group.
+
+```ngql
+ADD ZONE <zone_name> INTO GROUP <group_name>;
+```
+
+### DROP ZONE...FROM GROUP
+
+Delete a Zone from a GROUP.
+
+!!! note
+
+    You cannot delete a Zone that is being used in a Group. Delete the related space before the Zone is deleted.
+
+```ngql
+DROP ZONE <zone_name> FROM GROUP <group_name>;
+```
+
+### SHOW GROUPS
+
+View all Groups.
+
+```ngql
+SHOW GROUPS;
+```
+
+### DESCRIBE GROUP
+
+View a specified Group.
+
+```ngql
+DESCRIBE GROUP <group_name>;
+DESC GROUP <group_name>;
+```
+
+### DROP GROUP
+
+Delete a Group.
+
+!!! note
+
+    You cannot delete a Group that is being used. Delete the related space before the Group is deleted.
+
+```ngql
+DROP GROUP <group_name>;
+```