Struct FlatIndex 

pub struct FlatIndex { /* private fields */ }

Brute-force exact nearest-neighbour index.

See the crate-level docs for the design notes and the iqdb_index::IndexCore / iqdb_index::Index contracts this type satisfies.

Examples

use std::sync::Arc;

use iqdb_flat::{FlatConfig, FlatIndex};
use iqdb_index::{Index, IndexCore};
use iqdb_types::{DistanceMetric, SearchParams, VectorId};

let mut idx = FlatIndex::new(2, DistanceMetric::Euclidean, FlatConfig)?;
idx.insert(VectorId::from(1u64), Arc::<[f32]>::from(&[0.0, 0.0][..]), None)?;
idx.insert(VectorId::from(2u64), Arc::<[f32]>::from(&[3.0, 4.0][..]), None)?;

let hits = idx.search(&[0.0, 0.0], &SearchParams::new(1, DistanceMetric::Euclidean))?;
assert_eq!(hits.len(), 1);
assert_eq!(hits[0].id, VectorId::U64(1));

Implementations

impl FlatIndex

pub fn new_unconfigured(dim: usize, metric: DistanceMetric) -> Result<Self>

Builds an empty index for dim-component vectors compared under metric.

Returns IqdbError::InvalidConfig when dim == 0. This is the same construction surface as Index::new; calling it directly is the convenient path when the concrete type is known and there is nothing to configure.

Examples

use iqdb_flat::FlatIndex;
use iqdb_types::DistanceMetric;

let idx = FlatIndex::new_unconfigured(3, DistanceMetric::Cosine)?;
assert_eq!(idx.dim(), 3);
assert!(idx.is_empty());

pub fn dim(&self) -> usize

The dimensionality the index was built for.

Examples

use iqdb_flat::{FlatConfig, FlatIndex};
use iqdb_index::Index;
use iqdb_types::DistanceMetric;

let idx = FlatIndex::new(8, DistanceMetric::Euclidean, FlatConfig)?;
assert_eq!(idx.dim(), 8);

pub fn metric(&self) -> DistanceMetric

The distance metric the index was built for.

Examples

use iqdb_flat::{FlatConfig, FlatIndex};
use iqdb_index::Index;
use iqdb_types::DistanceMetric;

let idx = FlatIndex::new(8, DistanceMetric::Cosine, FlatConfig)?;
assert_eq!(idx.metric(), DistanceMetric::Cosine);

pub fn len(&self) -> usize

The number of searchable vectors in the index.

Examples

use std::sync::Arc;

use iqdb_flat::{FlatConfig, FlatIndex};
use iqdb_index::{Index, IndexCore};
use iqdb_types::{DistanceMetric, VectorId};

let mut idx = FlatIndex::new(1, DistanceMetric::Euclidean, FlatConfig)?;
assert_eq!(idx.len(), 0);
idx.insert(VectorId::from(1u64), Arc::<[f32]>::from(&[0.0][..]), None)?;
assert_eq!(idx.len(), 1);

pub fn is_empty(&self) -> bool

Returns true when the index holds no vectors.

Examples

use iqdb_flat::{FlatConfig, FlatIndex};
use iqdb_index::Index;
use iqdb_types::DistanceMetric;

let idx = FlatIndex::new(1, DistanceMetric::Euclidean, FlatConfig)?;
assert!(idx.is_empty());

Trait Implementations

impl Debug for FlatIndex

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Index for FlatIndex

type Config = FlatConfig

Configuration consumed at construction time.

fn new( dim: usize, metric: DistanceMetric, _config: Self::Config, ) -> Result<Self>

Build a fresh index of dim vectors under metric with config.

impl IndexCore for FlatIndex

fn insert_batch( &mut self, items: Vec<(VectorId, Arc<[f32]>, Option<Metadata>)>, ) -> Result<()>

Reserves capacity for all backing stores up front, then inserts each item via insert.

This is the same fail-fast contract as the trait default (the first error returns immediately; inserts before it remain), but a single reserve(items.len()) on each of the four Vecs and the HashMap replaces the O(log n) incremental reallocations the default loop would trigger — a measurable win for bulk loads.

fn search(&self, query: &[f32], params: &SearchParams) -> Result<Vec<Hit>>

Searches for the top-k nearest neighbours under params.metric.

Returns IqdbError::DimensionMismatch if query.len() != self.dim, IqdbError::InvalidMetric if the params metric does not match the index’s, and IqdbError::InvalidFilter if params.filter is supplied and rejected by FilterEvaluator::new (depth or In cardinality past iqdb_filter’s MAX_FILTER_DEPTH / MAX_IN_VALUES). A pathological filter surfaces as a clean error rather than overflowing the search thread.

fn insert( &mut self, id: VectorId, vector: Arc<[f32]>, metadata: Option<Metadata>, ) -> Result<()>

Insert one vector into the index.

fn delete(&mut self, id: &VectorId) -> Result<()>

Remove the vector identified by id from the search space.

fn len(&self) -> usize

The number of vectors currently searchable in the index.

fn is_empty(&self) -> bool

Returns true when the index holds no searchable vectors.

fn dim(&self) -> usize

The dimensionality of vectors this index was configured for.

fn metric(&self) -> DistanceMetric

The distance metric this index was configured for.

fn flush(&mut self) -> Result<()>

Flush any pending state to durable storage.

fn stats(&self) -> IndexStats

A runtime snapshot of the index’s state.

fn search_batch( &self, queries: &[&[f32]], params: &SearchParams, ) -> Result<Vec<Vec<Hit>>, IqdbError>

Run a batch of top-k searches with shared params.