apunkt/omnigraph
1
0
Fork 0
mirror of https://github.com/ModernRelay/omnigraph.git synced 2026-06-18 02:24:27 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 5

docs(readme): make Common Commands cluster-first, not store-first (#263)

Browse source 
Follow-up to #262: the command examples led with single-file `--store ./graph.omni`
for everything (init/load/query/mutate/branch), which reads as a single-graph-file
product — the opposite of the cluster-first paradigm.

Reframe so the everyday loop is the headline: declare a cluster → `cluster apply`
→ `omnigraph-server --cluster …` → work against the served graph with
`--server <name> --graph <id>`, invoking stored queries by name. `--store` is
demoted to a clearly-secondary "Local / ad-hoc" note for standalone-graph
iteration. Folds the former separate "Serving" section into step 1.

All served examples verified to resolve correctly (`→ http://…/graphs/<id>
(served)`).

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Andrew Altshuler 2026-06-16 11:40:11 +03:00 • committed by GitHub
parent a83da2ccfd
commit df0b0eadd1
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 39 additions and 40 deletions
Download patch file Download diff file Expand all files Collapse all files

79
README.md
View file

@ -78,51 +78,50 @@ value.
## Common Commands
Every command declares the **capability** it needs and how it's addressed.
Direct storage (`init`, `load`, `branch`, …) takes a positional `file://`/`s3://`
URI or `--store <uri>`; a served graph is addressed with `--server <name|url>`
(never a positional `http(s)://` URI). `query`/`mutate` invoke a stored query
**by name** (the positional is the query name, not a graph URI).
A deployment is a **cluster**. A `cluster.yaml` declares its graphs, schemas,
stored queries, and policies; you converge it with `cluster apply` and serve it.
The server is cluster-first — it boots only from a cluster and serves every graph
under `/graphs/{id}/…`. Day-to-day work goes through that server: graphs are
addressed with `--server <name>` (+ `--graph <id>`), and `query`/`mutate` invoke
a stored query from the catalog **by name**.
```bash
# Create a graph and load data (--mode is required; overwrite is destructive)
omnigraph init --schema ./schema.pg ./graph.omni
omnigraph load --data ./data.jsonl --mode merge --store ./graph.omni
# Read / write — ad-hoc .gq against a local store (positional selects the query)
omnigraph query --query ./queries.gq get_person --params '{"name":"Alice"}' --store ./graph.omni
omnigraph mutate --query ./queries.gq insert_person --params '{"name":"Mina"}' --store ./graph.omni
# Branch and merge (Git-style, across the whole graph)
omnigraph branch create --from main feature-x --store ./graph.omni
omnigraph branch merge feature-x --into main --store ./graph.omni
# Against a running server: invoke a stored query by name from the catalog
omnigraph query find_people --server prod --graph knowledge --params '{"q":"AI safety"}'
```
Operator settings (identity, named servers/clusters, credentials, defaults) live
in `~/.omnigraph/config.yaml`; with a default scope set, the addressing flags can
be omitted. See [docs/user/cli/index.md](docs/user/cli/index.md) and the
[CLI reference](docs/user/cli/reference.md) for schema apply, snapshots, commits,
profiles, and policy/queries tooling.
## Serving (cluster-first)
A deployment is a **cluster**: a `cluster.yaml` (graphs, schemas, stored queries,
policies, storage) that you converge with `cluster apply`, then serve. The server
boots from the cluster only — it has no single-graph mode — and serves every
graph under `/graphs/{id}/…`.
```bash
omnigraph cluster apply --config ./company-brain # converge the declared state
# 1. Converge the declared cluster, then serve it
omnigraph cluster apply --config ./company-brain
omnigraph-server --cluster ./company-brain --bind 0.0.0.0:8080
# or config-free from object storage — the bucket IS the deployment:
omnigraph-server --cluster s3://my-bucket/company-brain --bind 0.0.0.0:8080
# or config-free from object storage — the bucket IS the deployment:
# omnigraph-server --cluster s3://my-bucket/company-brain --bind 0.0.0.0:8080
# 2. Work against the served graph — stored queries invoked by name
omnigraph query find_people --server prod --graph knowledge --params '{"q":"AI safety"}'
omnigraph mutate add_person --server prod --graph knowledge --params '{"name":"Mina"}'
omnigraph load --data ./data.jsonl --mode merge --server prod --graph knowledge
# 3. Branch and merge, Git-style across the whole graph
omnigraph branch create --from main review/2026-06 --server prod --graph knowledge
omnigraph branch merge review/2026-06 --into main --server prod --graph knowledge
```
See the [cluster guide](docs/user/clusters/index.md) and
[deployment guide](docs/user/deployment.md).
Set a default scope (or a `--profile`) in `~/.omnigraph/config.yaml` — operator
identity, named servers/clusters, credentials — and the `--server`/`--graph`
flags drop away (`omnigraph query find_people --params …`).
**Local / ad-hoc.** For quick iteration on a standalone graph (no cluster, no
server), address storage directly with `--store` (or a positional `file://` /
`s3://` URI) and run ad-hoc `.gq` with `--query` (the positional then selects
which query in the file):
```bash
omnigraph init --schema ./schema.pg ./graph.omni
omnigraph load --data ./data.jsonl --mode merge --store ./graph.omni
omnigraph query --query ./queries.gq get_person --params '{"name":"Alice"}' --store ./graph.omni
```
See [docs/user/cli/index.md](docs/user/cli/index.md), the
[CLI reference](docs/user/cli/reference.md), the
[cluster guide](docs/user/clusters/index.md), and the
[deployment guide](docs/user/deployment.md) for schema apply, snapshots, commits,
profiles, and policy/queries tooling.
## Clients