Upsert Data

The POST /graph/{graph_name} endpoint is the most important API for real-time data ingestion. It handles Upserts (Update or Insert) for both vertices and edges in a single request.

1. Request Structure

The payload is a nested JSON object where data is grouped by type.


jsonterminal
{
  "vertices": {
    "User": {
      "id1": { "age": { "value": 25 } }
    }
  },
  "edges": {
    "User": {
      "id1": {
        "Liked": {
          "User": {
            "id2": { "weight": { "value": 5.0 } }
          }
        }
      }
    }
  }
}

2. Advanced Operation Codes

Instead of just setting values, you can apply logic during the upsert:

Op Code	Name	Action
`+`	`add`	Adds the payload value to the existing attribute value.
`>`	`max`	Keeps the higher of the new value or existing value.
`<`	`min`	Keeps the lower of the new value or existing value.
`~`	`ignore_if_exists`	Only writes if the vertex/edge is new.

3. URL Parameters

Parameter	Default	Description
`ack`	`all`	Returns only after all cluster instances acknowledge the write.
`new_vertex_only`	`false`	Skips updates to existing vertices.
`vertex_must_exist`	`false`	Rejects edges if the endpoints don't already exist.

4. Multi-Edges & Discriminators

In TigerGraph 4.2+, you can upsert multiple edges between the same two vertices using a JSON array if the edge has a Discriminator.


jsonterminal
{
  "edges": {
    "User": {
      "id1": {
        "Liked": {
          "User": {
            "id2": [
              { "actionId": { "value": "uuid-1" }, "weight": { "value": 1.0 } },
              { "actionId": { "value": "uuid-2" }, "weight": { "value": 2.0 } }
            ]
          }
        }
      }
    }
  }
}

5. Atomicity

By default, RESTPP upserts are non-atomic (partial failures are possible). To ensure all-or-nothing writes, include the following header:

gsql-atomic-level: atomic

[!CAUTION] Atomic writes incur a performance penalty. Use them only when strict consistency is required for a single transaction.