Skip to main content
Apply a batch of mutations to a graph session object.

​
POST /revisions/:id/data/command (Command: apply_session_graph_mutations)

Mutations are applied atomically in the order listed. Optimistic concurrency is supported per element via if_rev.

​
Request Body

ParameterTypeRequiredDescription
enginestringYesMust be workflow_blobhub.
commandstringYesMust be apply_session_graph_mutations.
session_idstringYesThe ID of the session that owns the graph envelope.
aliasstringYesAlias of the graph session object.
operationsarray of objectYesOrdered list of mutation operations. See operation types below.

​
Mutation Operation Types

Each entry in operations is an object with an op discriminator and op-specific fields:
opRequired fieldsOptional fieldsDescription
add_vertexlabels (non-empty)element_id, props, if_revCreate a new vertex. labels is required and must contain at least one label (labels are immutable afterward). element_id defaults to a server-generated id; props defaults to {}.
add_edgelabel (string), from_id, to_idelement_id, props, if_revCreate a new directed edge. label is the relationship type and is required.
set_vertex_propselement_id, props (object)if_revMerge props into an existing vertex (shallow merge — keys are added/replaced).
set_edge_propselement_id, props (object)if_revMerge props into an existing edge.
remove_vertex_propselement_id, keys (string[])if_revRemove the listed prop keys from an existing vertex.
remove_edge_propselement_id, keys (string[])if_revRemove the listed prop keys from an existing edge.
delete_vertexelement_idif_revDelete a vertex. Also cascades — all incident edges are removed atomically.
delete_edgeelement_idif_revDelete a single edge.
add_vertex requires a non-empty labels list. Labels are set only at creation and are immutable afterward, so there are no label-mutation operations (set_labels, add_labels, remove_labels do not exist). Every operation may optionally include if_rev (integer). If present, the server checks that the current rev of the element matches if_rev before applying the operation. A mismatch aborts the entire batch and returns graph_mutation_conflict (409).

​
Response

ParameterTypeDescription
elementsarray of objectThe current state of every upserted element in this batch (deleted elements are not included).
changesarray of objectChange records — one per affected element. Each entry has op ("upsert" or "delete"), element_id, and type. rev is included for upsert entries.

​
Errors

  • invalid_graph_envelope — the alias does not exist or its value.type is not "graph".
  • invalid_vertex_labels — an add_vertex op omitted labels or supplied only empty/whitespace labels; a vertex must be created with at least one non-empty label.
  • graph_element_too_large — a single element’s serialized props exceed the server-side size cap.
  • graph_mutation_too_large — the total serialized size of the mutation batch exceeds the cap.
  • graph_mutation_conflict (409) — an if_rev check failed; the batch was not applied.

​
Example

{
  "engine": "workflow_blobhub",
  "command": "apply_session_graph_mutations",
  "session_id": "sess_001",
  "alias": "task_graph",
  "operations": [
    {
      "op": "add_vertex",
      "element_id": "task:1",
      "labels": ["task"],
      "props": { "title": "Research", "status": "open" }
    },
    {
      "op": "add_vertex",
      "element_id": "task:2",
      "labels": ["task"],
      "props": { "title": "Write report", "status": "open" }
    },
    {
      "op": "add_edge",
      "element_id": "e:1",
      "label": "depends_on",
      "from_id": "task:2",
      "to_id": "task:1",
      "props": {}
    },
    {
      "op": "set_vertex_props",
      "element_id": "task:1",
      "if_rev": 1,
      "props": { "status": "in_progress" }
    }
  ]
}

​
See also