Command upsert() will either insert one or multiple nodes/edges into the current GraphSet, or update property values (except ID) of one or multiple existing nodes/edges based on ID.

upsert() may trigger:

• an insert operation if:
  • ID is not provided
  • the provided ID does not exist in the graph
• an update operation if:
  • the provided ID exists in the graph, and matches with schema
• a failure if:
  • the provided ID exists in the graph, but does not match with schema
  • FROM or TO is not provided when inserting edges
  • provided FROM or TO does not exist in the graph

When insert operation is triggered: same with insert().

When update operation is triggered:

• the missing custom properties will remain unchanged
• the custom properties provided in the wrong data type will be using default value

It is not suggested to execute upsert operation after streaming return of an algorithm, see details on stream() in document Ultipa Graph Analytics & Algorithms - Using Algorithms - Execution Method.

Syntax:

• Statement alias: supported (NODE or EDGE)

// To upsert nodes of a certain schema in the current graphset
upsert().into(@<schema>)
  .nodes([				// Square brackets can be omitted if upsert only one node
    {<property1>:<value1>, <property2>:<value2>, ...},
    {<property1>:<value1>, <property2>:<value2>, ...},
    ...
  ])
  
// To upsert edges of a certain schema in the current graphset, must carry _from and _to, or must carry _from_uuid and _to_uuid
upsert().into(@<schema>)
  .edges([				// Square brackets can be omitted if upsert only one edge
    {<property1>:<value1>, <property2>:<value2>, ...},
    {<property1>:<value1>, <property2>:<value2>, ...},
    ...
  ])

Sample graph: (to be used for the following examples)

create().node_schema("account").edge_schema("follow")
create().node_property(@account, "name").edge_property(@follow, "time", datetime)
insert().into(@account).nodes([{_id:"U001", _uuid:1, name:"Jason"}, {_id:"U002", _uuid:2, name:"Tim"}, {_id:"U003", _uuid:3, name:"Grace"}, {_id:"U004", _uuid:4, name:"Ted"}])
insert().into(@follow).edges([{_uuid:1, _from_uuid:4, _to_uuid:1, time:"2021-09-10"}, {_uuid:2, _from_uuid:3, _to_uuid:2, time:"2020-03-12"}, {_uuid:3, _from_uuid:4, _to_uuid:2, time:"2023-07-30"}])

Example: Insert 3 nodes into @account, one does not carry any information, namely, the _id and _uuid will be generated and all custom properties are null; the other two provide IDs matching with schema, but one carries no property which will not change, while the other carries a property with wrong type that will be set to default value (empty string)

upsert().into(@account).nodes([{}, {_id: "U001"}, {_id: "U002", name: [1,2,3]}]) as nodes
return nodes{*}

|           _id          | _uuid |  name  |
|------------------------|-------|--------|
| ULTIPA8000000000000001 |   5   |  null  |
| U001                   |   1   | Jason  | 
| U002                   |   2   |        |

Example: Prompt error when upserting node due to that ID does not match with schema

upsert().into(@card).nodes({_id: "U003", name: "Jack"}) as nodes
return nodes{*}

The schema: card does not match with U003!

Example: Prompt error when upserting edge due to that FROM/TO not provided

upsert().into(@follow).edges({_uuid: 1, time: "2021-08-31"}) as edges
return edges{*}

_from_uuid must > 0!