mirror of
https://github.com/ModernRelay/omnigraph.git
synced 2026-06-15 01:55:13 +02:00
612741b387
Content build-out on top of the Phase 1 topic move. No behavior changes. Splits (existing content relocated, cross-linked): - queries/index.md → mutations/index.md (insert/update/delete + the inserts-vs-deletes rule) and search/index.md (the multi-modal search functions + a hybrid-ranking overview tying nearest/bm25/rrf together). queries/index.md now covers the read shape and points at both. - branching/index.md → branching/time-travel.md (snapshots/time travel) and branching/merge.md (three-way merge + the 7 conflict kinds, verified against error.rs MergeConflictKind). New pages (written from the code, user-facing): - quickstart.md — init → load → query → branch, with verified CLI flags. - concepts/index.md — what OmniGraph is + the L1/L2 (Lance/OmniGraph) framing. Expanded operations/audit.md from a 7-line struct dump into a real actor-tracking page (server token-resolved vs CLI --as chain; reading the trail; the omnigraph:recovery reserved actor). Index wiring: docs/user/index.md and AGENTS.md's topic table link every new page; also normalized AGENTS.md's docs/user link display text to match the Phase 1 retargeted paths. Verified: zero broken .md links; check-agents-md.sh green (57 links, 54 docs). Deferred to Phase 3: de-dev polish (grammar paths, IR internals still in queries/branching), guides/, and a possible reference/config.md split (the config schema is already coherent in cli/reference.md). Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
52 lines
2 KiB
Markdown
52 lines
2 KiB
Markdown
# Mutations
|
|
|
|
Write statements live inside a `query` declaration whose body is one or more
|
|
mutation statements (the [query language](../queries/index.md) covers the read
|
|
shape and shared declaration syntax).
|
|
|
|
```
|
|
query onboard($name: String, $title: String) {
|
|
insert Person { name: $name, title: $title }
|
|
}
|
|
```
|
|
|
|
An edge type is inserted the same way — its endpoint columns are just
|
|
properties in the assignment block (`insert WorksAt { person: $p, org: $o }`).
|
|
|
|
## Statements
|
|
|
|
- `insert <Type> { prop: <value>, … }`
|
|
- `update <Type> set { prop: <value>, … } where <prop> <op> <value>`
|
|
- `delete <Type> where <prop> <op> <value>`
|
|
|
|
`<value>` is a literal, `$param`, or `now()`.
|
|
|
|
## Atomicity
|
|
|
|
A change query publishes **one commit** at the end of the query. Multiple
|
|
insert/update statements accumulate in memory and commit together — a mid-query
|
|
failure leaves the graph untouched. See [transactions](../branching/transactions.md)
|
|
for the per-query atomicity contract and [branches](../branching/index.md) for
|
|
multi-query workflows.
|
|
|
|
## Inserts/updates and deletes cannot mix in one query
|
|
|
|
A single change query must be **either insert/update-only or delete-only**.
|
|
Mixing the two is rejected at parse time, before any I/O:
|
|
|
|
> `mutation '<name>' on the same query mixes inserts/updates and deletes; split
|
|
> into separate mutations: (1) inserts and updates, then (2) deletes.`
|
|
|
|
Run two separate queries instead — the inserts/updates first, then the deletes.
|
|
The restriction exists because inserts/updates and deletes commit through
|
|
different paths today, and mixing them in one query creates ordering hazards
|
|
(e.g. a same-row insert-then-delete, or a cascading delete of a just-inserted
|
|
edge). Keeping the two kinds in separate queries keeps each one atomic and
|
|
correct.
|
|
|
|
## Bulk loading
|
|
|
|
For loading data from files rather than inline statements, use
|
|
[`omnigraph load`](../cli/index.md) (`--mode overwrite|append|merge`) — it is the
|
|
single bulk-write command and applies the same schema validation and atomic
|
|
publish as inline mutations.
|