Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

Concepts

Topology, kept separate from meaning and storage

oxgraph models graph and hypergraph topology — the question of what connects to what — and keeps it separate from what the data means and where it is stored.

  • The foundation defines connectivity and refuses to interpret it.
  • Layouts decide the byte representation.
  • Properties and domain meaning live in layers above.

Algorithms bind to capability traits, not to a concrete container, so the same BFS runs over an in-memory layout, a memory-mapped file, or rows read from a database. An algorithm declares the capabilities it needs — a forward BFS needs only outgoing traversal; a reverse query needs incoming traversal — and any layout that satisfies them works unchanged.

Why it exists

Graph-shaped data shows up everywhere: compilers, databases, knowledge graphs, provenance, build systems. Most of those systems rebuild large topology into a heap-owned graph before they can traverse it, and most reinvent node and edge IDs, adjacency, serialization, and validation while doing it.

oxgraph splits those concerns apart so one narrow goal drives the design: open a large graph from a snapshot, memory-map it, and start traversing without rebuilding it in memory.

The pipeline: bytes → validate → view → traverse

A snapshot is a topology-agnostic byte container. You validate it once, then borrow its sections as typed slices and point a layout view at them. From there you traverse directly against the bytes — there is no owned graph rebuilt in RAM. The Getting started example runs the whole pipeline in one file.

Verification

The substrate is unsafe-free (unsafe_code = "forbid"). Correctness is defended by proptest strategies, miri on the zero-copy borrow path, and cargo kani algebraic proofs (symmetry, totality, roundtrip, merge laws). The 0.4.0 release verifies 104 kani proof harnesses with 0 failures, plus a freeze→open differential proptest against an owned-index oracle.