Mutations and Loads | Omnigraph

Mutations and Loads

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

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 "commit": null. Load JSON responses use the same exact receipt.

For a multi-command workflow, use a branch as isolated staging. Earlier changes remain committed on that branch; merging makes the resulting branch state visible on the target in one atomic step. See Branches, Commits, and History.

Insert and update identity

All declared value, uniqueness, endpoint, and cardinality constraints are checked before publication; a node a @card minimum needs edges for arrives with them in one query or load ( edge cardinality).

Bulk loading

omnigraph load accepts newline-delimited JSON. One file can contain nodes and edges of several types:

{"type":"Person","data":{"email":"ada@example.com","display_name":"Ada"}}
{"type":"Company","data":{"slug":"acme","name":"Acme"}}
{"edge":"WorksAt","from":"ada@example.com","to":"acme","data":{"role":"Engineer"}}

Here, Person.email and Company.slug are single-property String keys, so their derived ids are exactly ada@example.com and acme. The edge uses those ids in from and to.

A Date value is an integer day count since 1970-01-01 or a YYYY-MM-DD string; a DateTime value is an integer millisecond count since the Unix epoch or an ISO 8601 string. Any other JSON type (a float such as 19723.0, a boolean, an object) fails the load with invalid Date value or invalid DateTime value naming the property. A Date string carries no time of day: "2024-01-01T02:00:00+05:00" fails the load with invalid Date literal, as it does in a mutation param, a date(...)literal, or a read filter; an instant belongs in aDateTimeproperty. ADateTimeholds milliseconds: a string with a non-zero digit past the third fractional digit, such as"2024-01-01T00:00:00.123456Z" fails the load with invalid DateTime literal, as it does in a mutation param, a datetime(...) literal, or a read filter. Trailing zeros, as in .123000, are accepted.

Choose the mode explicitly:

Mode Existing id Use
append Fails with key_conflict Add entities without replacing anything.
merge Updates the existing entity Upsert a batch.
overwrite Replaces every node or edge type represented in the batch; types absent from the batch remain unchanged Rebuild from a complete export or seed.
omnigraph load --data batch.jsonl --mode merge --target ./graph.omni

One load request is one graph commit. Use --branch <name> --from <base> to create a missing review branch and load onto it in the same workflow.

Loads preserve supplied embeddings and do not generate them. Results report embedding_generation: "unsupported" when a loaded node type declares @embed, or null otherwise; see Embeddings.

CSV loading

The load csv statement reads one CSV object into one declared node or edge type, with every cell typed by the .pg declaration. It is a GQ statement, so it runs wherever a branch create statement runs: omnigraph mutate -e, a .gq file, or POST /mutate with the request branch as its target (main when omitted). It is the one CSV surface: omnigraph load reads JSONL only.

load csv "s3://imports/person.csv" into node:Person mode append delimiter "|" header
load csv "s3://imports/knows.csv" into edge:Knows mode append delimiter "|" header columns (from, to, creationDate)

Numbers are typed by the reader. Bool takes exactly true or false. Date and DateTime cells are read as text and pass the checks above before conversion: 2024-01-01T02:00:00+05:00 in a Date column and 2024-01-01T00:00:00.123456Z in a DateTime column fail the load exactly as they fail a JSONL load, and a numeric offset without a colon, as LDBC writes it (2010-02-14T15:32:10.447+0000), stores the instant. List, Vector and Blob properties have no CSV encoding: a column mapped to one is refused with the kind named; an unmapped one stores null when nullable.

Float values must be finite and representable by their declared F32 or F64 type; NaN, infinity and overflow refuse the load. Each decoded batch is held against the statement's query_memory_bytes allowance before it is retained, and each staged-write input against write_max_bytes.

Node ids derive from the @key as in a JSONL load; an edge's from and to are the canonical ids of its endpoints, so a single-property integer key is written as its decimal value. The statement never forks a branch.

