mutations.md
Mutations and Loads
Mutation statements live inside a named .gq query. Run them with omnigraph mutate.
query hire($person_id: String, $company_id: String, $role: String) {
insert WorksAt {
from: $person_id,
to: $company_id,
role: $role
}
}
Edge endpoints use the reserved assignments from and to; their values are the logical ids of existing endpoint nodes.
Statements
insert Person { email: $email, display_name: $name }
update Person set { display_name: $name } where email = $email
delete Person where email = $email
A where on update or delete takes the same expressions as a read filter (see Boolean expressions and nulls):
and, or, not, parentheses, the six comparisons, starts_with, contains, in, is null and is not null. Its operands are the target type's properties, named bare, the system fields @id, @src and @dst, literals, parameters, and now(); from and to stay accepted for @src and @dst. It keeps only the rows whose expression is true. On four Knows edges, ab1 and ab2 from a to b, ac, and db:
query exact() { delete Knows where @src = "a" and @dst = "b" }
removes ab1 and ab2 and nothing else: affected: nodes=0 edges=2. A binding variable in a where is refused at compile time (T14); an aggregate, search, or ranking call is T44, for example T44: `count` cannot appear in a mutation where; a where compares the row's own properties, parameters and now(). A compound where runs under either engine setting. A where that tests over four properties twice each with =, != or in is refused.
Assignment values are constants: literals, parameters, now(), and comparisons or Boolean operators over them, such as adult: true or $flag. A constant's value is fixed per invocation: parameters and now() are bound once before any retry, so a retried mutation computes the same value. It follows the read rules for null: with $flag null, true or $flag is true and false and $flag is false, and $age > 30 with $age null is null. A null result assigned to a nullable property writes null; on a Blob property it clears the cell. null is a reserved word, so clear a Blob through a nullable parameter such as $content: Blob?. Assigned to a non-nullable property a null result is refused with a typed error that names the property, never written as a default. A property or system field in a value is refused, for example T45: `age` cannot appear in an assignment value; assignments and binding matches are constants per invocation.
A mutation query may contain several inserts and updates, or several deletes, but it cannot mix inserts or updates with deletes. Split that workflow into two queries, or run the queries on a branch and merge when the combined result is ready.
Atomicity
An effectful mutation query publishes one graph commit. All of its statements become visible together, or none do. Separate mutation commands are separate commits, even when they run consecutively.
With --json, a successful effectful mutation returns commit with the exact graph_commit_id and commit metadata published by that attempt. A successful mutation that matches no entities publishes no commit and returns `