Skip to content

UPSERT EDGE

UPSERT is a combination of UPDATE and INSERT. Use UPSERT EDGE to update properties of an edge if it exists or insert a new edge if it does not exist.

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

Danger

Don't use UPSERT for scenarios with highly concurrent writes. Use UPDATE or INSERT instead.

Syntax

UPSERT EDGE ON <edge_type>
<src_vid> -> <dst_vid> [@rank]
SET <update_prop>
[WHEN <condition>]
[YIELD <properties>]
Field Required Description Example
ON <edge_type> Yes Specifies the type of the edge. The properties to be updated must be on this edge type. ON serve
<src_vid> Yes Specifies the source vertex ID of the edge. "player100"
<dst_vid> Yes Specifies the destination vertex ID of the edge. "team204"
<rank> No Specifies the rank of the edge. 10
SET <update_prop> Yes Specifies the properties to be updated and how they will be updated. SET start_year = start_year +1
WHEN <condition> No Specifies the filter conditions. WHEN end_year < 2010
YIELD <output> No Specifies the output format of the statement. YIELD start_year AS Start_Year

Insert an edge if it does not exist

If an edge does not exist, it is created no matter the conditions in the WHEN clause are met or not, and the SET clause takes effect. The property values of the new edge depends on:

  • How the SET clause is defined
  • The default value of the properties

For example, if:

  • The edge to be inserted will have properties start_year and end_year based on the edge type serve.
  • The SET clause specifies that end_year = 2021.

Then the property values in different cases are listed as follows:

Are WHEN conditions met If properties has default values Value of start_year Value of end_year
Yes Yes The default value 2021
Yes No NULL 2021
No Yes The default value 2021
No No NULL 2021

Here are some examples:

// Check if the following three vertices has any outgoing serve edge.
nebula> GO FROM "player666", "player667", "player668" \
        OVER serve \
        YIELD serve.start_year, serve.end_year;
Empty set

// The result Empty set indicates that the edges don't exist.

nebula> UPSERT EDGE on serve \
        "player666" -> "team200"@0 \
        SET end_year = 2021 \
        WHEN end_year == 2010 \
        YIELD start_year, end_year;
+------------+----------+
| start_year | end_year |
+------------+----------+
| __NULL__   | 2021     |
+------------+----------+

nebula> UPSERT EDGE on serve \
        "player666" -> "team200"@0 \
        SET end_year = 2022 \
        WHEN end_year == 2010 \
        YIELD start_year, end_year;
+------------+----------+
| start_year | end_year |
+------------+----------+
| __NULL__   | 2021     |
+------------+----------+

nebula> UPSERT EDGE on serve \
        "player667" -> "team200"@0 \
        SET end_year = 2022 \
        YIELD start_year, end_year;
+------------+----------+
| start_year | end_year |
+------------+----------+
| __NULL__   | 2022     |
+------------+----------+

nebula> UPSERT EDGE on serve \
        "player668" -> "team200"@0 \
        SET start_year = 2000, end_year = end_year + 1 \
        YIELD start_year, end_year;
+------------+----------+
| start_year | end_year |
+------------+----------+
| 2000       | __NULL__ |
+------------+----------+

In the last query of the preceding example, since end_year has no default value, when the edge is created, end_year is NULL, and end_year = end_year + 1 does not take effect. But if it has a default value, end_year = end_year + 1 in the SET clause will take effect. For example:

nebula> CREATE EDGE serve_with_default(start_year int, end_year DEFAULT 2010);
Execution succeeded

nebula> UPSERT EDGE on serve_with_default \
        "player668" -> "team200" \
        SET end_year = end_year + 1 \
        YIELD start_year, end_year;
+------------+----------+
| start_year | end_year |
+------------+----------+
| __NULL__   | 2011     |
+------------+----------+

Update an edge if it exists

If the edge exists and the WHEN conditions are met, the edge is updated.

nebula> MATCH (v:player{name:"Ben Simmons"})-[e:serve]-(v2) \
        RETURN e;
+-----------------------------------------------------------------------+
| e                                                                     |
+-----------------------------------------------------------------------+
| [:serve "player149"->"team219" @0 {end_year: 2019, start_year: 2016}] |
+-----------------------------------------------------------------------+

nebula> UPSERT EDGE on serve \
        "player149" -> "team219" \
        SET end_year = end_year + 1 \
        WHEN start_year == 2016 \
        YIELD start_year, end_year;
+------------+----------+
| start_year | end_year |
+------------+----------+
| 2016       | 2020     |
+------------+----------+

If the edge exists and the WHEN conditions are not met, the edge does not take effect.

nebula> MATCH (v:player{name:"Ben Simmons"})-[e:serve]-(v2) \
        RETURN e;
+-----------------------------------------------------------------------+
| e                                                                     |
+-----------------------------------------------------------------------+
| [:serve "player149"->"team219" @0 {end_year: 2020, start_year: 2016}] |
+-----------------------------------------------------------------------+


nebula> UPSERT EDGE on serve \
        "player149" -> "team219" \
        SET end_year = end_year + 1 \
        WHEN start_year != 2016 \
        YIELD start_year, end_year;
+------------+----------+
| start_year | end_year |
+------------+----------+
| 2016       | 2020     |
+------------+----------+
Last update: May 10, 2021
Back to top