CREATE TAG¶

CREATE TAG creates a tag with the given name in a graph space.

OpenCypher compatibility¶

Tags in nGQL are similar to 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 vertices in CREATE statements.
In nGQL, tags are created separately using CREATE TAG statements. Tags in nGQL are more like tables in MySQL.

Prerequisites¶

Running the CREATE TAG statement requires some privileges for the graph space. Otherwise, NebulaGraph throws an error.

Syntax¶

To create a tag in a specific graph space, you must specify the current working space with the USE statement.

CREATE TAG [IF NOT EXISTS] <tag_name>
    (
      <prop_name> <data_type> [NULL | NOT NULL] [DEFAULT <default_value>] [COMMENT '<comment>']
      [{, <prop_name> <data_type> [NULL | NOT NULL] [DEFAULT <default_value>] [COMMENT '<comment>']} ...] 
    )
    [TTL_DURATION = <ttl_duration>]
    [TTL_COL = <prop_name>]
    [COMMENT = '<comment>'];

Parameter	Description
`IF NOT EXISTS`	Detects if the tag that you want to create exists. If it does not exist, a new one will be created. The tag existence detection here only compares the tag names (excluding properties).
`<tag_name>`	1. Each tag name in the graph space must be unique. 2. Tag names cannot be modified after they are set. 3. Tag names cannot start with a number; they support 1-4 byte UTF-8 encoded characters, including English letters (case sensitive), numbers, Chinese characters, etc., but do not support special characters other than underscores. To use special characters, reserved keywords, or start with a number in a tag name, enclose them in backticks (`), and do not use periods (`.`) in a tag name. For more information, see Keywords and reserved words. Note: If you name a tag in Chinese and encounter a `SyntaxError`, you need to quote the Chinese characters with backticks (`).
`<prop_name>`	The name of the property. It must be unique for each tag. The rules for permitted property names are the same as those for tag names.
`<data_type>`	Shows the data type of each property. For a full description of the property data types, see Data types and Boolean.
`NULL \\| NOT NULL`	Specifies if the property supports `NULL \| NOT NULL`. The default value is `NULL`.
`DEFAULT`	Specifies a default value for a property. The default value can be a literal value or an expression supported by NebulaGraph. If no value is specified, the default value is used when inserting a new vertex.
`COMMENT`	The remarks of a certain property or the tag itself. The maximum length is 256 bytes. By default, there will be no comments on a tag.
`TTL_DURATION`	Specifies the life cycle for the property. The property 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 `0`. It means the data never expires.
`TTL_COL`	Specifies the property to set a timeout on. The data type of the property must be `int` or `timestamp`. A tag can only specify one field as `TTL_COL`. For more information on TTL, see TTL options.

Examples¶

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

# The following example creates a tag with no properties.
nebula> CREATE TAG IF NOT EXISTS no_property(); 

# The following example creates a tag with a default value.
nebula> CREATE TAG IF NOT EXISTS player_with_default(name string, age int DEFAULT 20);

# In the following example, the TTL of the create_time field is set to be 100 seconds.
nebula> CREATE TAG IF NOT EXISTS woman(name string, age int, \
        married bool, salary double, create_time timestamp) \
        TTL_DURATION = 100, TTL_COL = "create_time";

Implementation of the operation¶

Trying to use a newly created tag may fail because the creation of the tag 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.

Last update: June 6, 2023