mirror of
https://github.com/ModernRelay/omnigraph.git
synced 2026-06-18 02:24:27 +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>
31 lines
1.3 KiB
Markdown
31 lines
1.3 KiB
Markdown
# Snapshots & Time Travel
|
|
|
|
Every read in OmniGraph happens against a **snapshot** — a consistent, cross-table
|
|
view of the graph at one manifest version. A query holds one snapshot for its whole
|
|
lifetime, so it never sees a partial write from a concurrent commit (see
|
|
[transactions](transactions.md)).
|
|
|
|
## Reading the past
|
|
|
|
- **Current head** — by default a read targets the current head of the bound branch.
|
|
- **By snapshot id** — read a branch or a specific snapshot id (`--snapshot` on
|
|
`omnigraph read`).
|
|
- **By version** — reconstruct a historical snapshot from any past manifest version.
|
|
- **Single entity** — look up one entity at a past version without building a full
|
|
snapshot (cheaper when you only need one node or edge).
|
|
|
|
Snapshots are cheap to build: a snapshot is just the set of visible sub-table
|
|
versions at a manifest version, so cross-table reads stay snapshot-isolated.
|
|
|
|
## CLI
|
|
|
|
```bash
|
|
# Read a query against a past snapshot
|
|
omnigraph read --query ./q.gq --name find --snapshot <snapshot-id> s3://bucket/graph.omni
|
|
```
|
|
|
|
Time travel composes with branches: every branch has its own version history, and
|
|
you can read any branch at any of its past versions. Commits and the commit DAG
|
|
that these versions correspond to are described in
|
|
[branches & commits](index.md); diffing two versions is on the
|
|
[changes](changes.md) page.
|