aarondb - v4.1.0

aarondb/vec_index

Types

HnswConfig

Construction and search limits for an HNSW index.

pub type HnswConfig {
  HnswConfig(
    max_neighbors: Int,
    search_budget: Int,
    level_source: LevelSource,
  )
}

Constructors 

  • HnswConfig(
  max_neighbors: Int,
  search_budget: Int,
  level_source: LevelSource,
)

Layer

A single layer in the Hierarchical Navigable Small-World (HNSW) graph.

pub type Layer {
  Layer(edges: dict.Dict(fact.EntityId, List(fact.EntityId)))
}

Constructors

LevelSource

The source used to choose HNSW insertion levels.

RandomLevels is the production default. DeterministicLevels is intended for repeatable tests and benchmarks; each accepted insert consumes one level, and an exhausted list uses level zero.

pub type LevelSource {
  RandomLevels
  DeterministicLevels(List(Int))
}

Constructors 

  • RandomLevels
  • DeterministicLevels(List(Int))

SearchResult

A search result: entity ID plus cosine-similarity score.

pub type SearchResult {
  SearchResult(entity: fact.EntityId, score: Float)
}

Constructors

VecIndex

A Hierarchical Navigable Small-World (HNSW) graph for approximate nearest-neighbor search.

The index is approximate. Use exact_search as a deterministic finite-corpus oracle for tests, benchmarks, and applications that require exhaustive results.

pub type VecIndex {
  VecIndex(
    nodes: dict.Dict(fact.EntityId, List(Float)),
    layers: dict.Dict(Int, Layer),
    dimensions: option.Option(Int),
    config: HnswConfig,
    entry_point: Result(fact.EntityId, Nil),
    max_level: Int,
  )
}

Constructors

Values

contains 

pub fn contains(idx: VecIndex, entity: fact.EntityId) -> Bool

Check if the index contains a given entity.

default_config 

pub fn default_config() -> HnswConfig

Production HNSW configuration. Its level source is intentionally random.

delete 

pub fn delete(idx: VecIndex, entity: fact.EntityId) -> VecIndex

Remove a node from the index across all layers and repair edges.

deterministic_config 

pub fn deterministic_config(levels: List(Int)) -> HnswConfig

A repeatable test/benchmark configuration. Each insert consumes one supplied non-negative level; after exhaustion, new nodes are placed on level zero.

pub fn exact_search(
  idx: VecIndex,
  query: List(Float),
  threshold: Float,
  k: Int,
) -> Result(List(SearchResult), Nil)

Exhaustively score every indexed vector with the same cosine, threshold, and validation rules as try_search.

This is the deterministic finite-corpus oracle for tests and benchmarks. Unlike HNSW, it is not approximate. Equal scores are ordered by ascending entity ID so callers can compare results mechanically.

insert 

pub fn insert(
  idx: VecIndex,
  entity: fact.EntityId,
  vec: List(Float),
) -> VecIndex

Insert a vector into the NSW graph.

A vector index has one fixed dimensionality, established by its first vector. A mismatched vector is rejected without changing the index.

new 

pub fn new() -> VecIndex

Create an empty vector index with production defaults.

new_with_config 

pub fn new_with_config(config: HnswConfig) -> VecIndex

Create an empty index with an explicit configuration.

DeterministicLevels provides reproducible topology for tests and benchmarks.

new_with_m 

pub fn new_with_m(m: Int) -> VecIndex

Create an empty vector index with custom max-neighbor degree.

pub fn search(
  idx: VecIndex,
  query: List(Float),
  threshold: Float,
  k: Int,
) -> List(SearchResult)

size 

pub fn size(idx: VecIndex) -> Int

Get the number of vectors in the index.

try_insert 

pub fn try_insert(
  idx: VecIndex,
  entity: fact.EntityId,
  vec: List(Float),
) -> Result(VecIndex, Nil)

Insert a vector, returning Error when it is empty, has zero magnitude, or its dimensionality differs from the index. Use this at validation boundaries when an invalid vector must be surfaced to the caller.

pub fn try_search(
  idx: VecIndex,
  query: List(Float),
  threshold: Float,
  k: Int,
) -> Result(List(SearchResult), Nil)

Search for vectors similar to query.

Returns Error when the query is empty, has zero magnitude, does not match the index dimensions, threshold is outside [-1.0, 1.0], or k is not positive. This prevents invalid inputs from receiving ambiguous scores.

✨ Search Document