Mutations

Mutations change the data inside an Omnigraph graph. Every mutation runs inside a transaction on a single branch and is validated against the compiled schema before it commits.

There are three mutation operations:

Where mutations live

Mutations are written as named operations in .gq files alongside your queries:

query add_person($name: String, $age: I32) {
    insert Person { name: $name, age: $age }
}

query complete_task($slug: String) {
    update Task set { status: "completed" }
    where slug = $slug
}

query remove_person($name: String) {
    delete Person where name = $name
}

Running a mutation

Use the change subcommand to execute a named mutation:

omnigraph change --uri ./graph.omni \
    --query mutations.gq \
    --name add_person \
    --params '{"name": "Alice", "age": 30}'

Mutations can target a specific branch with --branch:

omnigraph change --uri ./graph.omni \
    --query mutations.gq \
    --name add_person \
    --params '{"name": "Alice", "age": 30}' \
    --branch feature-x

Multi-statement mutations

A single named mutation can contain any number of insert and update statements. They all commit atomically as one graph commit. Either every statement succeeds or none of them do:

query onboard_customer($email: String, $name: String, $plan: String) {
    insert Customer { email: $email, name: $name, plan: $plan }
    insert Account  { slug: $email }
    insert OwnedBy  { from: $email, to: $email }
}

delete statements cannot be mixed with insert / update in the same mutation. That combination is rejected at execution time, before any I/O, with the message "mutation '<name>' on the same query mixes inserts/updates and deletes; split into separate mutations" (rule D2). If you need to swap an entity in one commit, run the two phases as separate mutations on the same branch and merge.

Constraint enforcement

Every mutation is validated against the schema before it commits. If a constraint is violated -- a missing @key property, a duplicate unique value, or a type mismatch -- the entire mutation is rolled back and an error is returned.