# Mutations and Loads

Mutation statements live inside a named `.gq` query. Run them with `omnigraph mutate`.

```graphql
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

```graphql
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](/content/docs/queries-search/queries.md#boolean-expressions-and-nulls/index.html)):
`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`:

```graphql
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 `
