mirror of
https://github.com/ModernRelay/omnigraph.git
synced 2026-06-15 01:55:13 +02:00
612741b387
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>
49 lines
2.7 KiB
Markdown
49 lines
2.7 KiB
Markdown
# Concepts
|
|
|
|
OmniGraph is a typed property-graph engine built as a coordination layer over the
|
|
[Lance](https://lance.org) columnar storage format. It gives you a schema-checked
|
|
graph with vector, full-text, and graph queries in one runtime, plus Git-style
|
|
branches and commits across the whole graph.
|
|
|
|
## The data model
|
|
|
|
- A graph has **node types** and **edge types**, declared in a
|
|
[schema](../schema/index.md).
|
|
- Each node type and each edge type is stored as its **own Lance dataset** —
|
|
columnar, versioned, on local disk or object storage.
|
|
- A single `__manifest` table coordinates all of those datasets, so the graph has
|
|
one coherent version even though it spans many datasets.
|
|
|
|
This split is what lets a graph commit be **atomic across every type at once**: a
|
|
publish flips every relevant dataset's version together in one manifest write, so
|
|
readers never see a half-applied change. See [storage](storage.md) for the layout.
|
|
|
|
## Two layers: inherited vs. added
|
|
|
|
Throughout the docs, capabilities are framed as **L1** (inherited from Lance) or
|
|
**L2** (added by OmniGraph):
|
|
|
|
| | L1 — from Lance | L2 — added by OmniGraph |
|
|
|---|---|---|
|
|
| Storage | Columnar Arrow datasets on object storage | Per-type datasets coordinated as one graph |
|
|
| Versioning | Per-dataset versions + time travel | [Snapshots](../branching/time-travel.md) across all types at once |
|
|
| Branches | Per-dataset branches | [Graph-level branches](../branching/index.md), atomic across types |
|
|
| Commits | Per-dataset commits | [Commit DAG](../branching/index.md) for the whole graph; three-way [merge](../branching/merge.md) |
|
|
| Indexes | Scalar / vector / full-text indexes | Built per relevant column; graph topology index for traversal |
|
|
| Search | Vector + full-text primitives | [`nearest` / `bm25` / `rrf`](../search/index.md) in one query, plus graph traversal |
|
|
| Querying | — | The [`.gq` query language](../queries/index.md) and [`.pg` schema language](../schema/index.md) |
|
|
|
|
## How the pieces fit
|
|
|
|
- The **schema** (`.pg`) and **query** (`.gq`) languages are compiled to a typed
|
|
intermediate representation.
|
|
- The **engine** runs queries and mutations against Lance, coordinates the manifest,
|
|
maintains the commit graph, and builds indexes.
|
|
- The **CLI** ([`omnigraph`](../cli/index.md)) and the
|
|
**HTTP server** ([`operations/server.md`](../operations/server.md)) are two front
|
|
ends over the same engine, so embedded and remote behavior match.
|
|
- [Cedar policy](../operations/policy.md) enforcement is engine-wide — every writer
|
|
goes through the same authorization gate regardless of front end.
|
|
|
|
For deployment-scale topics — multi-graph servers, control-plane operations,
|
|
recovery — see [clusters](../clusters/index.md).
|