Struct Omnigraph 

pub struct Omnigraph { /* private fields */ }

Top-level handle to an Omnigraph database.

An Omnigraph is a Lance-native graph database with git-style branching. It stores typed property graphs as per-type Lance datasets coordinated through a Lance manifest table.

Implementations

impl Omnigraph

pub async fn init(uri: &str, schema_source: &str) -> Result<Self>

Create a new repo at uri from schema source.

Creates _schema.pg, per-type Lance datasets, and __manifest.

pub async fn open(uri: &str) -> Result<Self>

Open an existing repo (read-write).

Reads _schema.pg, parses it, builds the catalog, and opens __manifest. Runs the open-time recovery sweep before returning — see OpenMode.

pub async fn open_read_only(uri: &str) -> Result<Self>

Open an existing repo for read-only consumers (NDJSON export, commit list, etc.). Skips the recovery sweep — see OpenMode.

pub fn catalog(&self) -> Arc<Catalog>

Returns an Arc<Catalog> snapshot. Cheap clone of the current catalog pointer; callers can hold the returned Arc across awaits without blocking concurrent apply_schema.

pub fn schema_source(&self) -> Arc<String>

Returns an Arc<String> snapshot of the schema source.

pub fn uri(&self) -> &str

pub async fn plan_schema( &self, desired_schema_source: &str, ) -> Result<SchemaMigrationPlan>

pub async fn apply_schema( &self, desired_schema_source: &str, ) -> Result<SchemaApplyResult>

pub async fn snapshot_of( &self, target: impl Into<ReadTarget>, ) -> Result<Snapshot>

pub async fn version_of(&self, target: impl Into<ReadTarget>) -> Result<u64>

pub async fn resolved_branch_of( &self, target: impl Into<ReadTarget>, ) -> Result<Option<String>>

pub async fn sync_branch(&self, branch: &str) -> Result<()>

Synchronize this handle’s write base to the latest head of the named branch.

pub async fn refresh(&self) -> Result<()>

Re-read the handle-local coordinator state from storage AND run in-process recovery. Closes the Phase B → Phase C residual (e.g. MutationStaging::finalize crash mid-publish in a long-running server) without restart.

Composition mirrors Omnigraph::open_with_storage_and_mode’s recovery sequence, in the same order, with one restriction: the manifest-drift sweep runs in RollForwardOnly mode (rollback / abort cases defer to the next ReadWrite open because Dataset::restore is unsafe under concurrency). Each step:

1. coordinator.refresh() — re-read manifest.
2. recover_schema_state_files — complete an in-flight schema_apply’s staging→final rename if a SchemaApply sidecar is on disk; idempotent + early-returns when no staging files exist. Required BEFORE manifest-drift recovery so a SchemaApply roll-forward doesn’t publish the manifest while the staging files remain unrenamed (which would corrupt the repo: data on new schema, catalog on old).
3. recover_manifest_drift(... RollForwardOnly) — close the finalize→publisher residual via roll-forward; defer rollback work to next ReadWrite open.
4. runtime_cache.invalidate_all — drop stale per-snapshot caches.

Steady state cost: one list_dir of __recovery/ (typically returns empty → early return for both passes). No additional Lance reads.

Engine-internal callers that already hold an in-flight sidecar (e.g. schema_apply mid-write) MUST use refresh_coordinator_only to avoid the recovery sweep racing their own sidecar.

pub async fn resolve_snapshot(&self, branch: &str) -> Result<SnapshotId>

pub async fn diff_between( &self, from: impl Into<ReadTarget>, to: impl Into<ReadTarget>, filter: &ChangeFilter, ) -> Result<ChangeSet>

pub async fn diff_commits( &self, from_commit_id: &str, to_commit_id: &str, filter: &ChangeFilter, ) -> Result<ChangeSet>

Diff two graph commits. Resolves each commit to (manifest_branch, manifest_version) and creates branch-aware snapshots. Supports cross-branch comparison.

pub async fn entity_at_target( &self, target: impl Into<ReadTarget>, table_key: &str, id: &str, ) -> Result<Option<Value>>

pub async fn entity_at( &self, table_key: &str, id: &str, version: u64, ) -> Result<Option<Value>>

Read one entity at a specific manifest version via time travel (on-demand enrichment).

pub async fn snapshot_at_version(&self, version: u64) -> Result<Snapshot>

Create a Snapshot at any historical manifest version.

