Skip to content

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> Uniquely identifies a graph space in a NebulaGraph instance. The name of the graph space starts with a letter, supports 1 to 4 bytes UTF-8 encoded characters, such as English letters (case-sensitive), digits, and Chinese characters, but does not support special characters except underscores. To use special characters or reserved keywords as identifiers, quote them with backticks. For more information, see Keywords and reserved words.
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, NebulaGraph throws an error.
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 BALANCE statement.

Restrictions on VID type change and VID length

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..

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 starts with a letter, supports 1 to 4 bytes UTF-8 encoded characters, such as English letters (case-sensitive), digits, and Chinese characters, but does not support special characters except underscores. 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.
<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)) 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. 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" | "3.0.1" |
| "storaged1" | 9779 | "ONLINE" | 9            | "basketballplayer:4, test:5"   | "basketballplayer:10, test:10" | "3.0.1" |
| "storaged2" | 9779 | "ONLINE" | 3            | "basketballplayer:3"           | "basketballplayer:10, test:10" | "3.0.1" |
+-------------+------+----------+--------------+--------------------------------+--------------------------------+---------+

To balance the request loads, use the following command.

nebula> BALANCE LEADER;
nebula> SHOW HOSTS;
+-------------+------+----------+--------------+--------------------------------+--------------------------------+---------+
| Host        | Port | Status   | Leader count | Leader distribution            | Partition distribution         | Version |
+-------------+------+----------+--------------+--------------------------------+--------------------------------+---------+
| "storaged0" | 9779 | "ONLINE" | 7            | "basketballplayer:3, test:4"   | "basketballplayer:10, test:10" | "3.0.1" |
| "storaged1" | 9779 | "ONLINE" | 7            | "basketballplayer:4, test:3"   | "basketballplayer:10, test:10" | "3.0.1" |
| "storaged2" | 9779 | "ONLINE" | 6            | "basketballplayer:3, test:3"   | "basketballplayer:10, test:10" | "3.0.1" |
+-------------+------+----------+--------------+--------------------------------+--------------------------------+---------+
Last update: March 13, 2023
Back to top