Overview

The upsert() statement allows for (1) the updating of existing nodes, or (2) the insertion of new nodes and edges within a single schema in a graphset.

// Updates or inserts nodes
upsert().into(@<schema>).nodes([
  {<property1?>: <value1?>, <property2?>: <value2?>, ...},
  {<property1?>: <value1?>, <property2?>: <value2?>, ...},
  ...
])

// Inserts edges
upsert().into(@<schema>).edges([
  {<property1?>: <value1?>, <property2?>: <value2?>, ...},
  {<property1?>: <value1?>, <property2?>: <value2?>, ...},
  ...
])

The updating feature applies only to nodes and takes effect when an existing _id value is provided in the property specification. When a node is updated:

• Provided custom property values will replace current values, while the values of missing custom properties remain unchanged.
• The _uuid and _id values remain unchanged.

A new node is inserted when a new _id value is provided, or when it is missing. Node _id values will be generated by the system if not provided.

A new edge is always inserted when the properties _from and _to (or _from_uuid and _to_uuid) are provided to specify its source and destination nodes.

During insertion, each provided property will be assigned its given value, while any missing custom properties will default to null. Node and edge _uuid values are always generated by the system and cannot be manually assigned.

Example Graph

To create the graph, execute each of the following UQL queries sequentially in an empty graphset:

create().node_schema("user").edge_schema("follow")
create().node_property(@user, "name").node_property(@user, "age", int32).edge_property(@follow, "time", datetime)
insert().into(@user).nodes([{_id:"U001", name:"Jason", age:30}, {_id:"U002", name:"Tim"}, {_id:"U003", name:"Grace", age:25}, {_id:"U004", name:"Ted", age:26}])
insert().into(@follow).edges([{_from:"U004", _to:"U001", time:"2021-9-10"}, {_from:"U003", _to:"U001", time:"2020-3-12"}, {_from:"U004", _to:"U002", time:"2023-7-30"}])

Updating or Inserting Nodes

To update or insert nodes into @user:

upsert().into(@user).nodes([
  {_id: "U001", name: "John"},
  {_id: "U005", name: "Alice"},
  {age: 12}
]) as n
return n{*}

• First node: The provided _id U001 already exists in the graph, so the corresponding node is updated.
• Second node: The provided _id U005 is new, so a new node is inserted.
• Third node: _id is not provided, so a new node is inserted.

Result: n

Inserting Edges

To insert two edges into @follow:

upsert().into(@follow).edges([
  {_from: "U004", _to: "U001", time: "2021-10-3"},
  {_from: "U001", _to: "U002"}
])

This is equivalent to the following insert() query:

insert().into(@follow).edges([
  {_from: "U004", _to: "U001", time: "2021-10-3"},
  {_from: "U001", _to: "U002"}
])