mirror of
https://github.com/ModernRelay/omnigraph.git
synced 2026-06-15 01:55:13 +02:00
docs(user): split language/branching pages + add front-door pages (Phase 2) (#225)
Content build-out on top of the Phase 1 topic move. No behavior changes. Splits (existing content relocated, cross-linked): - queries/index.md → mutations/index.md (insert/update/delete + the inserts-vs-deletes rule) and search/index.md (the multi-modal search functions + a hybrid-ranking overview tying nearest/bm25/rrf together). queries/index.md now covers the read shape and points at both. - branching/index.md → branching/time-travel.md (snapshots/time travel) and branching/merge.md (three-way merge + the 7 conflict kinds, verified against error.rs MergeConflictKind). New pages (written from the code, user-facing): - quickstart.md — init → load → query → branch, with verified CLI flags. - concepts/index.md — what OmniGraph is + the L1/L2 (Lance/OmniGraph) framing. Expanded operations/audit.md from a 7-line struct dump into a real actor-tracking page (server token-resolved vs CLI --as chain; reading the trail; the omnigraph:recovery reserved actor). Index wiring: docs/user/index.md and AGENTS.md's topic table link every new page; also normalized AGENTS.md's docs/user link display text to match the Phase 1 retargeted paths. Verified: zero broken .md links; check-agents-md.sh green (57 links, 54 docs). Deferred to Phase 3: de-dev polish (grammar paths, IR internals still in queries/branching), guides/, and a possible reference/config.md split (the config schema is already coherent in cli/reference.md). Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
parent
d46e50dd6d
commit
612741b387
11 changed files with 399 additions and 67 deletions
81
docs/user/quickstart.md
Normal file
81
docs/user/quickstart.md
Normal file
|
|
@ -0,0 +1,81 @@
|
|||
# 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 read --query queries.gq --name find_people \
|
||||
--params '{"title":"Engineer"}' --format table graph.omni
|
||||
```
|
||||
|
||||
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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue