Module batch 

Batch insertion API. Batch insertion API for HNSW indexes.

This module provides the BatchInsertable trait for efficient insertion of multiple vectors in a single operation.

Performance

Batch insertion provides convenience features rather than raw throughput gains:

• Single API call instead of loop
• Built-in progress tracking at ~10% intervals
• Best-effort semantics (partial success on non-fatal errors)
• Progress callback overhead: <1%

Note: Throughput is equivalent to sequential insertion since both use the same underlying HNSW algorithm. See benches/batch_vs_sequential.rs.

Example

use edgevec::{HnswConfig, HnswIndex, VectorStorage, batch::BatchInsertable, error::BatchError};

fn main() -> Result<(), BatchError> {
    // Create an HNSW index
    let config = HnswConfig::new(128);
    let mut storage = VectorStorage::new(&config, None);
    let mut index = HnswIndex::new(config, &storage).unwrap();

    // Prepare vectors for batch insertion
    let vectors: Vec<(u64, Vec<f32>)> = vec![
        (1, vec![0.1; 128]),
        (2, vec![0.2; 128]),
    ];

    // Batch insert with progress tracking
    let ids = index.batch_insert(vectors, &mut storage, Some(|inserted, total| {
        println!("Progress: {}/{}", inserted, total);
    }))?;

    assert_eq!(ids.len(), 2);
    Ok(())
}

Error Handling

Batch insert uses best-effort semantics:

• Fatal errors (dimension mismatch on first vector, capacity exceeded) abort immediately
• Non-fatal errors (duplicates, invalid vectors mid-batch) are skipped
• Partial success is returned via Ok(Vec<u64>)

See BatchError for error types.

Re-exports

pub use crate::hnsw::graph::VectorId;

Traits

BatchInsertable

Trait for HNSW indexes supporting batch insertion.