INSERT VERTEX¶

The INSERT VERTEX statement inserts one or more vertices into a graph space in NebulaGraph.

Prerequisites¶

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

Syntax¶

INSERT VERTEX [IF NOT EXISTS] <tag_name> (<prop_name_list>) [, <tag_name> (<prop_name_list>), ...]
     {VALUES | VALUE} VID: (<prop_value_list>[, <prop_value_list>])

prop_name_list:
  [prop_name [, prop_name] ...]

prop_value_list:
  [prop_value [, prop_value] ...]

IF NOT EXISTS detects if the VID that you want to insert exists. If it does not exist, a new one will be inserted.
Note
- IF NOT EXISTS only compares the names of the VID and the tag (excluding properties).
- IF NOT EXISTS will read to check whether the data exists, which will have a significant impact on performance.

tag_name denotes the tag (vertex type), which must be created before INSERT VERTEX. For more information, see CREATE TAG.

prop_name_list contains the names of the properties on the tag.

VID is the vertex ID. In NebulaGraph 2.0, string and integer VID types are supported. The VID type is set when a graph space is created. For more information, see CREATE SPACE.

prop_value_list must provide the property values according to the prop_name_list. If the property values do not match the data type in the tag, an error is returned. When the NOT NULL constraint is set for a given property, an error is returned if no property is given. When the default value for a property is NULL, you can omit to specify the property value. For details, see CREATE TAG.

Caution

INSERT VERTEX and CREATE have different semantics.

The semantics of INSERT VERTEX is closer to that of INSERT in NoSQL (key-value), or UPSERT (UPDATE or INSERT) in SQL.
When two INSERT statements (neither uses IF NOT EXISTS) with the same VID and TAG are operated at the same time, the latter INSERT will overwrite the former.
When two INSERT statements with the same VID but different TAGS are operated at the same time, the operation of different tags will not overwrite each other.

Examples are as follows.

Examples¶

# The following examples create tag t1 with no property and inserts vertex "10" with no property.
nebula> CREATE TAG IF NOT EXISTS t1();                   
nebula> INSERT VERTEX t1() VALUE "10":();

nebula> CREATE TAG IF NOT EXISTS t2 (name string, age int);                
nebula> INSERT VERTEX t2 (name, age) VALUES "11":("n1", 12);

#  In the following example, the insertion fails because "a13" is not int.
nebula> INSERT VERTEX t2 (name, age) VALUES "12":("n1", "a13"); 

# The following example inserts two vertices at one time.
nebula> INSERT VERTEX t2 (name, age) VALUES "13":("n3", 12), "14":("n4", 8);

nebula> CREATE TAG IF NOT EXISTS t3(p1 int);
nebula> CREATE TAG IF NOT EXISTS t4(p2 string);

# The following example inserts vertex "21" with two tags.
nebula> INSERT VERTEX t3 (p1), t4(p2) VALUES "21": (321, "hello");

A vertex can be inserted/written with new values multiple times. Only the last written values can be read.

# The following examples insert vertex "11" with new values for multiple times.
nebula> INSERT VERTEX t2 (name, age) VALUES "11":("n2", 13);
nebula> INSERT VERTEX t2 (name, age) VALUES "11":("n3", 14);
nebula> INSERT VERTEX t2 (name, age) VALUES "11":("n4", 15);
nebula> FETCH PROP ON t2 "11";
+---------------------------------+
| vertices_                       |
+---------------------------------+
| ("11" :t2{age: 15, name: "n4"}) |
+---------------------------------+

nebula> CREATE TAG IF NOT EXISTS t5(p1 fixed_string(5) NOT NULL, p2 int, p3 int DEFAULT NULL);
nebula> INSERT VERTEX t5(p1, p2, p3) VALUES "001":("Abe", 2, 3);

# In the following example, the insertion fails because the value of p1 cannot be NULL.
nebula> INSERT VERTEX t5(p1, p2, p3) VALUES "002":(NULL, 4, 5);
[ERROR (-1005)]: Storage Error: The not null field cannot be null.

# In the following example, the value of p3 is the default NULL.
nebula> INSERT VERTEX t5(p1, p2) VALUES "003":("cd", 5);
nebula> FETCH PROP ON t5 "003";
+--------------------------------------------+
| vertices_                                  |
+--------------------------------------------+
| ("003" :t5{p1: "cd", p2: 5, p3: __NULL__}) |
+--------------------------------------------+

# In the following example, the allowed maximum length of p1 is 5.
nebula> INSERT VERTEX t5(p1, p2) VALUES "004":("shalalalala", 4);
nebula> FETCH PROP on t5 "004";
+-----------------------------------------------+
| vertices_                                     |
+-----------------------------------------------+
| ("004" :t5{p1: "shala", p2: 4, p3: __NULL__}) |
+-----------------------------------------------+

If you insert a vertex that already exists with IF NOT EXISTS, there will be no modification.

# The following example inserts vertex "1".
nebula> INSERT VERTEX t2 (name, age) VALUES "1":("n2", 13);
# Modify vertex "1" with IF NOT EXISTS. But there will be no modification as vertex "1" already exists.
nebula> INSERT VERTEX IF NOT EXISTS t2 (name, age) VALUES "1":("n3", 14);
nebula> FETCH PROP ON t2 "1";
+--------------------------------+
| vertices_                      |
+--------------------------------+
| ("1" :t2{age: 13, name: "n2"}) |
+--------------------------------+

Last update: March 13, 2023