CREATE SPACE¶

Graph spaces are used to store data in a physically isolated way in NebulaGraph, 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]}
    )
    [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>`	1. Uniquely identifies a graph space in a NebulaGraph instance. 2. Space names cannot be modified after they are set. 3. By default, the name only supports 1-4 byte UTF-8 encoded characters, including English letters (case sensitive), numbers, Chinese characters, etc. However, it cannot include special characters other than the underscore (_), and cannot start with a number. 4. To use special characters, reserved keywords, or start with a number, quote the entire name with backticks (`) and do not include periods (`.`) within the pair of backticks (`). For more information, see Keywords and reserved words. Note: 1. If you name a space in Chinese and encounter a `SyntaxError`, you need to quote the Chinese characters with backticks (`). 2. To include a backtick (`) in a space name, use a backslash to escape the backtick, such as \`; to include a backslash, the backslash itself also needs to be escaped, such as \ .
`partition_num`	Specifies the number of partitions in each replica. The suggested value is 20 times (2 times for HDD) the number of the hard disks in the cluster. For example, if you have three hard disks in the cluster, we recommend that you set 60 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` bytes, NebulaGraph throws an error. Note, for UTF-8 chars, the length may vary in different cases, i.e. a UTF-8 Chinese char is 3 byte, this means 11 Chinese chars(length-33) will exeed a FIXED_STRING(32) vid defination.
`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 NebulaGraph Storage Service with the SUBMIT JOB BALANCE statement.

Restrictions on VID type change and VID length:
- For NebulaGraph v1.x, the type of VIDs can only be INT64, and the String type is not allowed. For NebulaGraph v2.x, both INT64 and FIXED_STRING(<N>) VID types are allowed. You must specify the VID type when creating a graph space, and use the same VID type in INSERT statements, otherwise, an error message Wrong vertex id type: 1001 occurs.
- The length of the VID should not be longer than N characters. If it exceeds N, NebulaGraph throws The VID must be a 64-bit integer or a string fitting space vertex id length limit..

If the Host not enough! error appears, the immediate cause is that the number of online storage hosts is less than the value of replica_factor specified when creating a graph space. In this case, you can use the SHOW HOSTS command to see if the following situations occur:
- For the case where there is only one storage host in a cluster, the value of replica_factor can only be specified to 1. Or create a graph space after storage hosts are scaled out.
- A new storage host is found, but ADD HOSTS is not executed to activate it. In this case, run SHOW HOSTS to locate the new storage host information and then run ADD HOSTS to activate it. A graph space can be created after there are enough storage hosts.
- For offline storage hosts after running SHOW HOSTS, troubleshooting is needed.

Legacy version compatibility

For NebulaGraph v2.x before v2.5.0, vid_type is optional and defaults to 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 [IF NOT EXISTS] <new_graph_space_name> AS <old_graph_space_name>;

Parameter	Description
`IF NOT EXISTS`	Detects if the new graph space exists. If it does not exist, the new one will be created. The graph space existence detection here only compares the graph space name (excluding properties).
`<new_graph_space_name>`	The name of the graph space that is newly created. By default, the space name only supports 1-4 byte UTF-8 encoded characters, including English letters (case sensitive), numbers, Chinese characters, etc. But special characters can only use underscore, and cannot start with a number. To use special characters, reserved keywords, or start with a number, quote the entire name with backticks (`) and cannot use periods (`.`). For more information, see Keywords and reserved words. 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. Note: 1. If you name a space in Chinese and encounter a `SyntaxError`, you need to quote the Chinese characters with backticks (`). 2. To include a backtick (`) in a space name, use a backslash to escape the backtick, such as \`; to include a backslash, the backslash itself also needs to be escaped, such as \ .
`<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 IF NOT EXISTS 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 IF NOT EXISTS 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 IF NOT EXISTS 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 IF NOT EXISTS 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)) comment = '测试图空间'" |
+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+

Implementation of the operation¶

Caution

Trying to use a newly created graph space may fail because the creation is implemented asynchronously. To make sure the follow-up operations work as expected, 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         | Version |
+-------------+------+----------+--------------+--------------------------------+--------------------------------+---------+
| "storaged0" | 9779 | "ONLINE" | 8            | "basketballplayer:3, test:5"   | "basketballplayer:10, test:10" | "master" |
| "storaged1" | 9779 | "ONLINE" | 9            | "basketballplayer:4, test:5"   | "basketballplayer:10, test:10" | "master" |
| "storaged2" | 9779 | "ONLINE" | 3            | "basketballplayer:3"           | "basketballplayer:10, test:10" | "master" |
+-------------+------+----------+--------------+--------------------------------+--------------------------------+---------+

To balance the request loads, use the following command.

nebula> BALANCE LEADER;
nebula> SHOW HOSTS;
+-------------+------+----------+--------------+--------------------------------+--------------------------------+---------+
| Host        | Port | HTTP port | Status   | Leader count | Leader distribution            | Partition distribution         | Version |
+-------------+------+-----------+----------+--------------+--------------------------------+--------------------------------+---------+
| "storaged0" | 9779 | "ONLINE" | 7            | "basketballplayer:3, test:4"   | "basketballplayer:10, test:10" | "master" |
| "storaged1" | 9779 | "ONLINE" | 7            | "basketballplayer:4, test:3"   | "basketballplayer:10, test:10" | "master" |
| "storaged2" | 9779 | "ONLINE" | 6            | "basketballplayer:3, test:3"   | "basketballplayer:10, test:10" | "master" |
+-------------+------+----------+--------------+--------------------------------+--------------------------------+---------+

Last update: January 30, 2024