Crate annex 

ANNex

In-memory ANN (HNSW) vector search engine with payload filtering, snapshot persistence, and WAL replay.

Overview

Segment is the main entry point. It wraps an HNSW index, per-point payloads, an inverted index for filter acceleration, and an optional write-ahead log. A single Segment is not internally synchronised for writes — callers running multi-threaded workloads should wrap it in an std::sync::Arc<std::sync::RwLock<Segment>> (a SharedSegment) and coordinate through the lock.

Quickstart

use std::collections::HashMap;
use annex::{DistanceMetric, Filter, Payload, PayloadValue, Segment};

// 128-dim cosine index, m=16, ef=64, max level cap 16.
let mut seg = Segment::with_config(DistanceMetric::Cosine, 16, 64, 16, 128);

for id in 0..4u64 {
    let vector = vec![id as f32; 128];
    let mut payload = Payload(HashMap::new());
    payload.set(
        "category",
        PayloadValue::Str(if id % 2 == 0 { "even".into() } else { "odd".into() }),
    );
    seg.insert_with_id(id, vector, Some(payload)).unwrap();
}

let query = vec![0.1_f32; 128];
let filter = Filter::Match {
    key: "category".into(),
    value: PayloadValue::Str("even".into()),
};
let hits = seg.search_with_filter(&query, 2, Some(&filter)).unwrap();
for hit in hits {
    println!("id={} score={}", hit.id, hit.raw_score);
}

Configuration

Runtime tuning (search budgets, purge thresholds, telemetry paths, and so on) is driven by VECTORDB_* environment variables, often cached on first use (the prefix predates the ANNex rename and is retained for compatibility). See .env.example in the repository for the full list.

Everything below the Segment layer (the vector, payload_storage, and analysis modules) is exposed but considered an implementation detail and may change between minor versions.

Re-exports

pub use crate::rerank::group_by_top_n;

pub use crate::rerank::mmr_select;

pub use crate::rerank::reciprocal_rank_fusion;

pub use crate::rerank::weighted_fusion;

pub use crate::segment::segment::Segment;

pub use crate::segment::segment::SnapshotMetadata;

pub use crate::segment::SharedSegment;

pub use crate::segment::SnapshotConfig;

pub use crate::segment::SnapshotterHandle;

pub use crate::segment::WalConfig;

pub use crate::segment::start_background_snapshots;

pub use crate::utils::errors::DBError;

pub use crate::utils::payload::Payload;

pub use crate::utils::payload::PayloadValue;

pub use crate::utils::payload::ScalarComparisonOp;

pub use crate::utils::types::DistanceMetric;

pub use crate::utils::types::PointId;

pub use crate::utils::types::Score;

pub use crate::utils::types::Vector;

Modules

rerank

Post-retrieval helpers: hybrid fusion, MMR result diversity, group-by.

segment

utils

Structs

ChunkedArray

Stable-slot append-only array of T.

ChunkedArrayView

Snapshot of a ChunkedArray’s chunk list.

ScoredPoint

SearchRuntimeOptions

SparseIndex

Memory grows with live documents and nonzero features, never feature IDs.

SparseVector

Parallel feature/weight arrays. Index operations validate and canonicalize these arrays: sort features, sum duplicates, and omit zero weights.

VectorArena

Stable-address chunk store for f32 vectors.

VectorArenaView

Snapshot of VectorArena’s chunk list at a point in time.

Enums

Filter