ee4986e9a1
* docs: optimize README for dev onboarding; fix 0.7.0 staleness The README's setup half drifted from the shipped 0.7.0 CLI and led with the heaviest path (Docker + RustFS). This reworks it for fast, correct onboarding: README.md - New zero-dependency "Your first graph in 60 seconds" hero: a fully copy-pasteable local file-backed loop (schema → init → load → query → branch). - Add a correct "Serve it" section (cluster apply + omnigraph-server --cluster); the server is cluster-only on main, so the old positional-URI boot is gone. - Demote the RustFS bootstrap to "rehearse the S3 path locally"; reframe the storage bullet as "filesystem or any S3-compatible store (AWS S3, R2, MinIO, RustFS)" — RustFS is a provider, not a storage class. - Fix crate/MCP descriptions (query/mutate/load, not read/change/ingest). docs/user/quickstart.md - Fix the query example: `read --name <q> … <uri>` is removed — the query name is positional and the graph is addressed with `--store` (`omnigraph query find_people --query queries.gq --store graph.omni`). scripts/local-rustfs-bootstrap.sh - Convert to cluster mode: write a cluster.yaml (storage: s3://…), then validate → import → apply, load the fixture into the derived root with the now-required --mode, and serve with `omnigraph-server --cluster`. The old flow (`load` without --mode, `omnigraph-server <URI>` positional boot) no longer works on a cluster-only server. * docs: move agent skill into the repo, add agent-setup snippet, drop rustfs script skills/omnigraph - The operational skill (formerly `omnigraph-best-practices` in the cookbooks repo) now lives with the engine it documents, co-versioned. Renamed to `omnigraph`; repository metadata repointed here. - Broadened the description to trigger on intent — storing/retrieving/querying knowledge, agent memory, building a knowledge graph, operating Omnigraph — as well as on CLI/artifact sightings (stays ≤1024 chars). - Install: `npx skills add ModernRelay/omnigraph@omnigraph`. README - New "Set it up with an AI agent" paste snippet: installs the skill, reads the docs (URL), browses the cookbooks, and asks the user about a use case before standing up a first graph. - "Agent skill & starter graphs" section points at skills/omnigraph + cookbooks. Drop scripts/local-rustfs-bootstrap.sh - Not CI-tested (so it rotted: it broke on the cluster-only migration — positional server boot, load without --mode), demoed the now-optional S3 path, and was the most fragile artifact in the repo. Replaced with a "Testing against S3 locally" guide in deployment.md (docker run RustFS/MinIO + AWS_* env + cluster-on-S3). README/AGENTS references updated.
2.3 KiB
Quickstart
This walks the core loop end to end: define a schema, initialize a graph, load
data, query it, and use a branch. It uses a local file-backed graph; swap the
path for an s3://… URI to run the same flow against object storage.
Install the omnigraph CLI first.
1. Write a schema
A schema (.pg) declares your node and edge types. Save this as schema.pg:
node Person {
name: String,
title: String?,
}
See the schema language for types, constraints, and edges.
2. Initialize the graph
omnigraph init --schema schema.pg graph.omni
init creates an empty graph at the given URI with your schema applied.
3. Load data
load is the single bulk-write command. --mode is required
(overwrite | append | merge):
omnigraph load --data people.jsonl --mode overwrite graph.omni
people.jsonl is newline-delimited JSON, one record per line. For finer-grained
or inline writes, see mutations.
4. Query
Write a query (.gq) — save as queries.gq:
query find_people($title: String) {
match { $p: Person { title: $title } }
return { $p.name }
}
Run it:
omnigraph query find_people --query queries.gq \
--params '{"title":"Engineer"}' --format table --store graph.omni
The query name is positional; --query points at the .gq source and
--store addresses the graph's storage directly.
The query language covers match/return/order, and
search covers vector and full-text search.
5. Work on a branch
Branches isolate changes until you merge them — Git-style, across the whole graph:
omnigraph branch create review/new-hires graph.omni
omnigraph load --data new-hires.jsonl --mode append --branch review/new-hires graph.omni
# inspect the branch, then integrate it
omnigraph branch merge review/new-hires --into main graph.omni
See branches & commits and merging.
Next steps
- CLI reference — every command and flag.
- Schema language and query language.
- Operating a cluster and running the server for multi-graph, multi-user deployments.