pub async fn export_jsonl( &self, branch: &str, type_names: &[String], table_keys: &[String], ) -> Result<String>

pub async fn export_jsonl_to_writer<W: Write>( &self, branch: &str, type_names: &[String], table_keys: &[String], writer: &mut W, ) -> Result<()>

pub async fn graph_index(&self) -> Result<Arc<GraphIndex>>

Get or build the graph index for the current snapshot.

pub async fn ensure_indices(&self) -> Result<()>

Ensure BTree scalar indices exist on key columns. Idempotent — Lance skips if index already exists.

Opens sub-tables at their latest version (not snapshot-pinned) because indices must be created on the current head. Any version drift from the snapshot is expected and logged. The resulting versions are committed back to the manifest.

On named branches, indexing preserves lazy branching: unbranched subtables keep inheriting main, while subtables inherited from an ancestor branch are first forked into the active branch before their index metadata is updated.

pub async fn ensure_indices_on(&self, branch: &str) -> Result<()>

pub async fn optimize(&self) -> Result<Vec<TableOptimizeStats>>

Compact small Lance fragments into fewer larger ones across every node + edge table on main. See [optimize] for details.

pub async fn cleanup( &mut self, options: CleanupPolicyOptions, ) -> Result<Vec<TableCleanupStats>>

Remove Lance manifests (and the fragments they uniquely own) per the given optimize::CleanupPolicyOptions. Destructive to version history. See [optimize] for details.

pub async fn read_blob( &self, type_name: &str, id: &str, property: &str, ) -> Result<BlobFile>

Read a blob from a node by its string ID and property name.

Returns a BlobFile handle with async read(), seek(), tell(), and metadata accessors (size(), kind(), uri()).

let blob = db.read_blob("Document", "readme", "content").await?;
let bytes = blob.read().await?;

pub async fn branch_create(&self, name: &str) -> Result<()>

pub async fn branch_create_from( &self, from: impl Into<ReadTarget>, name: &str, ) -> Result<()>

pub async fn branch_list(&self) -> Result<Vec<String>>

pub async fn branch_delete(&self, name: &str) -> Result<()>

pub async fn get_commit(&self, commit_id: &str) -> Result<GraphCommit>

pub async fn list_commits( &self, branch: Option<&str>, ) -> Result<Vec<GraphCommit>>

impl Omnigraph

pub async fn branch_merge( &self, source: &str, target: &str, ) -> Result<MergeOutcome>

pub async fn branch_merge_as( &self, source: &str, target: &str, actor_id: Option<&str>, ) -> Result<MergeOutcome>

impl Omnigraph

pub async fn mutate( &self, branch: &str, query_source: &str, query_name: &str, params: &ParamMap, ) -> Result<MutationResult>

pub async fn mutate_as( &self, branch: &str, query_source: &str, query_name: &str, params: &ParamMap, actor_id: Option<&str>, ) -> Result<MutationResult>

impl Omnigraph

pub async fn query( &self, target: impl Into<ReadTarget>, query_source: &str, query_name: &str, params: &ParamMap, ) -> Result<QueryResult>

Run a named query against an explicit branch or snapshot target.

pub async fn run_query_at( &self, version: u64, query_source: &str, query_name: &str, params: &ParamMap, ) -> Result<QueryResult>

Run a named query against the graph as it existed at a prior manifest version.

Compiles the query normally, builds a temporary (non-cached) graph index if traversal is needed, and executes against the historical snapshot.

impl Omnigraph

pub async fn ingest( &self, branch: &str, from: Option<&str>, data: &str, mode: LoadMode, ) -> Result<IngestResult>

pub async fn ingest_as( &self, branch: &str, from: Option<&str>, data: &str, mode: LoadMode, actor_id: Option<&str>, ) -> Result<IngestResult>

pub async fn ingest_file( &self, branch: &str, from: Option<&str>, path: &str, mode: LoadMode, ) -> Result<IngestResult>

pub async fn ingest_file_as( &self, branch: &str, from: Option<&str>, path: &str, mode: LoadMode, actor_id: Option<&str>, ) -> Result<IngestResult>

pub async fn load( &self, branch: &str, data: &str, mode: LoadMode, ) -> Result<LoadResult>

pub async fn load_as( &self, branch: &str, data: &str, mode: LoadMode, actor_id: Option<&str>, ) -> Result<LoadResult>

pub async fn load_file( &self, branch: &str, path: &str, mode: LoadMode, ) -> Result<LoadResult>