Struct Uni 

pub struct Uni { /* private fields */ }

Main entry point for Uni embedded database.

Handles storage, schema, and query execution. It coordinates the various subsystems including the storage engine, query executor, and graph algorithms.

Examples

Local Usage

use uni_db::Uni;

#[tokio::main]
async fn main() -> Result<(), uni_db::UniError> {
    let db = Uni::open("./my_db")
        .build()
        .await?;

    // Run a query
    let results = db.query("MATCH (n) RETURN count(n)").await?;
    println!("Count: {:?}", results);
    Ok(())
}

Hybrid Storage (S3 + Local)

Store bulk data and catalog metadata in S3 (or GCS/Azure) while keeping WAL/ID allocation local.

use uni_db::Uni;

#[tokio::main]
async fn main() -> Result<(), uni_db::UniError> {
    // Requires `object_store` features enabled (aws, gcp, azure)
    let db = Uni::open("./local_meta")
        .hybrid("./local_meta", "s3://my-bucket/graph-data")
        .build()
        .await?;
    Ok(())
}

Implementations

impl Uni

pub fn locy(&self) -> LocyEngine<'_>

Create a Locy evaluation engine bound to this database.

impl Uni

pub async fn explain(&self, cypher: &str) -> Result<ExplainOutput>

Explain a Cypher query plan without executing it.

pub async fn profile( &self, cypher: &str, ) -> Result<(QueryResult, ProfileOutput)>

Profile a Cypher query execution.

pub async fn query(&self, cypher: &str) -> Result<QueryResult>

Execute a Cypher query

pub async fn query_cursor(&self, cypher: &str) -> Result<QueryCursor>

Execute query returning a cursor for streaming results

pub fn query_with(&self, cypher: &str) -> QueryBuilder<'_>

Execute a query with parameters using a builder

pub fn execute_with(&self, cypher: &str) -> QueryBuilder<'_>

Execute a mutation with parameters using a builder.

Alias for query_with that clarifies intent for mutation queries. Use .param() to bind parameters, then .execute() to run the mutation.

Examples

db.execute_with("CREATE (p:Person {name: $name, age: $age})")
    .param("name", "Alice")
    .param("age", 30)
    .execute()
    .await?;

pub async fn execute(&self, cypher: &str) -> Result<ExecuteResult>

Execute a modification query (CREATE, SET, DELETE, etc.) Returns the number of affected rows/elements

impl Uni

pub fn schema(&self) -> SchemaBuilder<'_>

pub async fn load_schema(&self, path: impl AsRef<Path>) -> Result<()>

pub async fn save_schema(&self, path: impl AsRef<Path>) -> Result<()>

impl Uni

pub async fn begin(&self) -> Result<Transaction<'_>>

pub async fn transaction<'a, F, T>(&'a self, f: F) -> Result<T>

where F: for<'b> FnOnce(&'b mut Transaction<'a>) -> BoxFuture<'b, Result<T>>,

impl Uni

pub fn xervo(&self) -> Result<UniXervo>

Access Uni-Xervo runtime facade configured for this database.

impl Uni

pub fn open(uri: impl Into<String>) -> UniBuilder

Open or create a database at the given path.

If the database does not exist, it will be created.

Arguments

• uri - Local path or object store URI.

Returns

A UniBuilder to configure and build the database instance.

pub fn open_existing(uri: impl Into<String>) -> UniBuilder

Open an existing database at the given path. Fails if it does not exist.

pub fn create(uri: impl Into<String>) -> UniBuilder

Create a new database at the given path. Fails if it already exists.

pub fn temporary() -> UniBuilder

Create a temporary database that is deleted when dropped.

Useful for tests and short-lived processing. Note: Currently uses a temporary directory on the filesystem.

pub fn in_memory() -> UniBuilder

Open an in-memory database (alias for temporary).

pub fn config(&self) -> &UniConfig

Get configuration

pub fn procedure_registry(&self) -> &Arc<ProcedureRegistry>

Returns the procedure registry for registering test procedures.

pub fn get_schema(&self) -> Arc<Schema>

Get current schema (read-only snapshot)

