Skip to content


CREATE SPACE [IF NOT EXISTS] <graph_space_name>
    [(partition_num = <partition_number>, 
    replica_factor = <replica_number>, 
    vid_type = {FIXED_STRING(<N>) | INT64})];

The CREATE SPACE statement creates a new graph space with the given name. A SPACE is a region that provides physically isolated graphs in Nebula Graph. An error occurs if a graph space with the same name exists if you did not specify IF NOT EXISTS.


You can use the IF NOT EXISTS keywords when creating graph spaces. These keywords automatically detect if the related graph space exists. If it does not exist, a new one is created. Otherwise, no graph space is created.

NOTE: The graph space existence detection here only compares the graph space name (excluding properties).

Graph space name

The graph_space_name uniquely identifies a graph space in a Nebula Graph instance.

Customized graph space options

You can set four optional options for a new graph space:

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

  • replica_factor

    Specifies the number of replicas in the cluster. The default replica factor is 1. The suggested number is 3 in a production environment and 1 in a test environment. Always set the replica to an odd number for the need of quorum-based voting.

NOTICE: If the replica number is set to one, you won't be able to use the BALANCE statements to load balance or scale out the Nebula Graph Storage Service.

  • vid_type

    Specifies the data type of VIDs in a graph space. Available values are FIXED_STRING(N) and INT64, where N represents the maximum length of the VIDs and it must be a positive integer. The default value is FIXED_STRING(8).

    If you set a VID length greater than N, Nebula Graph throws an error. To set the integer VID for vertices, set vid_type to INT64.

If no option is given, Nebula Graph creates the graph space with the default options.


nebula> CREATE SPACE my_space_1; -- create a graph space with default options
nebula> CREATE SPACE my_space_2(partition_num=10); -- create a graph space with customized partition number
nebula> CREATE SPACE my_space_3(replica_factor=1); -- create a graph space with customized replica factor
nebula> CREATE SPACE my_space_4(vid_type = FIXED_STRING(30)); -- create a graph space with customized VID maximum length

Implementation of the operation

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 can't, 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.

Check partition distribution

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

nebula> SHOW HOSTS;
| Host      | Port  | Status | Leader count | Leader distribution              | Partition distribution      |
| storaged0 | 9779  | ONLINE | 1            | basketballplayer:5               | basketballplayer:5          |
| storaged1 | 9779  | ONLINE | 2            | test:1, basketballplayer:5       | basketballplayer:5, test:1  |
| storaged2 | 9779  | ONLINE | 1            | basketballplayer:5               | basketballplayer:5          |

To balance the request loads, use the following command.


Last update: April 13, 2021