Operating Omnigraph
This skill captures the operational rules for working with a locally or remotely deployed Omnigraph. Follow them when authoring schema, writing queries, loading data, evolving schema, or automating graph operations.
Check
and the command's
before using these
instructions. This skill tracks the current CLI/server contract, including
; older HTTP contracts are unsupported, and a
request across contracts is refused with
before any
effect. The engine
reports
internal-schema 17 (serves v14 to v17)
: the storage format of a
graph it creates, then the range it serves. A v14 or v15 branch is served as
it is and stamped v16 by its first publication; no publication stamps a
branch v17, only the offline
does. New graphs use
/
/
system columns; a graph
that already spells them
/
/
keeps its physical columns. A
standalone v8, v9 or v13 graph is converted in place by the offline
; any other format is rebuilt by export and load. See
converting a graph.
Read
migration guidance before replacing a
deployed binary.
An
binary that has the
command carries the copy of this
skill written for it:
omnigraph skill export <dir> --force
writes it where
your agent loads skills, and
omnigraph skill show [<path>]
prints one file.
Prefer that copy when the installed CLI differs from the one this copy was
written for (see
version-matched skill).
Edge selections in traversal
selects named edge types;
selects compatible
types from the captured schema and requires declared endpoint node types.
Omitted bounds always mean
; recursive traversal needs finite bounds
such as
, and a bound above one (like undirected traversal) needs the
same node type at both ends:
over
is
refused with
.
binds one-hop concrete edges, exposing
and
. Common properties must exist with compatible base types
on every member; nullability and enum domains widen.
set traversal_work_limit = 1000000;
controls shared traversal row work in
statements using selections. Full selected-table sizes count before scans, even
for selective neighborhoods. A result limit cannot replace this cap. Exhaustion
terminates the query with an error; received rows do not become partial success.
On a server a request cannot raise it past the server's ceiling (the larger of
its process default and 1000000); ask the operator to raise
OMNIGRAPH_TRAVERSAL_WORK_LIMIT
instead.
Historical wildcard targets are refused. Stored-query validation can refuse a
schema addition that would invalidate a wildcard common-property reference.
See
traversal and
session settings.
The Seven Rules
- Lint before commit —
omnigraph lint --schema schema.pg --query queries/foo.gq
validates both sides against each other. No running repo required.
- Plan before apply — never run without a successful first. Apply is destructive; plan is free. (Cluster mode has the same rule with different verbs: before — the plan embeds the engine's real migration steps.)
- Branches are for data; apply is for schema — review bulk data loads on a feature branch then merge. Schema changes go straight to : in cluster mode edit the and run (a server target deploys without restart; a direct root target requires stopped serving; a direct refuses a cluster-managed graph); for the managed service commit,
cluster push --target managed
, cluster plan --target managed --rev <rev>
, then cluster apply --target managed --plan <preview-id>
; / is for a non-cluster store.
- Pick the right write command — for edits (typechecked, parameterized); for bulk JSONL, local or remote, with a required ( upsert · strict-insert · replaces only the node/edge types represented in the batch). forks a review branch in one shot; bare needs an existing target branch.
- Parameterize everything — never string-interpolate values into bodies or . Declare and pass via .
- Expose agent reads as aliases — aliases decouple a read operation name
from its stored-query implementation. Aliases are read-only; invoke a served
stored mutation with
omnigraph mutate <name> --target ...
.
- Treat a lost remote response as unknown — an effectful data mutation or load returns its exact commit, but a proxy can return 504 after publication. Branch statements have different outcome/receipt semantics. On timeout, reconcile the intended effect and relevant history before replay. See .
Essentials: Queries, Mutations, Loads
The patterns below cover the daily 80% — enough to write correct
and JSONL without leaving this file. The long tail (multi-hop, negation, aggregations, hybrid search, every decorator) is in
and
.
Comments in and are , never (the #1 parse error).
Read query ()
gq
query get_signal($slug: String) {
match {
$s: Signal { slug: $slug } // inline property filter goes in the match block
$s formsPattern $p // edge FormsPattern declared PascalCase, traversed lowerCamelCase
}
return { $s.slug, $s.name, $p.slug }
}
- Parameterize, never interpolate. Declare in the signature; pass via
--params '{"slug":"sig-foo"}'
. An empty signature still needs parens: .
- Edge traversal is lowerCamelCase even though the schema declares edges PascalCase ( → ).
- System identity uses . Read and /;
bare , , and name declared user properties.
returns an object containing and its non-Blob/non-Vector properties.
reports the graph's physical ; do not
substitute physical names into GQ.
- List/sort by appending
order { $s.stagingTimestamp desc } limit 50
after . Without , may return any valid rows (the subset can change between releases); order for stable pages.
- and require a trailing — omitting it is a compile error. does not require a limit, but use one to keep ranked output bounded. Ranking operators lead , and still restrict rows ( keeps only text matches; skips null vectors). Scope with /filters first, then rank (
order { nearest($d.embedding, $q) } limit 10
). Project a score by repeating the leading key: return { $d.slug, nearest($d.embedding, $q) as distance }
. A ranked read's JSON result carries a object (, , , ); means the cap left vector partitions unsearched, so a nearer row may exist.
Mutation ()
There is
no top-level — every block is a named
; the verb (
/
/
) makes it a write. Dispatch with
(not
). (A source may instead hold exactly one statement:
branch create|delete|merge
and
run through
;
branch list|diff|merge-base
,
and
through
;
through
; see
.)
gq
query add_signal($slug: String, $name: String, $brief: String, $createdAt: DateTime) {
insert Signal { slug: $slug, name: $name, brief: $brief,
stagingTimestamp: $createdAt, createdAt: $createdAt, updatedAt: $createdAt }
}
query link($from: String, $to: String) { insert FormsPattern { from: $from, to: $to } }
query retitle($slug: String, $t: String) { update Signal set { name: $t } where slug = $slug }
query remove($slug: String) { delete Signal where slug = $slug }
- Every non-nullable property must be supplied. Lint normally reports T12
when one is missing. A non-null Vector target carrying
is a known exception: source-only insert can lint successfully even though
execution still requires the vector. Supply it explicitly; writes never
embed automatically.
- A single mutation is insert/update-only or delete-only — never both (D₂ rule, refused at execution before any effect; does not catch it); split them.
- Edge inserts give logical / endpoint IDs; a propertyless edge needs only those, and there is no nested block in GQ. An unkeyed edge insert is strict (inserting twice creates two edges). An edge type may declare
@key(@src, @dst[, prop…])
in its body when created; inserts then upsert by the derived id, and identical inserts on two branches converge on merge. Edges cannot be d (T16).
Bulk load (JSONL)
jsonl
{"type":"Signal","data":{"slug":"sig-foo","name":"Foo","brief":"…","stagingTimestamp":"2026-04-14T00:00:00Z","createdAt":"2026-04-14T00:00:00Z","updatedAt":"2026-04-14T00:00:00Z"}}
{"edge":"FormsPattern","from":"sig-foo","to":"pat-bar","data":{}}
bash
omnigraph load --data seed.jsonl --mode merge --target $GRAPH # --mode is REQUIRED (no default)
omnigraph load --data delta.jsonl --from main --branch review --mode merge --target $GRAPH # fork a review branch in one shot
- : (upsert by logical entity ID; keyed node and keyed edge IDs derive from their tuple — re-running a merge file duplicates unkeyed edges) · (fails on ID collision) · (destructive, staged). forks a missing ; bare needs an existing branch. Works local and remote.
- Date values: use a calendar-day string () for and an ISO timestamp to the millisecond for ( or ; is refused), in both and JSONL. also accepts integer epoch days for .
- CSV is a GQ statement, not an format ( reads JSONL only):
omnigraph mutate --target $GRAPH -e 'load csv "s3://imports/person.csv" into node:Person mode append header'
, with required, optional , and when there is no . The source must lie under the graph's external Blob policy base (a direct run admits its own directory; a served run refuses ) and within (32 MiB default). See CSV loading.
Blob values
A
property is written like any other property in
/
params and JSONL
:
stores managed bytes, another
string stores an external URI (denied unless the graph's
policy admits its base), and
clears an optional cell. Blobs are never
returned by
; read and write one cell directly:
bash
omnigraph blob stat node Document manual content --target $GRAPH --json # kind, size, ETag
omnigraph blob get node Document manual content --target $GRAPH --out manual.pdf
omnigraph blob put node Document manual content --file manual.pdf --if-match '"<etag>"' --target $GRAPH --json
omnigraph blob clear node Document manual content --target $GRAPH --json
/
replace one cell of an existing entity as one commit (
),
with an optional ETag precondition; HTTP is
/
/
/
DELETE /graphs/{graph_id}/blob
. Blob properties cannot be keys, unique, indexed or
lists. See
.
Dispatching
bash
omnigraph alias signal --params '{"slug":"sig-foo"}' # operator alias → its bound stored read query
omnigraph query get_signal --params '{"slug":"sig-foo"}' # served stored query by name (verb asserts read vs write)
omnigraph query -e 'query q() { match { $s: Signal } return { $s.slug } limit 5 }' # ad-hoc/inline (or: --query f.gq <name>)
omnigraph mutate add_signal --query mutations.gq --params '{"slug":"sig-foo","name":"Foo","brief":"Example","createdAt":"2026-04-14T00:00:00Z"}' # name positional; ad-hoc file source
omnigraph lint --schema schema.pg --query queries/foo.gq # after EVERY .gq/.pg edit (no server needed)
grammar
The non-obvious facts that bite, then the full grammar:
- Scalar param types:
String Bool I32 I64 U32 U64 F32 F64 DateTime Date Blob
. Modifiers: (optional), (list), . There is no — use . An integer parameter takes its type's whole range ( up to ); send a 64-bit value above 2^53 in as a decimal string so no client rounds it through a double.
- A read query needs and (/ optional); a mutation has neither — only //.
- takes an integer literal, not a param — , never .
- Variable-hop traversal: — bounds are required to be finite ( is rejected: "unbounded traversal is disabled"), and an edge whose endpoint types differ allows only one hop (). Hops are shortest-path distances; each is a distinct anonymous node; variables beginning are reserved.
- Undirected traversal: matches the edge in either direction, deduplicated (a pair connected both ways appears once). Same-endpoint-type edges only (e.g. ) — asymmetric edges are rejected (T22). Composes with bounds () and correlated blocks (, , ).
- Edge bindings: an optional prefix on the edge word — , undirected — binds the matched edge row, so edge properties work in filters (
$w.confidence = "asserted"
), projections (), aggregates, and ordering. A bound traversal returns one row per edge (parallel edges stay distinct); binding a multi-hop, rebinding a taken name, or projecting bare is rejected (T23).
- Literals & calls: , , , list .
, , , , , , , , , ,
Those are the complete
filter operators (
tests membership in a list parameter or literal); conditions compose with
,
,
, parentheses and
/
, and a filter keeps only rows whose expression is true (a comparison with a null operand is null). String predicates are exact and
case-sensitive.
Aggregates are
(
,
count(distinct $f.city) as cities
);
/
also accept String, Bool, Date, and DateTime. Alias aggregates and order by the alias.
keeps one row per distinct projected tuple.
- Result column names must be distinct (): alias projections that would collide.
- Stored-query metadata: / may follow the param list.
- Casing: type names uppercase-initial (); idents/edges lowercase-initial (); variables -prefixed. and comments only.
The compiler grammar in
crates/omnigraph-compiler/src/query/query.pest
is the
single source of truth.
CLI Reference (condensed)
Select one complete destination with
or the operator
file's
. Every backend invocation prints the resolved target to
stderr; machine results remain on stdout. An unknown or unsupported target
refuses without fallback. Source files and current directories never select a
backend.
is source input only.
- Direct graph: or a registered
kind: direct, scope: graph
entry.
- Direct cluster root:
--target ./cluster --graph knowledge
; registered root targets can set .
- Server:
--target production --graph knowledge
; the registered target owns endpoint and one auth provider.
- Managed: for account operations; a managed target references that profile and pins cluster ID/incarnation. Graph operations need its endpoint and or .
- Direct targets support local files, plus an inline cluster root for
cluster plan/apply/status/force-unlock/upgrade-ledger
and /// while the server is stopped. Each direct writer on the root takes the admission lock and keeps it; once that writer has stopped and its I/O has settled, release its exact (from ) with before the next writer or the server starts. Other cloud-direct, catalogue and Unix socket targets are unsupported. Remote inline URLs must be registered.
Bare target names resolve from the operator file; use
for relative inline
paths.
init --schema schema.pg ./graph.omni
is the sole positional backend
address convenience.
attributes supported direct operations and
names the actor
reports for direct storage;
served targets derive their actor from credentials and send
as the
assertion, refusing a mismatch with
and
exit 4; managed targets refuse it.
supplies explicit
consent for destructive nonlocal operations. There is no quiet switch for the
destination line.
| Family | Operations and applicability |
|---|
| Engine inventory | or catalogue --query file.gq
, optionally ; local, without operator configuration, credentials or storage |
| Data | , , load --mode overwrite|append|merge
, , , , , , , ; direct or served targets |
| Managed data | and common served graph commands, subject to endpoint capabilities and policy; no direct maintenance fallback |
| Direct schema | ; and schema upgrade-system-columns
require standalone graph targets |
| Direct maintenance | , , index rebuild --kind full-text
, ; is standalone and offline |
| Source-only | lint --schema FILE --query FILE
, cluster validate --config DIR
; no backend target |
| Root control | , policy validate/test/explain
, cluster observe/force-unlock/upgrade-ledger
; direct root targets; also reads one served graph |
| Deployment | cluster plan/apply --config DIR
on a direct root or server; uses only the target |
| Managed account | , organization members/invitations
; |
| Managed cluster | cluster members/pull/push/plan/apply/status/operation/history/cancel/token/delete/undo-delete
; complete cluster target |
| Local configuration | config validate/rename-profile/rename-target/recover-rename/recover-operations
, target list/inspect/add/refresh/remove
, , , ; owns its target and graph |
| Authentication | login --create-profile NAME
, , or for platform sessions; credentials set/status/remove/export
requires explicit profile or standalone target |
| Access | access [--branch B [--target-branch T]]
; the actor and the actions the graph's policy grants it, from a server or managed target's access route or, for a direct graph or root target, the installed policy; catalogue targets refuse |
| Agent MCP | mcp --target NAME [--graph G] [--write]
relays an agent's stdio MCP to an existing server or managed target's with that target's credential, bound to one graph, read-only tools unless (the server's policy still decides every call); a cancelled write gets no answer and may still have landed; direct targets refuse |
| Studio | studio --target NAME [--graph G] [--json]
opens Omnigraph Studio on an existing server target through an link and prints it, sending no request; direct and managed targets refuse; without Studio it refuses |
and
invoke stored queries by positional name, or accept
/
. Use
or
, never interpolate
values into query source. Reads support
--format table|json|jsonl|csv|kv|toon
;
encodes the same document as
in TOON;
preserves exact receipt/error structure. Inspect
and
after uncertain writes; do not infer safe retry from a timeout.
Managed source changes use
cluster push --config DIR --expected-revision REV --message MSG
, then
, then
cluster apply --plan PREVIEW_ID
, all with the same cluster target. Managed plan/apply reject local
, wait until
(default 300 seconds), and return on acceptance
with
. A timeout cancels nothing and submits nothing new: resume
by repeating
with the same
and the printed
. Creation
returns identity; it does not select a new target or bind a folder. Providers never
fall back to each other. Preserve unresolved folder lifecycle evidence and
reconcile it through explicit
config recover-operations --source DIR --profile NAME
.
For direct recovery,
cluster apply --target ROOT --deployment-id ID --writers-stopped
has no
: it reconciles an existing attempt. A fresh
apply with a caller ID requires explicit
, and reusing an existing ID
only observes that attempt. Full command shapes and bounds live in
commands and
cluster operations.
Schema Design
Omnigraph schemas are ontologies, and when many agents share one graph the
schema is their coordinate system: it decides where a fact goes, what a stored
value means, and which paths agents reason along. Design for
convergence:
two agents given the same input should write the same graph and read the same
meaning back. Decide conservatively what to model; once modeled, constrain
precisely, because changing a commitment later is a rebuild (adding
/
/
, an edge
or a required edge to an existing
type, changing cardinality, removing a constraint from a property that stays,
and
→
are refused;
additions, nullable additions, enum
widening, renames, drops,
→
and a node
apply in place, the
last two only when the stored rows already satisfy them).
In short: Gruber's five criteria (clarity · coherence · extendibility · minimal
encoding bias · minimal commitment) · neither too loose (one meaning, many
encodings) nor too tight (a meaning with no encoding): tight where agents must
converge, open at declared extension points · write the questions as
first ·
design identity first (
, keyed edges, find before create) · kinds are
types, roles are edges · put a fact on what determines it · keep attribution,
justification, confidence and time on separate axes · provenance is structural
(
→ fact,
,
), never a free-text
field · layer
extracted and synthesized knowledge over raw spans, with lineage back to them,
keyed per fact (span + extractor + statement digest) · store decisions, compute
derived facts · narrow types and closed vocabularies · constraints in the
schema; rules it cannot express as
nodes agents lint the graph
against, including an orphan check per required link (
counts a node
only when a write touches it) · compose around shared identities (modules add
facets, never modify the core) from general primitives that combine · optimize
retrieval: links for recall, specific edges, filters and answer-sized units for
precision · write names,
and
for a reader without
context · never repurpose a field · measure convergence with two independent
encoders. Full text with Omnigraph
mappings:
references/schema-design.md
.
Storage & Credentials
A graph's bytes live in one of three supported URI families:
- Local filesystem — a path or URI. The target selects the graph or cluster root explicitly; a source directory does not select storage. Local development needs no object store.
- S3-compatible object storage — AWS, Railway, Tigris, etc. (). Authenticate with the standard environment contract.
- Azure Blob storage preview — . Reads and Azurite qualification are available, but Azure is not production-supported; every write or maintenance process must be launched through the root-scoped
omnigraph-azure-admission
wrapper.
Direct CLI targets are local, with one exception: a stopped S3 cluster accepts
an inline
cluster root for
cluster plan/apply/status/force-unlock/upgrade-ledger
and the maintenance commands with
(see
S3 cluster roots); the CLI
then reads
(or
) and endpoint variables from its environment. Otherwise,
for cloud-backed graphs, use a registered server or managed target; the server
owns storage credentials. Keep development credentials in a git-ignored
and source it before starting the process that needs them:
bash
set -a && source .env.omni && set +a
Direct
/
write local storage, and direct
writes a local or inline
cluster root, without an HTTP server. A served
or
sends the request to
, which performs the writes with its storage credentials. A managed
cluster apply --target NAME --plan PREVIEW_ID
is submitted through the profile’s control plane. A serving process needs read-write storage access for served data-plane writes. Validate with
curl http://127.0.0.1:8080/readyz
(HTTP 200,
;
only proves the process is alive), then
omnigraph snapshot --target <name> --graph <id> --json
.
Project Layout
Deployment & access
- Cluster deployment — the only way to serve. A declares the
whole deployment (graphs, schemas, stored queries, policies, optional S3/Azure
root); converges it and
omnigraph-server --cluster .
(or --cluster s3://bucket/prefix
,
config-free) serves it. A direct apply keeps its admission lock: once its
writes have settled, release that exact lock with
cluster force-unlock <LOCK_ID>
before starting the server, and send later
changes with cluster apply --target NAME --config DIR
using a registered server target.
See .
- Direct / embedded access — no server. Address a graph's storage directly
with a local path or
--target file:///absolute/path/graph.omni
; also accepts its creation URI positionally.
There is no single-graph server mode — the server is cluster-only.
- Agents — one path per place. In a terminal, an agent runs CLI commands
with , or connects its MCP client to an existing server target with
omnigraph mcp --target NAME
(see , MCP for agents);
in Studio's agent panel it uses Studio's gateway. No path starts a server.
The two config surfaces
The team owns
and referenced schemas, queries and policies.
The operator owns the
document at
.
changes the operator directory;
selects one replacement file without merging.
is deployment source.
The primary
operator reference owns the complete
schema, providers, transport, defaults and upgrade procedure.
Profiles pin API/organization and own one auth provider for one identity. Managed targets
reference a profile and pin cluster ID/incarnation; standalone server targets
own endpoint/auth. Direct graph/root targets use absolute local
URIs.
Every standalone target owns a single auth provider; use separate targets for
different identities at the same endpoint. Managed
targets use their pinned profile; default/global profiles cannot override it.
and
apply only to their command
classes. A graph selector overrides target
; direct graphs reject
it. Read output defaults to
. Whole-document validation is offline.
bash
omnigraph config validate
omnigraph login --create-profile work
omnigraph cluster list --profile work --json
omnigraph target add production --profile work --cluster CLUSTER_ID
omnigraph target inspect production --resolved --json
omnigraph credentials status --profile work --json
Never put secrets in configuration. Providers are
(managed device
login),
(exactly one
,
or
source),
(absolute
argv, bounded JSON protocol), managed-only
(explicit
HTTPS token endpoint, client ID and env/file client secret), and standalone-only
. No fallback is allowed. Static installation uses
, not login; existing
entries require
. Managed credentials require
; standalone
credentials require
. Status never uses network/helpers or prompts; secure-store availability
and identity remain unknown without reading secrets. Export is raw bearer-plus-newline to a pipe
only, never terminal/file output; managed-target export releases data access;
exports control access.
Neither exports refresh tokens. Read the reference before using credential commands.
Use
config rename-profile FROM TO
or
config rename-target FROM TO
to preserve custody and update
references/defaults. An interrupted rename needs
against
the same operator file; conflicting edits refuse. These commands have no
.
Changing a profile's principal requires
login --profile NAME --replace-principal NEW_PRINCIPAL_ID
, matching the verified new identity and
invalidating old derived credentials. See the primary operator reference.
login --create-profile NAME
explicitly creates a new profile, defaulting its API
to
https://platform.omnigraph.dev
. Bare login uses
; it never
creates a missing profile. Neither form changes routing defaults. Operator YAML
may be read-only; credential metadata stays in writable
.
Credentials retain their expiry through discovery and are checked before dispatch.
Transport defaults to verified system TLS and direct routing, ignoring proxy
variables unless opted in. Custom CA plus HTTPS proxy is refused. This model
qualifies neither BYOC private routing nor workload federation. Direct aliases
cannot execute the server-owned stored-query registry. Credentials and
discovery never supply a missing destination.
What to commit
Commit: ,
,
,
,
, and the project's
and
.
Ignore: (credentials),
(local agent state),
(local graph artifacts),
and
(cluster state + derived graph roots).
Give agents a
A per-project
tells coding agents where files live and what conventions matter. Without it, agents re-discover the same things every session.
Common Gotchas
These are the traps most likely to bite. Scan this table before debugging any parse or runtime error.
| Trap | Symptom | Fix |
|---|
| comments in | parse error: expected schema_file
| Use |
| Standalone block | parse error: expected EOI or schema_decl
| Inline: |
| (list of enum) | compile error | Use ; lists must contain scalars |
| Assuming must quote its source | unnecessary schema churn | and are both valid; quoted form is canonical |
| Bare / in an edge constraint on a new graph | offline passes; / fail unknown property reference 'Knows.src'; the system field is '@src'
| Put inside the edge body; means a declared user property |
| -prefixed property on a new graph | property name '_x' is reserved for system columns (names starting with '_')
| Rename it; / are also reserved on edges (is reserved on edge types
) |
| Expecting to populate vectors during load | missing/stale vectors | is metadata; run the offline omnigraph embed ... --reembed-all
file pipeline, then load its output |
| with feature branches open | schema apply requires a graph with only main
| Delete them ( or ); a merge alone leaves the branch live |
| / without | compile error | Add ; a BM25-only query may omit it, though bounded output is recommended |
| Adding non-nullable property without backfill | unsupported migration | Make optional → backfill; keep it optional (tightening → is refused, OG-MF-106) |
| unexpected argument '--json' found
| doesn't support ; drop the flag |
| on an already-initialized URI | graph already initialized or initialization metadata exists at '<uri>'
| Never overwrite it. only replaces orphan schema artifacts after proving there is no graph manifest |
| dropping a property/type | nothing is reclaimed at apply; older commits still read the dropped data, and a dropped property's values stay in the current data files | a type: with a retention that excludes the pre-drop commits. A property: first, delete branches and tags from before it, then that ; the data is then unrecoverable |
| Committing | credential leak | Add to |
| Non-parameterized query values | typecheck surprise, injection risk | Declare and pass via |
| Missing required field in | T12: insert for `X` must provide non-nullable property `Y`
| Accept the param in the mutation signature |
| Mixing with / in one query | lint passes; fails "mixes inserts/updates and deletes" | Split into two mutations (D₂ rule) |
| , , for identity | //: type `Person` has no property `id`; the system identity is `$p.@id`
(a failing stored-query registry quarantines its graph) | Use , /, ; means a declared user property |
| Long-lived feature branches | merge conflicts, schema apply blocked | Merge promptly; delete when done |
| wrapper in | parse error: expected query_file
at line 1 | Use query <name>(...) { insert T { ... } }
; there is no top-level keyword |
| on a data/schema command | unexpected argument '--config' found
| Use it only for source-taking cluster commands; select destinations with |
| names another actor than the served write's token | (exit 4) | Use the token of that actor, or drop ; the bearer token selects the actor |
| Reading a large schema via stdout-capped tool | Truncated, garbled, or duplicated output | omnigraph schema show --target <name> --graph <id> > /tmp/schema.pg
, then read the file in chunks |
| without | the following required arguments were not provided: --mode <MODE>
| Pass --mode merge|append|overwrite
— there is no default (overwrite is destructive, so it is never implicit). Address direct storage or a served graph |
| Blind retry after 504 | duplicate unkeyed nodes/edges or a repeated effect | compare the intended branch/entity state first; retry only after proving the attempt did not land |
| Review branch left after a timed-out | uncertain load result | Inspect its content and history; matching 's head alone is not proof of abandonment or authorization to delete it |
| / on a cluster-managed graph | refused — bypasses the cluster ledger | Evolve cluster graphs via omnigraph cluster apply --target ROOT --config .
; / are for a non-cluster store |
| Assuming Blob-bearing data cannot compact | unnecessary skipped maintenance | Lance 13 Blob compaction is supported; preserves null/empty/non-empty values |
| / on a Blob column, on a list or vector | schema parse/validation rejection | Blob properties cannot be keys, unique, or indexed; list and vector properties cannot be keys or unique |
Full-text search refused with FullTextIndexRebuildRequired
| the index has no certified analyzer | Run index rebuild --kind full-text --branch <b>
on every live branch that needs text search; does not rebuild indexes |
| Opening a graph at a format below v14 | refused: this omnigraph reads only v14 to v17
| A standalone v8, v9 or v13 graph is converted by (next row); any other format is rebuilt by export with the binary that wrote it, then and |
| Opening a v8, v9 or v13 graph | refused: normal open serves v14 to v17 only and names | Stop every process using the graph, back up the whole root, then run upgrade --target ./graph.omni --check --json
and upgrade --target ./graph.omni --json
on a standalone graph; a cluster-managed graph below v14 is exported with the build that wrote it and rebuilt. The message's positional examples predate . See converting a graph |
| , or on a branch still at format v14 or v15 | refused at v14 (unattached also at v15) | Make one ordinary write on that branch, or run the offline stamp-only route on a standalone graph |
| Using for identity on a new graph | unknown input field 'id': move data.id to the top-level 'id' field
| Put identity in top-level JSONL ; contains user properties |
| Re-running a load with unkeyed edges | duplicate edges | Supply stable top-level edge s, or declare when creating the edge type |
| Assuming every JSON result cell has a key | absent keys for null values | Query/export JSON omits null cells; change images retain explicit nulls |
| configuration refusal | Use , , , , , or |
| or a symlink in a relative path | / | Keep referenced files inside the config directory with plain relative paths |
| A 0.13 operator file | configuration refusal | Rewrite it as (see migrations); keep the old operator home until unresolved work is reconciled |
Deep Dives
For anything beyond the basics, load the relevant reference file. Each is self-contained — load only what you need.
| Reference | When to load |
|---|
| Setting Omnigraph up for a new user: install, version-matched skill, a first schema, local graph, load, query and branch, then next steps |
| Editing files, running /, renaming types, backfilling required fields |
references/schema-design.md
| Designing or reviewing a schema: Gruber's criteria, design flow, identity, provenance, rules, composition, and measuring convergence across agents |
| Writing or linting files, search functions, aggregations, multi-hop patterns |
| Choosing between and (required , to fork a review branch); branch review workflow; exact overwrite scope |
| Writing and reading managed/external Blob values, selectors/ranges, security and lifecycle boundaries |
| Exact read/write positions, conditional mutations, commit diffs, feed cursors, baselines, and retention gaps |
| Operating through : exact receipts, unknown 504 outcomes, conflict handling, and safe retry decisions |
| Cluster configuration, plan/apply, drift, and serving |
| Embeddings, , vector/text ranking, scope-then-rank pattern |
| Defining aliases for agents, structured output, JSON args |
references/stored-queries.md
| Cluster stored-query registry: declaration, queries validate/list --target
, served invocation, and Cedar gating |
references/server-policy.md
| Starting the HTTP server, routes, bearer auth, Cedar policy gating, multi-graph mode |
| Current command shapes, addressing, output, and maintenance |
| Upgrading from 0.13: the 0.14 HTTP API, operator configuration and v14/v15 graphs; converting a v8, v9 or v13 graph offline |