Omnigraph Atlas Omnigraph's documentation, bound to its Rust workspace
79 documents

Omnigraph Atlas

Omnigraph's documentation, bound to its Rust workspace

Journeys

Quickstart: zero to a query

The shortest path from a fresh install to a graph you can query — schema, init, load, query, branch — entirely on a local file-backed graph, no server.

5 stops →

Deploy a cluster as code

How a deployment goes from a folder of declarations to N graphs served behind policy — the Terraform-style declare → plan → apply → serve loop.

5 stops →

How a write becomes durable

Follow a mutation from the query executor through in-memory staging, the single manifest-publish CAS fence, and crash recovery — the heart of Omnigraph's atomicity guarantee.

5 stops →

Query & retrieval runtime

How one query runtime fuses graph traversal, vector ANN, and full-text search — the .gq surface, the search functions, RRF fusion, embeddings, and the executor underneath.

5 stops →

Getting Started

Omnigraph in one sitting — what it is (a lakehouse graph database for context assembly and multi-agent coordination), how to install the `omnigraph` CLI and `omnigraph-server`, and the five-step core loop (schema → init → load → query → branch) on a local file-backed graph. Start here, then branch into the user guide.

  • Install When installing or upgrading Omnigraph binaries, choosing a release channel, or building from source on any platform.
  • Quickstart First hands-on session — define a schema, load data, query, and use a branch end to end without standing up a server.
  • README Anyone new to Omnigraph wanting the full capability and architecture overview, the crate map, and pointers to deeper guides.
  • User Docs When you need to find which user doc covers a given task and want the map of the docs/user tree.

User Guide

The task-oriented user manual: the `.pg` schema and `.gq` query languages, mutations, vector / full-text / hybrid (RRF) search and embeddings, Git-style branching, merge, time-travel and transactions, the cluster control plane (declare → plan → apply → serve), the full CLI reference, and day-2 operations — the HTTP server, Cedar policy, audit, errors, and storage maintenance.

  • Audit & Actor Tracking Read when you need to attribute graph changes to actors, inspect commit history, or distinguish system-initiated writes from operator ones.
  • Authorization (Cedar policy) Read when writing or testing Cedar policy, choosing actions/scopes, or understanding the three auth runtime states and actor resolution.
  • Branches, Commits, Snapshots Read for the branch and commit-DAG mechanics — creating/listing/deleting branches, lazy forking, commit metadata, and finding recovery commits.
  • Change Detection / Diff Read when you need to diff two branches/commits programmatically and want the algorithm, the diff API signatures, and the change/filter types.
  • CLI Guide Read to get productive with the CLI fast — the everyday commands, the catalog-vs-ad-hoc distinction, addressing, and the renamed verbs.
  • CLI Reference (`omnigraph`) Read as the authoritative lookup for any command's flags, the capability/addressing rules, the operator config schema, credential resolution, or destructive-write guards.
  • Cluster Config Read as the lookup reference for exact cluster.yaml keys, state.json fields, plan dispositions, diagnostic codes, or per-command edge-case behavior.
  • Concepts Read first if you're new to Omnigraph and need the mental model — the data model, the L1/L2 split, and how schema, query, engine, and front ends fit together.
  • Constants & Tunables (cheat sheet) Read when you need a specific constant's value, an environment-variable default, or the precise Expand traversal dispatch tuning knobs.
  • Deployment Read when deploying or self-hosting the server — choosing a storage shape, writing container/AWS/Railway configs, wiring bearer-token sources, or testing against local S3.
  • Embeddings Read when configuring the embedding provider, populating vector columns, or debugging a nearest model-mismatch rejection.
  • Errors and Result Serialization Read when handling or interpreting Omnigraph errors, manifest/CAS conflicts, or choosing a query-result serialization format.
  • HTTP Server (`omnigraph-server`) Read when deploying or calling the HTTP server: boot flags, endpoint/auth matrix, deprecated aliases, admission/429 behavior, or the stored-query catalog.
  • Indexes Read when reasoning about which index a column gets, why an equality filter is slow, or why a vector index is pending until optimize.
  • Maintenance: Optimize, Repair & Cleanup Read when running storage maintenance — compaction/reindex, healing drift, or garbage-collecting old versions — or to understand the optimize/repair/cleanup safety gates.
  • Merging Branches Read before merging branches or when handling merge failures — to know the outcomes, the conflict taxonomy, and how conflicts surface over CLI and HTTP.
  • Mutations Read when writing mutation queries, reasoning about per-query atomicity, or deciding between inline mutations and `omnigraph load`.
  • Operating an OmniGraph Cluster Read when operating a deployment: standing up a cluster, running the day-2 apply loop, handling drift, approving deletions, or recovering from a crashed apply.
  • Query Language (`.gq`) Read when authoring read queries, traversals, or orderings in `.gq`, or tuning how variable-length expands are executed.
  • Schema Language (`.pg`) Read when writing or evolving a `.pg` schema, choosing scalar types and constraints, or planning a migration with potential data loss.
  • Schema lint Read when you hit a schema-migration rejection code, or want to know which lint families and severity/suppression features exist versus are still planned.
  • Search Read when adding vector, full-text, or hybrid (RRF) search to a query, or scoring/ranking results.
  • Snapshots & Time Travel Read when you need to query historical state, read a specific snapshot/version, or understand snapshot isolation guarantees.
  • Storage Read when you need to understand the physical disk layout, the manifest schema, concurrency/CAS semantics, or the internal schema migration stamps.
  • Transactions in OmniGraph Read when you need atomicity across multiple operations or are coming from SQL transactions and want the branch-based equivalents and their trade-offs.

