Skip to content

UPSERT VERTEX

UPSERT VERTEX <vid> SET <update_columns> [WHEN <condition>] [YIELD <columns>]
  • vid is the ID of the vertex to be updated.
  • update_columns is the properties of the vertex to be updated. For example, tag1.col1 = $^.tag2.col2 + 1 means to update tag1.col1 to tag2.col2+1.

    NOTE:  $^ indicates the vertex to be updated.

  • condition is some constraints. Only when the conditions are met, UPSERT is executed successfully. condition supports expression operations.
  • columns is the columns to be returned, YIELD returns the latest updated values.

UPSERT is a combination of UPDATE and INSERT. Use UPSERT VERTEX to update properties on a vertex if it exists or insert a new vertex if it does not exist. The UPDATE VERTEX statement only updates one tag of a vertex at a time.

The performance of UPSERT is much lower than that of INSERT, because UPSERT is a read-modify-write serialization operation at the partition level.

DON'T: DO NOT use UPSERT for scenarios with highly concurrent writes.

  • If the vertex does not exist, a new vertex is created no matter whether the condition in the WHEN clause is met or not. The property columns not specified by the SET statement use the default values of the columns. If there are no default values, an error is returned.
  • If the vertex exists and the WHEN condition is met, the vertex is updated.
  • If the vertex exists and the WHEN condition is not met, Nebula Graph does nothing.

Consider the following example:

nebula> INSERT VERTEX player(name, age) VALUES "player111":("Ben Simmons", 22); -- Insert a new vertex.
nebula> UPSERT VERTEX "player111" SET player.name = "Dwight Howard", player.age = $^.player.age + 11 WHEN $^.player.name == "Ben Simmons" AND $^.player.age > 20 YIELD $^.player.name AS Name, $^.player.age AS Age; -- Do an upsert operation on the vertex.

+-----------------+-----+
| Name            | Age |
+-----------------+-----+
| "Dwight Howard" | 33  |
+-----------------+-----+

// An empty set is returned. Because vertex "player123" does not exist.
nebula> FETCH PROP ON * "player123";
Empty set (Time spent: 3.069/4.382 ms)
nebula> UPSERT VERTEX "player123" SET player.age = $^.player.age + 1;

If the vertex "player123" does not exist and the default value of age is NULL, the player.age of vertex "player123" is NULL. If player.age has a default value, the player.age of vertex "player123" is the default value plus one.

nebula> CREATE TAG person(followers int, age int DEFAULT 0); -- Create example tag person

nebula> UPSERT VERTEX "300" SET person.followers = $^.person.age + 1,  person.age = 8; -- the number of followers is 1, age is 8

nebula> UPSERT VERTEX "300" SET person.age = 8, person.followers = $^.person.age + 1; -- the number of followers is 9, age is 8
Last update: February 4, 2021
Back to top