Mutations

Mutations change the data inside an Omnigraph repository. 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 ./my-graph \
    --query mutations.gq \
    --name add_person \
    --params '{"name": "Alice", "age": 30}'

Mutations can target a specific branch with --branch:

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

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.