Rust API

The public Rust API is the primary supported interface. It is currently evolving toward the 1.0.0 stability target.

High-level engine

Use EngineConfig to open TaiDbEngine:

use taidb::EngineConfig;

let mut db = EngineConfig::new("./app.taidb").open()?;

Common methods:

Method	Purpose
put_text(key, value)	Store UTF-8 text.
get_text(key)	Read UTF-8 text.
put_bytes(key, value)	Store bytes.
get_bytes(key)	Read bytes.
delete(key)	Delete one key.
put_vector(key, vector)	Store an f32 vector.
get_vector(key)	Read an f32 vector.
search_vector(query, limit)	Exact cosine vector search.
write_text_batch(values)	Batch text writes.
list_keys(prefix, limit)	List key metadata.
scan_prefix(prefix, limit)	Iterate sorted key metadata by prefix.
scan_range(start, end, limit)	Iterate sorted key metadata by key range.
stats()	Inspect database statistics.
verify()	Verify integrity.
compact()	Rewrite live records.
repack()	Rewrite with current options.
flush()	Flush pending writes.
is_read_only()	Report whether the handle was opened without write access.

Open an existing database for inspection:

let mut db = EngineConfig::new("./app.taidb")
    .read_only()
    .open()?;

Low-level database

TaiDb exposes byte-oriented operations and is used by the CLI and engine facade.

Use it when you need lower-level access:

use taidb::{Options, TaiDb};

let mut db = TaiDb::open_with_options("./raw.taidb", Options::default())?;
db.put(b"key", b"value")?;

Use TaiDb::open_read_only or TaiDb::open_read_only_with_options when the caller must not create or modify database files.

Prefix and range scans

scan_prefix and scan_range return KeyCursor, an exact-size iterator over sorted KeyInfo metadata. A limit of 0 means no limit, matching list_keys.

use taidb::EngineConfig;

let mut db = EngineConfig::new("./index.taidb").open()?;
db.write_text_batch([
    ("doc:0001:title", "Rust storage"),
    ("doc:0002:title", "Vector cache"),
])?;

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

for info in db.scan_range(Some("doc:0002:"), Some("doc:0003:"), 10) {
    println!("{}", String::from_utf8_lossy(&info.key));
}

Range scans use an inclusive start and exclusive end. Use None for either side when the range should be open-ended.

Results and errors

Most operations return:

taidb::Result<T>

Keep errors typed until your application boundary so you can distinguish filesystem errors, invalid vectors, invalid values, corruption, and encryption failures.

Benchmark helpers

The taidb::bench module exposes reusable benchmark helpers for applications and CI:

• run_large_benchmark
• run_enterprise_benchmark
• run_compression_benchmark

Use run_compression_benchmark when you need to compare zstd speed and file size tradeoffs from Rust code without shelling out to the CLI.

Stability note

The public API is not yet frozen. The roadmap requires a SemVer review before 1.0.0, including:

• intended public exports
• error variants
• option builders
• migration notes for breaking changes