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 <path> --query <file> --name <query> [options]Options
| Option | Required | Default | Description |
|---|---|---|---|
--query | yes | — | Path to a .gq file containing the query |
--name | yes | — | Name of the query within the file |
--params | no | — | JSON object of parameter values |
--branch | no | main | Branch to read from |
--snapshot | no | — | Snapshot version to read from (overrides branch) |
--json | no | — | Output as JSON array |
--jsonl | no | — | Output as newline-delimited JSON |
--csv | no | — | Output as CSV |
--format | no | table | Explicit format: table, json, jsonl, csv |
Examples
Run a simple query:
omnigraph read ./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 ./repo.omni \
--query queries.gq \
--name friends_of \
--params '{"name": "Alice"}' \
--json[
{ "name": "Bob", "age": 32 },
{ "name": "Carol", "age": 28 }
]Read from a specific branch:
omnigraph read ./repo.omni \
--query queries.gq \
--name unblocked_tasks \
--branch feature-xRead from a past snapshot:
omnigraph read ./repo.omni \
--query queries.gq \
--name all_people \
--snapshot 3 \
--jsonchange
Run a mutation that modifies data on a branch.
Usage
omnigraph change <path> --query <file> --name <mutation> [options]Options
| Option | Required | Default | Description |
|---|---|---|---|
--query | yes | — | Path to a .gq file containing the mutation |
--name | yes | — | Name of the mutation within the file |
--params | no | — | JSON object of parameter values |
--branch | no | main | Branch to mutate |
--json | no | — | Output result as JSON |
Example
omnigraph change ./repo.omni \
--query mutations.gq \
--name mark_completed \
--params '{"slug": "auth"}' \
--branch feature-x \
--json{
"branch": "feature-x",
"mutation": "mark_completed",
"rows_affected": 1
}Aliases in omnigraph.yaml
Define shortcuts for frequently used queries in your omnigraph.yaml:
target: ./repo.omni
aliases:
unblocked:
command: read
query: queries.gq
name: unblocked_tasks
complete:
command: change
query: mutations.gq
name: mark_completedThen run them by alias:
omnigraph unblocked --json
omnigraph complete --params '{"slug": "auth"}' --branch feature-xAliases inherit the target from the config, so you do not need to pass the repository path.
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.