Overview

The insert().overwrite().into() clause facilitates either the overwriting of existing nodes or edges within a single schema or the insertion of new nodes or edges.

Syntax

// Overwrite or insert nodes
insert().overwrite().into(@<schema>).nodes([
  {<property1>: <value1>, <property2>: <value2>, ...},
  {<property1>: <value1>, <property2>: <value2>, ...}
])

// Overwrite or insert edges
insert().overwrite().into(@<schema>).edges([
  {<property1>: <value1>, <property2>: <value2>, ...},
  {<property1>: <value1>, <property2>: <value2>, ...}
])

• Specify one schema in the into() method.
• Include one or multiple nodes or edges in the nodes() or edges() method.
  • Provide key-value pairs of properties for each node or edge enclosed in { }.
  • If there is only one node or edge, the outer [ ] can be omitted.
• Allow to define an alias for the clause, with the data type being either NODE or EDGE.

When a node or edge is overwritten:

• A targeted node is specified by its _id and/or _uuid. A targeted edge is specified by its _uuid, _from and _to (or _from_uuid and _to_uuid)
• The values of provided custom properties will be overwritten; the values of missing custom properties will be null.
• The values of system properties (_id, _uuid, _from, _to, _from_uuid, _to_uuid) remain unchanged.

A new node is inserted when new _id or _uuid is provided, or when both _id and _uuid are missing.

A new edge is inserted when new _uuid is provided, or when _uuid is missing.

Example Graph

Run these UQLs row by row in an empty graphset to create this graph:

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", _uuid:1, name:"Jason", age:30}, {_id:"U002", _uuid:2, name:"Tim"}, {_id:"U003", _uuid:3, name:"Grace", age:25}, {_id:"U004", _uuid:4, name:"Ted", age:26}])
insert().into(@follow).edges([{_uuid:1, _from_uuid:4, _to_uuid:1, time:"2021-9-10"}, {_uuid:2, _from_uuid:3, _to_uuid:2, time:"2020-3-12"}, {_uuid:3, _from_uuid:4, _to_uuid:2, time:"2023-7-30"}])

Examples

Overwrite or Insert Nodes

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

• The first node with the provided _id U001 exists in the graph, so it is overwritten.
• The second is a new node to be inserted, as the provided _id U005 does not exist in the graph.
• The third is a new node to be inserted, as both _id and _uuid are missing.

Result:

Overwrite or Insert Edges

insert().overwrite().into(@follow).edges([
  {_uuid: 1, _from: "U004", _to: "U001"},
  {_uuid: 4, _from: "U002", _to: "U003"},
  {_from: "U002", _to: "U001", time: "2023-9-6"}
]) as e
return e{*}

• The first edge with the provided _uuid 1, _from U004, and _to U001 exists in the graph, so it's overwritten.
• The second is a new edge to be inserted, as the provided _uuid 4 does not exist in the graph.
• The third is a new edge to be inserted, as _uuid is missing.

Result:

Common Reasons for Failures

• Overwriting fails when the specified existing nodes or edges do not belong to the given schema.
• Node overwriting or insertion fails when both _id and _uuid are provided, one of their values exists in the graph while the other one does not.
• Node overwriting or insertion fails when _id and _uuid are provided, they both exist in the graph but they don't match.
• Edge overwriting or insertion fails when the start or end node is not specified.
• Edge overwriting or insertion fails when the specified start or end node does not exist in the graph.
• Edge overwriting fails when the given existing _uuid does not match the given start and end nodes.