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 graph at uri from schema source.

Strict mode: errors with OmniError::AlreadyInitialized if uri already holds any of the three schema artifacts. To overwrite an existing graph deliberately, call Self::init_with_options with InitOptions { force: true }.

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

Create a new graph at uri, with explicit init-time options.

See InitOptions for the safety contract — by default this behaves identically to Self::init.

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

Open an existing graph (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 graph 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 fn with_policy(self, checker: Arc<dyn PolicyChecker>) -> Self

Install a policy checker for engine-layer enforcement (MR-722). Builder-style setter — consumes self, returns Self. Calling this on a Omnigraph previously without policy enables enforce() to fire at every mutating engine method that’s been wired to call it (currently apply_schema_as; PR #3 fans out to the remaining writers).

Embedded callers that don’t care about authorization should just not call this. Server / CLI callers that have loaded a PolicyEngine from policy.yaml pass it here.

pub fn with_embedding_config(self, config: Arc<EmbeddingConfig>) -> Self

Install a pre-resolved embedding config (RFC-012 Phase 5). Builder-style, mirroring Omnigraph::with_policy: a graph served from a cluster embedding provider profile injects it here; an embedded/CLI caller that doesn’t call this keeps the EmbeddingClient::from_env() fallback.

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

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

pub async fn preview_schema_apply_with_options( &self, desired_schema_source: &str, options: SchemaApplyOptions, ) -> Result<SchemaApplyPreview>

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

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

pub async fn apply_schema_as( &self, desired_schema_source: &str, options: SchemaApplyOptions, actor: Option<&str>, ) -> Result<SchemaApplyResult>

Apply a schema migration with an explicit actor for engine-layer policy enforcement (MR-722). When a PolicyChecker is installed via Self::with_policy, this method calls enforce(SchemaApply, Branch("main"), actor) before any apply work happens. Denial returns OmniError::Policy and leaves the manifest untouched.

The no-actor variants (apply_schema, apply_schema_with_options) pass None here. They work fine without a policy; if a policy IS installed and actor is None, enforcement intentionally fails to prevent silent-bypass-via-forgetting-the-actor footguns.

pub async fn apply_schema_as_with_catalog_check<F>( &self, desired_schema_source: &str, options: SchemaApplyOptions, actor: Option<&str>, validate_catalog: F, ) -> Result<SchemaApplyResult>

where F: FnOnce(&Catalog) -> Result<()>,

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 heal 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 graph: data on new schema, catalog on old).
3. heal_pending_sidecars_roll_forward — close the finalize→publisher residual via roll-forward; defer rollback work to next ReadWrite open. Serializes against live writers by acquiring each sidecar’s per-(table_key, branch) write queues, so refresh never rolls forward an in-flight writer’s sidecar from under it.
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.

The staged-write entry points (load_as, mutate_as) run the same heal via heal_pending_recovery_sidecars, so a long-lived server converges on the next write without an explicit refresh. 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<Vec<PendingIndex>>

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. Returns the declared indexes that could not be materialized on this pass (today: vector columns with no trainable vectors yet). They are deferred, not errors; a later ensure_indices/optimize builds them once the column is trainable. Reads stay correct (brute-force) meanwhile.

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

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 repair(&self, options: RepairOptions) -> Result<RepairStats>

Classify and explicitly repair uncovered manifest/head drift. See [repair] for the distinction between safe maintenance drift and suspicious/unverifiable drift.

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_as( &self, name: &str, actor: Option<&str>, ) -> Result<()>

Create a branch from the coordinator’s currently-open snapshot, with an explicit actor for engine-layer policy enforcement (MR-722 fan-out). Scope is TargetBranch(name) — symmetric with branch_delete_as: the branch being acted upon is the target. Cedar rules using target_branch_scope: protected therefore see the new-branch name and can deny e.g. creating any branch named main from a non-privileged actor.

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

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

Create a branch from a specific source branch with an explicit actor for engine-layer policy enforcement (MR-722 fan-out).

Scope is BranchTransition { source, target } — matches the HTTP-layer convention at server_branch_create (branch=Some(from), target_branch=Some(name)), so engine and HTTP fire the same Cedar decision. Pinned-snapshot sources (which aren’t a branch ref) materialize as the sentinel <snapshot> for the policy check; Cedar rules using branch_scope: any still match, rules pinning a specific source branch correctly do not.

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

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

pub async fn branch_delete_as( &self, name: &str, actor: Option<&str>, ) -> Result<()>

Delete a branch with an explicit actor for engine-layer policy enforcement (MR-722 fan-out). Scope is TargetBranch(name) — matches the HTTP-layer convention at server_branch_delete (branch=None, target_branch=Some(name)). Cedar rules using target_branch_scope: protected therefore correctly gate deletion of protected branches (e.g. deny BranchDelete against main).

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>

👎Deprecated:

use load_as with an explicit base instead; the ingest family will be removed in a future release

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

👎Deprecated:

use load_as with an explicit base instead; the ingest family will be removed in a future release

Deprecated shim over the unified load_as. Preserves the historical ingest contract exactly: from: None means fork from main, and the base branch is recorded in the result even when the target branch already existed (no fork happened).

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

👎Deprecated:

use load_file_as with an explicit base instead; the ingest family will be removed in a future release

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

👎Deprecated:

use load_file_as with an explicit base instead; the ingest family will be removed in a future release

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

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

Load JSONL data onto branch.

base selects the branch-creation behavior: with Some(base), a missing target branch is forked from base first (the former ingest semantics); with None, the target branch must already exist — staging fails on an unknown branch when it resolves the manifest snapshot, so a typo’d branch name can never create one.

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

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

Read a file into memory and delegate to load_as. Used by the CLI’s omnigraph load so file-path-based writes flow through the same engine-layer policy gate as in-memory load_as calls.