read / change
Run read queries and mutations from the CLI.
The read command executes a query against the graph and returns results. The
change command executes a mutation that modifies data. Both commands reference
named queries inside .gq files.
read
Run a read-only query and return the result.
Usage
omnigraph read --uri <uri> --query <file> [options]Options
| Option | Required | Default | Description |
|---|---|---|---|
--uri or --target | no | config or alias default | Repo or server target |
--query or --alias | yes | — | Query file path or configured alias |
--name | no | inferred if the file contains one query | Query name within the file |
--params | no | — | JSON object of parameter values |
--params-file | no | — | Path to a JSON file with parameter values |
--branch | no | main | Branch to read from |
--snapshot | no | — | Snapshot id to read from; overrides branch |
--format | no | table | Output format: table, kv, csv, jsonl, or json |
--json | no | — | Shortcut for --format json |
Examples
Run a simple query:
omnigraph read --uri ./repo.omni --query queries.gq --name all_people847 rows from branch main via all_people
NAME AGE
Dr. Sarah Kim 34
Bob Chen 28
Carol Wu 45
...Run a parameterized query with JSON output:
omnigraph read --uri ./repo.omni \
--query queries.gq \
--name friends_of \
--params '{"name": "Alice"}' \
--json{
"query_name": "friends_of",
"target": {
"branch": "main",
"snapshot": null
},
"row_count": 2,
"columns": ["name", "age"],
"rows": [
{ "name": "Bob", "age": 32 },
{ "name": "Carol", "age": 28 }
]
}Read from a specific branch:
omnigraph read --uri ./repo.omni \
--query queries.gq \
--name unblocked_tasks \
--branch feature-xRead from a past snapshot id:
omnigraph read --uri ./repo.omni \
--query queries.gq \
--name all_people \
--snapshot <graph-commit-id> \
--jsonchange
Run a mutation that modifies data on a branch.
Usage
omnigraph change --uri <uri> --query <file> [options]Options
| Option | Required | Default | Description |
|---|---|---|---|
--uri or --target | no | config or alias default | Repo or server target |
--query or --alias | yes | — | Mutation file path or configured alias |
--name | no | inferred if the file contains one mutation | Mutation name within the file |
--params | no | — | JSON object of parameter values |
--params-file | no | — | Path to a JSON file with parameter values |
--branch | no | main | Branch to mutate |
--json | no | — | Output result as JSON |
Example
omnigraph change --uri ./repo.omni \
--query mutations.gq \
--name mark_completed \
--params '{"slug": "auth"}' \
--branch feature-x \
--json{
"branch": "feature-x",
"query_name": "mark_completed",
"affected_nodes": 1,
"affected_edges": 0
}Aliases in omnigraph.yaml
Define shortcuts for frequently used queries in your omnigraph.yaml:
targets:
local:
uri: ./repo.omni
cli:
target: local
branch: main
aliases:
unblocked:
command: read
query: queries.gq
name: unblocked_tasks
target: local
branch: main
format: kv
complete:
command: change
query: mutations.gq
name: mark_completed
target: local
branch: main
args: [slug]Then run them by alias:
omnigraph read --alias unblocked
omnigraph change --alias complete auth --branch feature-xAlias args map positional values to named query parameters. Aliases also let
you centralize the target, default branch, and output format.
Query file format
A single .gq file can contain multiple named queries and mutations. Select
which one to run with --name:
query all_people() {
match { $p: Person }
return { $p.name, $p.age }
}
query friends_of($name: String) {
match {
$p: Person { name: $name }
$p knows $f
}
return { $f.name, $f.age }
}
query mark_completed($slug: String) {
update Task set {
status: "completed",
}
where slug = $slug
}If --name is omitted and the file contains exactly one query, that query is
used. If the file contains multiple queries and --name is omitted, the
command returns an error listing the available names.