mirror of
https://github.com/ModernRelay/omnigraph.git
synced 2026-06-18 02:24:27 +02:00
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.
84 lines
2.3 KiB
Markdown
84 lines
2.3 KiB
Markdown
# 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](install.md) 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](schema/index.md) for types, constraints, and edges.
|
|
|
|
## 2. Initialize the graph
|
|
|
|
```bash
|
|
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`):
|
|
|
|
```bash
|
|
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](mutations/index.md).
|
|
|
|
## 4. Query
|
|
|
|
Write a query (`.gq`) — save as `queries.gq`:
|
|
|
|
```gq
|
|
query find_people($title: String) {
|
|
match { $p: Person { title: $title } }
|
|
return { $p.name }
|
|
}
|
|
```
|
|
|
|
Run it:
|
|
|
|
```bash
|
|
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](queries/index.md) covers `match`/`return`/`order`, and
|
|
[search](search/index.md) covers vector and full-text search.
|
|
|
|
## 5. Work on a branch
|
|
|
|
Branches isolate changes until you merge them — Git-style, across the whole graph:
|
|
|
|
```bash
|
|
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](branching/index.md) and [merging](branching/merge.md).
|
|
|
|
## Next steps
|
|
|
|
- [CLI reference](cli/reference.md) — every command and flag.
|
|
- [Schema language](schema/index.md) and [query language](queries/index.md).
|
|
- [Operating a cluster](clusters/index.md) and [running the server](operations/server.md)
|
|
for multi-graph, multi-user deployments.
|