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

When executing upsert():

• An insert operation is triggered if ID is not provided, or the provided ID does not exist in the graph;
• An update operation is triggered if the provided ID already exists in the graph, and the mapping of node _id and _uuid, the mapping of ID and schema are not violated;
• Cases of failure: the mapping of node _id and _uuid or the mapping of ID and schema are violated; FROM or TO not provided when inserting or updating edges, or provided but the nodes they represent do not exist in the graph.

When insert operation is triggered by upsert(): same details as insert().

When update operation is triggered by upsert():

• Find metadata to be updated based on IDs that are provided;
• Custom properties provided in the correct data type will be updated;
• Custom properties provided in the wrong data type will be updated as empty string (for string, text, datetime), 0 (for int32, int64, uint32, uint64, float, double), or "1970-01-01 08:00:00 +08:00" (for timestamp);
• Custom properties that are not provided, will not be changed.

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>, ...},
    ...
  ])

Example: Given an account U001 with name "test", update the account if it already exists, otherwise insert the account; check the account information after the operation

upsert().into(@account)
  .nodes({_id: "U001", name: "test"}) as nodes
return nodes{*}

Example: Update transaction edge of UUID = 1 with transaction No. TRX001 and from C001 to C003, or insert such an edge if not existing; insert another transaction edge with No. TRX003 and from C003 to C001 in the same UQL

upsert().into(@transaction)
  .edges([
  	{no: "TRX001", _from: "C001", _to: "C003", _uuid: 1},
  	{no: "TRX003", _from: "C003", _to: "C001"}
])