Time Travel

Every write to an Omnigraph repository creates a new immutable snapshot. Because snapshots are never modified or deleted, you can read the graph as it existed at any point in its history.

How snapshots work

A snapshot is a version-numbered, immutable record of the entire graph state at a moment in time. Each branch points to a snapshot, and every write advances the branch to a new one.

Snapshots are not diffs or deltas — each snapshot is a self-contained view of the graph. Under the hood, unchanged tables are shared across snapshots (copy-on-write), so storage grows only with actual changes.

Key properties:

• Immutable — Once created, a snapshot is never modified.
• Version-numbered — Snapshots are identified by a monotonically increasing integer.
• Per-repository — Snapshot versions are global to the repository, not per-branch.

Reading the current snapshot

To see the current snapshot version and table state of a branch:

omnigraph snapshot ./repo.omni

{
  "branch": "main",
  "manifest_version": 5,
  "tables": [
    { "table_key": "Person", "table_version": 3, "table_branch": "main", "row_count": 847 },
    { "table_key": "Company", "table_version": 2, "table_branch": "main", "row_count": 124 },
    { "table_key": "WorksAt", "table_version": 2, "table_branch": "main", "row_count": 912 }
  ]
}

The manifest_version is the snapshot version. Each table has its own version that advances independently when that table is modified.

Querying at a specific version

Use the --snapshot flag to read the graph as it existed at a past snapshot version:

omnigraph read ./repo.omni \
    --query queries.gq \
    --name friends_of \
    --params '{"name": "Alice"}' \
    --snapshot 3

This runs the query against the graph state at snapshot version 3, regardless of what the current version is. The result reflects exactly the data that existed at that point in time.

The --snapshot flag works with any read command:

omnigraph read ./repo.omni \
    --query queries.gq \
    --name all_people \
    --snapshot 1 \
    --json

Diffing between points in time

Compare the graph at two different snapshot versions to understand what changed:

omnigraph diff ./repo.omni --from 3 --to 5

{
  "from_version": 3,
  "to_version": 5,
  "changes": [
    {
      "table": "Person",
      "inserts": 12,
      "updates": 3,
      "deletes": 0
    },
    {
      "table": "WorksAt",
      "inserts": 8,
      "updates": 0,
      "deletes": 2
    }
  ]
}

Change classification

Each row-level change falls into one of three categories:

Use cases

• Debugging — Query the graph before and after a mutation to isolate what changed.
• Auditing — Review the exact state of the graph at the time a decision was made.
• Reproducibility — Re-run a query at a known snapshot to reproduce past results.
• Rollback analysis — Compare the current state with a known-good snapshot to decide whether to revert.