Crate iqdb 

iqdb — embedded vector database for Rust

iqdb is a single-process, in-application similarity-search engine for high-dimensional workloads. It targets the operational shape of sqlite or redb: no daemon, no network hop, no separate runtime. Open a handle, write vectors, query nearest neighbours — all from inside your binary.

The 0.5.0 release re-platforms iqdb onto the iqdb crate family: it is now the integration layer that composes the family’s shared vocabulary (iqdb_types), its index seam (iqdb_index), the exact and approximate index implementations (iqdb_flat, iqdb_hnsw, iqdb_ivf), durable storage (iqdb_persist), and an optional result cache (iqdb_cache). The public vocabulary — Vector, VectorId, Metadata, Value, Hit, Filter, DistanceMetric — is re-exported from the family so it agrees across every iqdb-* crate.

The handle

Iqdb is the one type most callers construct. A database fixes its dimensionality and DistanceMetric at open time, then exposes a small surface: upsert / get / delete for record management, search / search_with (plus batch variants) for top-k similarity search, and flush / optimize / close for maintenance.

Choosing an index

Tier 1 — Iqdb::open_in_memory and Iqdb::open default to the exact flat index. Tier 2 — pass an IqdbConfig to Iqdb::open_in_memory_with / Iqdb::open_with to select an approximate index (IndexKind::Hnsw / IndexKind::Ivf) and tune it, or to attach a CacheConfig. Flat is the recall ground truth that the approximate indices are measured against.

Async

Enable the async feature for AsyncIqdb, a Tokio adapter that mirrors the Iqdb surface and offloads each blocking call onto Tokio’s blocking pool via spawn_blocking. The synchronous API and the default build are unchanged; no Tokio is pulled unless async is enabled.

Examples

Open an in-memory database, upsert a record, look it up, and search:

use iqdb::{DistanceMetric, Iqdb, Result, Vector, VectorId};

fn run() -> Result<()> {
    let db = Iqdb::open_in_memory(3, DistanceMetric::Cosine)?;

    db.upsert(VectorId::from(1u64), Vector::new(vec![0.1, 0.2, 0.3])?, None)?;
    db.upsert(VectorId::from(2u64), Vector::new(vec![0.9, 0.1, 0.0])?, None)?;

    let hits = db.search(&Vector::new(vec![0.1, 0.2, 0.3])?, 1)?;
    assert_eq!(hits[0].id, VectorId::from(1u64));
    Ok(())
}

Select an HNSW index and a result cache through IqdbConfig:

use iqdb::{CacheConfig, DistanceMetric, HnswConfig, IndexKind, Iqdb, IqdbConfig};

let cfg = IqdbConfig::new(128, DistanceMetric::Cosine)
    .index(IndexKind::Hnsw(HnswConfig::default().with_ef_search(96)))
    .cache(CacheConfig::new().capacity(10_000));
let db = Iqdb::open_in_memory_with(cfg)?;
assert!(db.is_empty());

Structs

AsyncIqdbasync

An async handle over an Iqdb database.

CacheConfig

Tuning for a CachedIndex — the Tier-2 configured path.

CacheStats

A point-in-time snapshot of a CachedIndex’s cache.

Hit

One result of a similarity search: a matched record and its distance.

HnswConfig

Configuration for crate::HnswIndex construction (see iqdb_index::Index::new).

Iqdb

An open iqdb database.

IqdbConfig

Construction-time configuration for an Iqdb handle.

IvfConfig

Configuration for crate::IvfIndex construction (see iqdb_index::Index::new).

Metadata

An immutable, ordered map of metadata keys to Values.

SearchParams

The parameters of a nearest-neighbor search.

Vector

An owned dense vector of f32 components.

Enums

DistanceMetric

The metric used to measure distance (or similarity) between two vectors.

Error

An error from any iqdb operation.

EvictionPolicy

Which entry an eviction discards when the cache is full.

Filter

A boolean filter expression over record metadata.

IndexKind

Which index implementation backs an Iqdb handle.

Value

A scalar metadata value.

VectorId

A stable identifier for a stored vector.

Type Aliases

Result

A specialized Result whose error is Error.