Crate iqdb_build 

iqdb-build

Bulk index construction for the iqdb embedded vector-database spine. Loading a million vectors into an index one insert at a time is slow; iqdb-build is the fast path. It is generic over the iqdb_index::Index trait, so the same builder constructs flat, HNSW, and IVF indexes without naming a concrete type.

The crate exposes the three iQDB API tiers:

• Tier 1 — the lazy path. The free functions build (construct a fresh index from a stream of vectors, with default configuration) and build_into (bulk-insert into an index you already hold, including a &mut dyn IndexCore trait object). One call each.
• Tier 2 — the configured path. IndexBuilder, which carries the dim, metric, and the backend’s own Config so you can tune the index it constructs. build_parallel splits the input into shards and constructs them concurrently on rayon’s pool; build_merged folds those shards back into a single index — the full split → build → merge pipeline in one call. An optional on_progress callback reports shard completion.
• Tier 3 — the trait seam. The iqdb_index::Index and iqdb_index::IndexCore traits, plus this crate’s Mergeable (how a backend absorbs another instance of itself): implement them and the same builder constructs and merges your backend.

Every fallible call returns iqdb_types::Result; errors raised by the backend (Index::new and insert_batch) are propagated unchanged. The crate adds no error type of its own and never panics on bad input.

Example

use std::sync::Arc;
use iqdb_build::IndexBuilder;
use iqdb_types::{DistanceMetric, VectorId};
// Build a 3-dimensional index from three vectors in one call.
let items = vec![
    (VectorId::from(1u64), Arc::from([0.0_f32, 0.0, 0.0].as_slice()), None),
    (VectorId::from(2u64), Arc::from([1.0_f32, 0.0, 0.0].as_slice()), None),
    (VectorId::from(3u64), Arc::from([0.0_f32, 1.0, 0.0].as_slice()), None),
];
let index: Flat = IndexBuilder::new(3, DistanceMetric::Euclidean).build(items)?;
assert_eq!(index.len(), 3);

Structs

BuildProgress

A progress snapshot delivered to the callback registered with IndexBuilder::on_progress as parallel construction proceeds.

IndexBuilder

A configured, reusable plan for constructing an Index.

Constants

VERSION

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

Traits

Mergeable

A backend that can absorb another instance of itself.

Functions

build

Construct a fresh index from a stream of vectors, using the backend’s default Config.

build_into

Bulk-insert a stream of vectors into an index you already hold, returning the number inserted.

merge

Fold a collection of sub-indexes into one by merging them in order.

Type Aliases

BuildItem

One vector to feed into a build: its VectorId, its components owned as an Arc<[f32]>, and its optional Metadata.