Architecture & Internals

The contributor's map of how Omnigraph actually works: the compiler → engine → storage-seam → Lance layering, the direct-publish write path and its four-phase recovery protocol, query/mutation execution, three-way merge, the Lance substrate-alignment log, the hard invariants every change is measured against, the test surface, and CI / governance mechanics.

  • Architectural Invariants Read before proposing, reviewing, or implementing any change — it is the architectural contract and deny-list every PR is checked against.
  • Architecture Read when you need the mental model of how a request flows through compiler, engine, storage seam, and Lance before changing any cross-layer behavior.
  • Branch protection on `main` Read when changing what gates merges to main, adding a required check, or recovering/auditing branch-protection state.
  • CI / Release Workflows Read when changing CI, debugging why a PR check is or isn't running, or before merging non-trivial work given main is not gated by the full test suite.
  • Code ownership Read before changing code ownership or reviewer requirements — always edit codeowners-roles.yml and re-render, never CODEOWNERS directly.
  • Developer Docs Read first when you are a contributor or agent picking up any non-trivial Omnigraph change and need to find which doc owns the area you are about to touch.
  • Direct-Publish Write Path Read before adding or modifying any write path, recovery sidecar, or anything that can advance Lance HEAD before the manifest publish.
  • Lance Docs Index (for OmniGraph agents) Read before touching anything Lance-shaped (manifest, fragments, indexes, transactions, compaction) or before performing a Lance version bump.
  • Merging (three-way) and Conflicts Read when working on branch merge logic, conflict detection, or the merge-conflict error/HTTP shape.
  • OmniGraph — Architecture & Technology (code-verified) Read when you want ground-truth, citation-backed numbers and component facts (LOC, crate boundaries, exact call sites) rather than the conceptual prose in architecture.md.
  • Query Execution, Mutations, and Loading Read when changing query execution, mutation routing/staging, or the bulk loader, or when you need the exact function and line where a read/write step happens.
  • Testing Read before writing or modifying any test, to find existing coverage, the right helpers, and the file that owns the area you are changing.

Design RFCs & Plans

The design track — internal team RFCs (rfc-001…012) plus the cluster-control-plane specs and axioms that drive Omnigraph's in-flight evolution: the query envelope + stored queries + MCP, the config/CLI re-architecture (operator config, omnigraph.yaml deprecation, unified access paths, plane restructuring), cluster apply/boot, provider-independent embeddings, and the Azure-backend proposal. Many describe planned or partially-landed work — read them with the drift report open.

Project & Governance

Repo-level context for contributors and agents — the contribution guide, governance model, security policy, code of conduct, the per-repo agent instructions (AGENTS.md, CLAUDE.md), and the bundled `omnigraph` operational skill with its reference playbooks.

Releases

Versioned release notes — user-visible behavior changes, breaking changes, and upgrade guidance between Omnigraph versions.

  • Omnigraph v0.7.0 Before upgrading to v0.7.0 or auditing scripts — especially for the omnigraph.yaml removal, the --cluster-only server boot, required load --mode, and the embedding default flip.