Struct TieredIndex 

pub struct TieredIndex { /* private fields */ }

Tiered vector index with binary, int8, and optional fp32 representations

Implementations

impl TieredIndex

pub fn new(dim: usize) -> TieredIndex

Create a new tiered index (no memory limit)

pub fn with_fp32_storage(dim: usize) -> TieredIndex

Create with fp32 storage for maximum precision rescoring

pub fn with_capacity( dim: usize, capacity: usize, store_fp32: bool, ) -> TieredIndex

Create with pre-allocated capacity

pub fn memory_constrained(dim: usize, max_bytes: usize) -> TieredIndex

Create a memory-constrained index for resource-limited systems

Automatically calculates the maximum number of vectors that fit in the given memory budget.

Example

// For a system with 512 MB available for vectors
let index = TieredIndex::memory_constrained(1024, 512 * 1024 * 1024);

// For 1 GB budget
let index = TieredIndex::memory_constrained(768, 1024 * 1024 * 1024);

// Using helper constants
let index = TieredIndex::memory_constrained(1024, TieredIndex::MB(256));

pub fn memory_constrained_precise(dim: usize, max_bytes: usize) -> TieredIndex

Create memory-constrained index with fp32 storage

Note: fp32 storage uses 4x more memory per vector.

pub const fn MB(mb: usize) -> usize

Helper: convert MB to bytes

pub const fn GB(gb: usize) -> usize

Helper: convert GB to bytes

pub fn is_constrained(&self) -> bool

Check if the index has a memory constraint

pub fn memory_constraint(&self) -> Option<&MemoryConstraint>

Get the memory constraint configuration (if any)

pub fn can_add(&self) -> bool

Check if we can add more vectors

pub fn can_add_n(&self, n: usize) -> bool

Check if we can add N more vectors

pub fn remaining_capacity(&self) -> Option<usize>

Get remaining capacity (vectors)

pub fn remaining_bytes(&self) -> Option<usize>

Get remaining memory budget (bytes)

pub fn memory_utilization(&self) -> Option<f32>

Get memory utilization as percentage (0.0 - 1.0)

pub fn add(&mut self, vector: &[f32]) -> bool

Add a vector to the index

Automatically quantizes to binary and int8 representations. Returns false if memory limit reached (for constrained indexes).

pub fn add_unchecked(&mut self, vector: &[f32])

Add a vector, panicking if memory limit reached

Use this when you’re sure there’s capacity.

pub fn try_add(&mut self, vector: &[f32]) -> Result<(), MemoryLimitError>

Try to add a vector, returning error details if failed

pub fn add_batch(&mut self, vectors: &[Vec<f32>]) -> usize

Add multiple vectors in batch

Returns the number of vectors successfully added.

pub fn add_batch_partial(&mut self, vectors: &[Vec<f32>]) -> (usize, usize)

Add multiple vectors, stopping at memory limit

Returns (added_count, remaining_vectors)

pub fn len(&self) -> usize

Get number of vectors in the index

pub fn is_empty(&self) -> bool

Check if index is empty

pub fn dim(&self) -> usize

Get dimensionality

pub fn memory_stats(&self) -> TieredMemoryStats

Get memory usage statistics

pub fn search(&self, query: &[f32], k: usize) -> Vec<TieredSearchResult>

Search for k nearest neighbors using tiered retrieval

Uses default configuration (rescore_multiplier=4, no fp32 final).

pub fn search_with_config( &self, query: &[f32], k: usize, config: &TieredSearchConfig, ) -> Vec<TieredSearchResult>

Search with custom configuration

pub fn search_binary_only( &self, query: &[f32], k: usize, ) -> Vec<TieredSearchResult>

Search with only binary (fastest, least precise)

pub fn search_int8( &self, query: &[f32], k: usize, rescore_multiplier: usize, ) -> Vec<TieredSearchResult>

Search with binary + int8 (recommended balance)