Crate iqdb_cache 

iqdb-cache

An in-process caching layer for the HiveDB iqdb vector-database spine. For indexes that do not fit in RAM, a well-tuned cache turns repeated reads into memory reads. CachedIndex wraps any IndexCore and memoizes search results, while staying a drop-in IndexCore itself — so it slots in anywhere the wrapped index does, including behind Box<dyn IndexCore>.

Caching is an opt-in optimization: a database is correct with no cache at all (the default), and wrapping an index never changes the results a search returns — only how fast a repeated search returns them.

Tiers

• Tier 1 — the lazy path. CachedIndex::new wraps an index with a sensible default capacity. That is the whole common case.
• Tier 2 — the configured path. CachedIndex::with_capacity sizes the cache (or disables it with 0), and CachedIndex::with_config takes a CacheConfig to set capacity and an optional TTL together.
• Tier 3 — the trait seam. CachedIndex<I> implements IndexCore, so it composes with any index that does.

Correctness

The cache is invalidated on every mutation, so a search never observes a stale result. See CachedIndex for the exact contract.

Example

use iqdb_cache::CachedIndex;
use iqdb_index::IndexCore;
use iqdb_types::{DistanceMetric, SearchParams};

// `stub_index()` stands in for a real `iqdb-flat` / `iqdb-hnsw` index.
let mut cached = CachedIndex::new(iqdb_cache::doc_stub::stub_index());
let params = SearchParams::new(3, DistanceMetric::Cosine);

let a = cached.search(&[1.0, 0.0, 0.0], &params).unwrap();
let b = cached.search(&[1.0, 0.0, 0.0], &params).unwrap();  // served from cache
assert_eq!(a, b);
assert_eq!(cached.cache_stats().hits, 1);

Structs

CacheConfig

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

CacheStats

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

CachedIndex

A drop-in IndexCore wrapper that memoizes search results.

Constants

VERSION

The version of this crate, taken from Cargo.toml at compile time.