pub fn bulk_writer(&self) -> BulkWriterBuilder<'_>

Create a bulk writer for efficient data loading.

pub fn session(&self) -> SessionBuilder<'_>

Create a session builder for scoped query context.

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

Flush all uncommitted changes to persistent storage (L1).

This forces a write of the current in-memory buffer (L0) to columnar files. It also creates a new snapshot.

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

Create a named point-in-time snapshot of the database.

This flushes current changes and records the state. Returns the snapshot ID.

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

Create a persisted named snapshot that can be retrieved later.

pub async fn list_snapshots(&self) -> Result<Vec<SnapshotManifest>>

List all available snapshots.

pub async fn restore_snapshot(&self, snapshot_id: &str) -> Result<()>

Restore the database to a specific snapshot.

Note: This currently requires a restart or re-opening of Uni to fully take effect as it only updates the latest pointer.

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

Check if a label exists in the schema.

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

Check if an edge type exists in the schema.

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

Get all label names. Returns the union of schema-registered labels (Active state) and labels discovered from data (for schemaless mode where labels may not be in the schema). This is consistent with list_edge_types() for schema labels while also supporting schemaless workflows.

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

Get all edge type names.

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

Get detailed information about a label.

pub async fn compact_label(&self, label: &str) -> Result<CompactionStats>

Manually trigger compaction for a specific label.

Compaction merges multiple L1 files into larger files to improve read performance.

pub async fn compact_edge_type( &self, edge_type: &str, ) -> Result<CompactionStats>

Manually trigger compaction for a specific edge type.

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

Wait for any ongoing compaction to complete.

Useful for tests or ensuring consistent performance before benchmarks.

pub async fn bulk_insert_vertices( &self, label: &str, properties_list: Vec<Properties>, ) -> Result<Vec<Vid>>

Bulk insert vertices for a given label.

This is a low-level API intended for bulk loading and benchmarking. Each properties map should contain all property values as JSON.

Returns the allocated VIDs in the same order as the input.

pub async fn bulk_insert_edges( &self, edge_type: &str, edges: Vec<(Vid, Vid, Properties)>, ) -> Result<()>

Bulk insert edges for a given edge type using pre-allocated VIDs.

This is a low-level API intended for bulk loading and benchmarking. Each tuple is (src_vid, dst_vid, properties).

pub async fn index_rebuild_status(&self) -> Result<Vec<IndexRebuildTask>>

Get the status of background index rebuild tasks.

Returns all tracked index rebuild tasks, including pending, in-progress, completed, and failed tasks. Use this to monitor progress of async index rebuilds started via BulkWriter::commit() with async_indexes(true).

Example

let status = db.index_rebuild_status().await?;
for task in status {
    println!("Label: {}, Status: {:?}", task.label, task.status);
}

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

Retry failed index rebuild tasks.

Resets failed tasks back to pending state and returns the task IDs that will be retried. Tasks that have exceeded their retry limit will not be retried.

Returns

A vector of task IDs that were scheduled for retry.

pub async fn rebuild_indexes( &self, label: &str, async_: bool, ) -> Result<Option<String>>

Force rebuild indexes for a specific label.

Arguments

• label - The vertex label to rebuild indexes for.
• async_ - If true, rebuild in background; if false, block until complete.

Returns

When async_ is true, returns the task ID for tracking progress. When async_ is false, returns None after indexes are rebuilt.

pub async fn is_index_building(&self, label: &str) -> Result<bool>

Check if an index is currently being rebuilt for a label.

Returns true if there is a pending or in-progress index rebuild task for the specified label.

pub fn list_indexes(&self, label: &str) -> Vec<IndexDefinition>

List all indexes defined on a specific label.

pub fn list_all_indexes(&self) -> Vec<IndexDefinition>

List all indexes in the database.

pub async fn shutdown(self) -> Result<()>

Shutdown the database gracefully, flushing pending data and stopping background tasks.

This method flushes any pending data and waits for all background tasks to complete (with a timeout). After calling this method, the database instance should not be used.

Trait Implementations

impl Drop for Uni

fn drop(&mut self)

Executes the destructor for this type.