Rust Quick Start

The Rust crate is the primary way to use TaiDB. It avoids process spawning, keeps errors typed, and exposes configuration for compression, encryption, durability, and memory-mapped reads.

Create a project

cargo new taidb-demo
cd taidb-demo
cargo add taidb

Store text and vectors

Replace src/main.rs:

use taidb::{EngineConfig, Options};

fn main() -> taidb::Result<()> {
    let options = Options::builder().flush().zstd_fast().build();
    let mut db = EngineConfig::new("./app.taidb")
        .options(options)
        .open()?;

    db.put_text("user:1", "Alice")?;
    db.put_text("user:2", "Bob")?;

    db.put_vector("vec:alice", &[0.1, 0.9, 0.2])?;
    db.put_vector("vec:bob", &[0.9, 0.1, 0.1])?;

    if let Some(name) = db.get_text("user:1")? {
        println!("user:1 = {name}");
    }

    for info in db.scan_prefix("user:", 10) {
        println!("key = {}", String::from_utf8_lossy(&info.key));
    }

    for hit in db.search_vector(&[0.0, 1.0, 0.2], 2)? {
        println!("{}\t{:.6}", String::from_utf8_lossy(&hit.key), hit.score);
    }

    Ok(())
}

Run it:

cargo run

Use explicit options

EngineConfig is convenient for common setup. Use lower-level options when you need full control.

use taidb::{Durability, EngineConfig, Options};

fn main() -> taidb::Result<()> {
    let options = Options::builder()
        .durability(Durability::Sync)
        .zstd(3, 256)
        .mmap_reads(true)
        .build();

    let mut db = EngineConfig::new("./sync-compressed.taidb")
        .options(options)
        .open()?;

    db.put_text("config:mode", "sync")?;
    db.flush()?;

    Ok(())
}

Batch writes

Batch writes reduce per-record overhead for bulk inserts.

use taidb::EngineConfig;

fn main() -> taidb::Result<()> {
    let mut db = EngineConfig::new("./batch.taidb").open()?;

    let report = db.write_text_batch([
        ("doc:1", "first document"),
        ("doc:2", "second document"),
        ("doc:3", "third document"),
    ])?;

    println!("wrote {} records", report.operations);
    Ok(())
}

Inspect and maintain

let stats = db.stats()?;
println!("keys={} vectors={}", stats.keys, stats.vectors);

let verify = db.verify()?;
println!("verified {} bytes", verify.bytes_verified);

db.compact()?;

Error handling

All high-level operations return taidb::Result<T>. Keep the error in your own application boundary instead of converting it to a string too early:

fn open_app_db(path: &str) -> taidb::Result<taidb::TaiDbEngine> {
    taidb::EngineConfig::new(path).zstd_fast().open()
}

This lets callers distinguish invalid input, corruption, encryption failures, and filesystem errors.