The source is a URI the engine reads under the graph's external Blob policy ( External Blob references): s3:// objects beneath a configured base, and for an embedded run file:// paths beneath an embedded_only base. A graph with no policy denies every source; a URI outside every base, an unsupported scheme, and an object over the load_source_max_bytes setting (default 32 MiB) are refused before any byte is read, and every read of the object (each range an overwrite's partition reads, or the one read of an append or merge) is bounded by a 120-second deadline. A refused source names csv_source_bytes; raising the setting in the statement's set prefix (or the request's settings field) admits a larger object. A direct omnigraph mutate run installs an embedded-only base over a file:// source's directory for that statement, so the file is admitted by the same rule; a served run refuses a file:// source, since the server reads only what it may reach.

explain before a load csv statement prints the load's plan, the same document a query's explain prints: the source, the one validation with each check and its access path, and the write. An overwrite runs that plan; append and merge run the keyed adapters. It reads the source's metadata and no payload byte.

CLI and HTTP requests

omnigraph mutate --target ./graph.omni -e 'load csv "file:///data/person_0_0.csv" into node:Person mode append delimiter "|" header'
omnigraph mutate --target dev -e 'load csv "s3://imports/knows.csv" into edge:Knows mode append delimiter "|" header'

The CLI uses --branch; HTTP uses the request branch, with main as the omitted default. The statement accepts no name, params or commit precondition (--if-commit or Omnigraph-If-Graph-Commit). It requires change on the branch. A source that holds no records is refused. The response is a mutation's ChangeOutput: the branch, load csv as query_name, loaded node and edge counts, the commit, and for mode overwrite an executed object, what the load's plan measured as it ran.

curl -sS http://localhost:8080/graphs/knowledge/mutate \
  -H 'Omnigraph-Http-Api: 0.14' \
  -H 'authorization: Bearer secret-a' \
  -H 'content-type: application/json' \
  -d '{"query":"load csv \"s3://imports/person.csv\" into node:Person mode append delimiter \"|\" header","branch":"main"}'

The HTTP body carries the statement; the server reads its source under the graph's external_blobs.allow policy, with server-safe bases only. Before fetching, workload admission reserves the request's load_source_max_bytes (default 32 MiB) plus the statement bytes against both global and per-actor budgets, so a raised setting must still fit the server's own limits. This reservation lasts until the write settles, including when the HTTP caller disconnects.

Limits and conflicts

Insert/update mutations and incremental keyed loads are bounded to 8,192 entities per touched type. The write_max_bytes setting (default 32 MiB) bounds retained row data per type and across all touched types. Blob payloads have a separate allowance of the same size, including inline bytes, copied external bytes and carried update values. Every version of a key written in one mutation counts, so an insert and an update of the same row charge its Blob twice.

Keyed loads also bound their parser estimate independently. A strict JSONL load retains its projected input check, strict_input_arrow_bytes. A vector counts its full width (dimension × 4 bytes), present or null: 12 KiB for Vector(3072). A CSV load has no whole-statement input check; it applies write_max_bytes to each staged-write input instead. An overwrite stages the reader's 8,192-row batches, and a batch over the allowance refuses as staged_write_input_bytes. An overwrite writes a fragment per parse partition, up to 1 Mi rows each, as the rows drain; nothing commits before the publish, a refusal deletes them all. An append or merge keeps the keyed adapter's ceilings (retained keyed batch bytes per operation, keyed entities for <table>, keyed entity bytes for <table>).

The query_memory_bytes setting bounds one load csv statement's tracked memory as a whole: the retained source, every decoded batch, validation state and the staging working set; a streaming overwrite's working set is its open fragments and the writers in flight. An overwrite admits that memory once, before any partition reads, one share per parse partition that only its own reader charges, so a refusal and its actual (the smallest admitting limit) are the same on every run (the shares: the settings reference); a statement it cannot hold refuses before any fragment write.

Blobs

Blob assignments accept managed base64: data and, when allowed by graph policy, external URI references. Ownership differs by load mode, and Blob bytes count toward write limits. See the canonical Blob guide before loading them, and its limits for the bounds that apply.

Conditional mutations

A mutation can be made to apply only to the graph state the caller read, with --if-commit; see conditional mutations.