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.

Enums

EvictionPolicy

Which entry an eviction discards when the cache is full.

Constants

VERSION

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