CREATE SPACE¶

Graph spaces are used to store data in a physically isolated way in Nebula Graph, which is similar to the database concept in MySQL. The CREATE SPACE statement can create a new graph space or clone the schema of an existing graph space.

Prerequisites¶

Only the God role can use the CREATE SPACE statement. For more information, see AUTHENTICATION.

Syntax¶

Create graph spaces¶

CREATE SPACE [IF NOT EXISTS] <graph_space_name> (
    [partition_num = <partition_number>,]
    [replica_factor = <replica_number>,]
    vid_type = {FIXED_STRING(<N>) | INT[64]}
    )
    [ON <group_name>]
    [COMMENT = '<comment>'];

Parameter	Description
`IF NOT EXISTS`	Detects if the related graph space exists. If it does not exist, a new one will be created. The graph space existence detection here only compares the graph space name (excluding properties).
`<graph_space_name>`	Uniquely identifies a graph space in a Nebula Graph instance. The name of the graph space is case-sensitive and allows letters, numbers, or underlines. Keywords and reserved words are not allowed.
`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.
`COMMENT`	The remarks of the graph space. The maximum length is 256 bytes. By default, there is no comments on a space.

Caution

If the replica number is set to one, you will not be able to load balance or scale out the Nebula Graph Storage Service with the BALANCE statement.

Caution

Restrictions on VID type change and VID length

In Nebula Graph 1.x, the VID type can only be INT64 and does not support string. In Nebula Graph 2.x, the VID type can be both INT64 and FIXED_STRING(<N>). You should specify the VID type when creating a graph space and keep consistency when using the INSERT statement. Otherwise, Nebula Graph throws Wrong vertex id type: 1001.
The length of the VID should not be longer than N characters. If it exceeds N, Nebula Graph throws The VID must be a 64-bit integer or a string fitting space vertex id length limit..

Legacy version compatibility

In the 2.x releases before 2.5.0, vid_type is not a required parameter and its default value is FIXED_STRING(8).

Note

graph_space_name, partition_num, replica_factor, vid_type, and comment cannot be modified once set. To modify them, drop the current working graph space with DROP SPACE and create a new one with CREATE SPACE.

Clone graph spaces¶

CREATE SPACE <new_graph_space_name> AS <old_graph_space_name>;

Parameter Description

<new_graph_space_name> The name of the graph space that is newly created. The name of the graph space is case-sensitive and allows letters, numbers, or underlines. Keywords and reserved words are not allowed. When a new graph space is created, the schema of the old graph space <old_graph_space_name> will be cloned, including its parameters (the number of partitions and replicas, etc.), Tag, Edge type, and native indexes.

<old_graph_space_name> The name of the graph space that already exists.

Examples¶

# The following example creates a graph space with a specified VID type and the maximum length. Other fields still use the default values.
nebula> CREATE SPACE my_space_1 (vid_type=FIXED_STRING(30));

# The following example creates a graph space with a specified partition number, replica number, and VID type.
nebula> CREATE SPACE my_space_2 (partition_num=15, replica_factor=1, vid_type=FIXED_STRING(30));

#  The following example creates a graph space with a specified partition number, replica number, and VID type, and adds a comment on it.
nebula> CREATE SPACE my_space_3 (partition_num=15, replica_factor=1, vid_type=FIXED_STRING(30)) comment="Test the graph space";

# Clone a graph space.
nebula> CREATE SPACE my_space_4 as my_space_3;
nebula> SHOW CREATE SPACE my_space_4;
+--------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Space        | Create Space                                                                                                                                                            |
+--------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| "my_space_4" | "CREATE SPACE `my_space_4` (partition_num = 15, replica_factor = 1, charset = utf8, collate = utf8_bin, vid_type = FIXED_STRING(30)) ON default comment = 'Test the graph space'"  |
+--------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

Implementation of the operation¶

Caution

Trying to use a newly created graph space may fail because the creation is implemented asynchronously.

Nebula Graph implements the creation in the next heartbeat cycle. To make sure the creation is successful, take one of the following approaches:

Find the new graph space in the result of SHOW SPACES or DESCRIBE SPACE. If you cannot, wait a few seconds and try again.

Wait for two heartbeat cycles, i.e., 20 seconds.

To change the heartbeat interval, modify the heartbeat_interval_secs parameter in the configuration files for all services. If the heartbeat interval is too short (i.e., less than 5 seconds), disconnection between peers may happen because of the misjudgment of machines in the distributed system.

Check partition distribution¶

On some large clusters, the partition distribution is possibly unbalanced because of the different startup times. You can run the following command to do a check of the machine distribution.

nebula> SHOW HOSTS;
+-------------+------+----------+--------------+--------------------------------+--------------------------------+
| Host        | Port | Status   | Leader count | Leader distribution            | Partition distribution         |
+-------------+------+----------+--------------+--------------------------------+--------------------------------+
| "storaged0" | 9779 | "ONLINE" | 8            | "basketballplayer:3, test:5"   | "basketballplayer:10, test:10" |
| "storaged1" | 9779 | "ONLINE" | 9            | "basketballplayer:4, test:5"   | "basketballplayer:10, test:10" |
| "storaged2" | 9779 | "ONLINE" | 3            | "basketballplayer:3"           | "basketballplayer:10, test:10" |
| "Total"     |      |          | 20           | "basketballplayer:10, test:10" | "basketballplayer:30, test:30" |
+-------------+------+----------+--------------+--------------------------------+--------------------------------+

To balance the request loads, use the following command.

nebula> BALANCE LEADER;
+-------------+------+----------+--------------+--------------------------------+--------------------------------+
| Host        | Port | Status   | Leader count | Leader distribution            | Partition distribution         |
+-------------+------+----------+--------------+--------------------------------+--------------------------------+
| "storaged0" | 9779 | "ONLINE" | 7            | "basketballplayer:3, test:4"   | "basketballplayer:10, test:10" |
| "storaged1" | 9779 | "ONLINE" | 7            | "basketballplayer:4, test:3"   | "basketballplayer:10, test:10" |
| "storaged2" | 9779 | "ONLINE" | 6            | "basketballplayer:3, test:3"   | "basketballplayer:10, test:10" |
| "Total"     |      |          | 20           | "basketballplayer:10, test:10" | "basketballplayer:30, test:30" |
+-------------+------+----------+--------------+--------------------------------+--------------------------------+

Last update: November 1, 2021