Skip to content


CREATE TAG creates a tag with the given name in a graph space. You must have the CREATE privilege for the graph space. To create a tag in a specific graph space, you must use the graph space first.

OpenCypher compatibility

Tags in nGQL are similar with labels in openCypher. But they are also quite different. For example, the ways to create them are different.

  • In openCypher, labels are created together with nodes by CREATE statements.
  • In nGQL, tags are created separately by CREATE TAG statements. Tags in nGQL are more like tables in MySQL.


    ([<create_definition>, ...])

<create_definition> ::=
    <prop_name> <data_type> [NULL | NOT NULL]

<tag_options> ::=
    <option> [, <option> ...]

<option> ::=
    TTL_DURATION [=] <ttl_duration>
    | TTL_COL [=] <prop_name>
    | DEFAULT <default_value>

Tag name

  • IF NOT EXISTS: Creating an existent tag results in an error. You can use the IF NOT EXISTS option to conditionally create the tag and avoid the error.


    The tag existence detection here compares only the tag names (excluding properties).

  • tag_name: The tag name must be unique in a graph space. Once the tag name is set, it can not be altered. The rules for permitted tag names are the same as those for graph space names. For prohibited names, see Keywords and reserved words.

Property names and data types

  • prop_name

    prop_name is the name of the property. It must be unique for each tag.

  • data_type

    data_type shows the data type of each property. For a full description of the property data types, see Data types.


    Specifies if the property supports NULL | NOT NULL. The default value is NULL.


    Specifies a default value for a property. The default value can be a literal value or an expression supported by Nebula Graph. If no value is specified, the default value is used when inserting a new vertex.

Time-to-Live (TTL)


    Specifies the life cycle for the data. Data that exceeds the specified TTL expires. The expiration threshold is the TTL_COL value plus the TTL_DURATION. The default value of TTL_DURATION is zero. It means the data never expires.


    The data type of prop_name must be either int or timestamp.

  • single TTL definition

    Only one TTL_COL field can be specified in a tag.

For more information on TTL, see TTL options.


nebula> CREATE TAG player(name string, age int);

// Create a tag with no properties.
nebula> CREATE TAG no_property(); 

// Create a tag with a default value.
nebula> CREATE TAG player_with_default(name string, age int DEFAULT 20);
// Time interval is 100s, starting from the create_time field
nebula> CREATE TAG woman(name string, age int, \
   married bool, salary double, create_time timestamp) \
   TTL_DURATION = 100, TTL_COL = "create_time";

// Data expires after TTL_DURATION
nebula> CREATE TAG icec_ream(made timestamp, temperature int) \
   TTL_DURATION = 100, TTL_COL = "made";

Implementation of the operation

Trying to insert vertices with a newly created tag may fail, because the creation of the tag 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 tag in the result of SHOW TAGS. 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.

Last update: April 22, 2021
Back to top