graph
batch_write
Apply graph mutations atomically.
db.graphs.batch_write(graph: 'str', operations: 'list') -> 'Any'wire graph_batch_write
Applies a list of graph operations - `upsert_node`, `delete_node`, `upsert_edge`, `delete_edge` - in one engine commit. Validation failures (bad ids, missing edge endpoints, frozen-ontology violations) reject the whole batch; nothing is partially applied. The response reports one positional item result per operation, all sharing the same commit receipt.
This whole-batch atomicity is deliberate, and differs from the itemwise `kv`, `json`, and `event` batch writes (where the valid items of a mixed batch still commit and the invalid one carries a typed per-item error). A graph batch mixes node and edge upserts, and an edge references its endpoint nodes, so applying only the valid items could leave an edge pointing at a node that never landed. Rejecting the whole batch keeps graph references consistent - referential integrity is the reason the graph channel is atomic where its siblings are itemwise.
Atomic batches validate every operation up front and apply all of them in one engine commit, or none at all. The response still reports one positional item result per operation; all item results share the same commit receipt.
To see the complete help for this command, run:
help(db.graphs.batch_write)
Example
Apply several node and edge mutations in one atomic commit.
_ = db.graphs.create("g")_ = db.graphs.batch_write("g", [{"type": "upsert_node", "node_id": "a", "data": {"object_type": "person"}}, {"type": "upsert_node", "node_id": "b", "data": {"object_type": "person"}}, {"type": "upsert_edge", "src": "a", "edge_type": "knows", "dst": "b", "data": {}}]) # All operations land in one engine commit, or none do.db.graphs.meta("g").node_count
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| graph | string | yes | Graph name. |
| operations | array | yes | Batch operations. |
| branch | string or null | no | Target branch. Defaults to the executor handle branch. |
| space | string or null | no | Target product space. Defaults to `"default"`. |
Returns
BatchResult<GraphBatchItemResult>
- dataobject
Shared batch response wrapper for all public batch commands.
- typestring
Errors
Recover by code. Retry policy and commit outcome come from the shipped error registry.
| Code | Retry | Commit outcome |
|---|---|---|
| failed_precondition.engine.runtime_closed | never | not_started |
| not_found.engine.branch | never | not_applicable |
| invalid_argument.engine.product_space | never | not_started |
| invalid_argument.engine.graph_name | never | not_started |
| not_found.engine.graph | never | not_applicable |
| invalid_argument.engine.graph_batch | never | not_started |
| invalid_argument.engine.graph_node_id | never | not_started |
| invalid_argument.engine.graph_edge_type | never | not_started |
| invalid_argument.engine.graph_edge_endpoint | never | not_started |
| failed_precondition.engine.graph_ontology_node_type | never | not_started |
| failed_precondition.engine.graph_ontology_edge_type | never | not_started |