apunkt/omnigraph
1
0
Fork 0
mirror of https://github.com/ModernRelay/omnigraph.git synced 2026-06-15 01:55:13 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions
omnigraph/docs/user/branching/time-travel.md
Andrew Altshuler 612741b387
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>
2026-06-14 13:53:46 +03:00

1.3 KiB
Raw Blame History

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).

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

# 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; diffing two versions is on the changes page.