Skip to content

index.md

Latest commit

 

History

History
234 lines (181 loc) · 8.56 KB

index.md

File metadata and controls

234 lines (181 loc) · 8.56 KB
Raw

CLI guide

The omnigraph CLI can work directly with a graph store, through a running server, or with a cluster definition. Start with the form that matches the resource you have:

# One graph, opened directly
omnigraph query sources_for_claim --query queries.gq \
  --params '{"claim":"lower-latency"}' --store ./graph.omni

# One graph on a multi-graph server
omnigraph query sources_for_claim --params '{"claim":"lower-latency"}' \
  --server prod --graph knowledge

# A reusable scope from ~/.omnigraph/config.yaml
omnigraph query sources_for_claim --params '{"claim":"lower-latency"}' \
  --profile prod-knowledge

Run omnigraph <command> --help for the flags supported by your installed version. The CLI reference summarizes addressing, commands, configuration, and output formats.

For a managed cluster, first select it with use and cache an identity credential with cluster token. Run graphs list to discover graph names, then query or mutate from that folder with an explicit --graph. Applied Cedar policy determines your permissions. See managed data access for legacy restricted credentials, expiry, offline operation, and clearing.

Create, load, and query a graph

omnigraph init --schema schema.pg ./graph.omni
omnigraph load --data evidence.jsonl --mode overwrite ./graph.omni

omnigraph query sources_for_claim \
  --query queries.gq \
  --params '{"claim":"lower-latency"}' \
  --format table \
  --store ./graph.omni

load always requires a mode:

  • overwrite replaces each node or edge type represented in the batch. Types absent from the batch are unchanged.
  • append inserts new entities and rejects duplicate IDs.
  • merge inserts new IDs and updates existing IDs.

Use mutate for .gq insert, update, and delete queries:

omnigraph mutate add_source \
  --query mutations.gq \
  --params '{"slug":"incident-review","title":"Incident review"}' \
  --store ./graph.omni

For a stored server query, omit --query; the positional name selects the query from the server's registry:

omnigraph query sources_for_claim --server prod --graph knowledge \
  --params '{"claim":"lower-latency"}'

Work with branches

omnigraph branch create review/new-data --from main --store ./graph.omni
omnigraph load --data batch.jsonl --mode merge \
  --branch review/new-data ./graph.omni
omnigraph query inspect --query review.gq \
  --branch review/new-data --store ./graph.omni
omnigraph branch merge review/new-data --into main --store ./graph.omni

Each branch operation is also a GQ statement, run through the same verbs that run any .gq source: the control writes through mutate, the listing through query. A statement names its branches itself, so it takes no --branch:

omnigraph mutate -e 'branch create "review/new-data" from main' --store ./graph.omni
omnigraph query  -e 'branch list' --format table --store ./graph.omni
omnigraph mutate -e 'branch merge "review/new-data" into main' --store ./graph.omni
omnigraph mutate -e 'branch delete "review/new-data"' --store ./graph.omni

See Branches and commits for isolation, history, and merge behavior.

Session settings

--set NAME=VALUE, repeatable, gives a session setting a value for one invocation; the value is spelled as after = in a set line (--set merge_lineage=off). A set line in the source applies after --set, so the file wins.

  • query --set: applies to the read, show included.
  • mutate --set: applies to the mutation or branch statement.
  • branch merge --set: applies to the merge (--set merge_lineage=verify).
  • commit changes --set: sent as set=NAME=VALUE on the commit's change read. The values are validated and select nothing in this release; a direct run (--store) accepts them with no effect.
  • changes poll --set: sent as set=NAME=VALUE on the change feed read, with the same validation and the same absence of effect.
  • load --set and ingest --set: a direct run (--store) applies them to the staged write (--set stage_write_concurrency=16); a served run refuses any --set before sending, since the served load and ingest routes carry no settings field.
omnigraph query reports --query queries.gq --set merge_lineage=off --store ./graph.omni
omnigraph branch merge review/new-data --into main --set merge_lineage=verify --store ./graph.omni

A direct run (--store) is the process, so it accepts a process setting from --set, the file and the environment. A served run (--server) sends --set values in the request's settings field, and a --set or set line naming a process setting is refused before anything is sent: setting is a process setting; it is read from the server's environment, not from a request.

A stored query takes no --set: omnigraph query <name> without -e or --query runs under the process defaults.

Read Blob values

Read a managed Blob cell to a file or inspect its metadata:

omnigraph blob get node Document doc-42 body \
  --store ./graph.omni --out body.bin

omnigraph blob stat node Document doc-42 body \
  --store ./graph.omni --json

blob get writes bytes to stdout when --out is omitted. Add --offset and --length for a range. The CLI reports external references but does not follow them. See Blob values for the complete contract.

Inspect and maintain a graph

omnigraph snapshot ./graph.omni --json
omnigraph commit list ./graph.omni --json
omnigraph schema show ./graph.omni

omnigraph optimize ./graph.omni
omnigraph repair ./graph.omni                 # preview only
omnigraph cleanup --keep 10 --older-than 7d ./graph.omni
omnigraph cleanup --keep 10 --older-than 7d --confirm ./graph.omni

Maintenance commands open storage directly; they do not run through --server. For a cluster-managed graph, address it with --cluster <root> --graph <id>. Read the maintenance guide before repair or cleanup.

Use a server

Declare the server once, store its token, then address graphs by ID:

# ~/.omnigraph/config.yaml
servers:
  prod:
    url: https://graph.example.com
printf '%s' "$OMNIGRAPH_TOKEN" | omnigraph login prod
omnigraph graphs list --server prod
omnigraph query sources_for_claim --params '{"claim":"lower-latency"}' \
  --server prod --graph knowledge

The token is stored separately from config.yaml. A server resolves the actor from the token; clients cannot override it with --as.

Manage a cluster

Without a managed context, cluster commands read a directory containing cluster.yaml:

omnigraph cluster validate --config ./company-brain
omnigraph cluster plan --config ./company-brain
omnigraph cluster apply --config ./company-brain --as act-alice

They manage graph definitions, schemas, stored queries, and policies—not graph data. See Operating a cluster.

For a managed cluster, log in to its Intent API and select the cluster for your config directory:

omnigraph login --api https://control.example
omnigraph use CLUSTER_ID --api https://control.example --config ./company-brain
omnigraph cluster plan --config ./company-brain --json > plan.json
omnigraph cluster apply --config ./company-brain --plan "$(jq -r .data.run_id plan.json)" --json
omnigraph cluster status --config ./company-brain --json
omnigraph cluster history --config ./company-brain --json
omnigraph logout --api https://control.example

Commit and push external configuration before planning. The API plans its bound head, or the pushed revision selected with --rev. Apply uses the exact saved plan and your current permissions. To release an unused plan, run omnigraph cluster cancel PLAN_RUN_ID --config ./company-brain; its result remains in history and cannot be applied afterward.

The folder's .omnigraph/context selects the managed API. An unavailable API or malformed context causes an error. To intentionally use the direct cluster.yaml path, pass --direct. See Managed cluster commands for credential storage, automation, bounded waits, and exit codes.

Validate source before running it

omnigraph lint --schema schema.pg --query queries.gq
omnigraph queries validate --cluster ./company-brain --graph knowledge

lint checks one .gq source. queries validate checks the applied stored query registry for a cluster graph.

Deprecated names

read, change, check, and ingest remain compatibility shims. New scripts should use query, mutate, lint, and load.