Conditional mutations | Omnigraph

Conditional mutations

The condition compares the effective head of the target branch.

Use --if-commit when a mutation should apply only to the graph state that the caller read:

# The JSON response includes the commit pinned for these rows.
omnigraph query find_person --query queries.gq --target ./graph.omni --json

omnigraph mutate update_person --query queries.gq --target ./graph.omni 
  --params '{"name":"Ada"}' 
  --if-commit <graph_commit_id> --json

The condition compares the effective head of the target branch. Any intervening commit invalidates it, including a commit that changed an unrelated entity or type. On mismatch, nothing is written: the CLI exits with code 4 against a server and with code 1 on an embedded graph such as this --target run, and JSON output contains precondition_failure with expected and optional actual commit ids. Re-read the branch and decide again; do not blindly retry the old mutation. The precondition is still checked when the mutation would match no entities.

Use the graph_commit_id returned with the original query rows. Fetching a head id afterward creates a race between the read and the precondition. For the HTTP header and dedicated conditional routes, see the HTTP server guide.

[Mutations and Loads

Mutation statements live inside a named .gq query. Run them with omnigraph mutate.](/content/docs/queries-search/mutations/index.html) [Search

OmniGraph combines vector, full-text, and graph patterns in one .gq query.](/content/docs/queries-search/search/index.html)