aarondb - v4.0.0

aarondb/vec_index

Types

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

SearchResult

A search result: entity ID + 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. Scales logarithmically even for million-scale datasets by using hierarchical layers.

pub type VecIndex {
  VecIndex(
    nodes: dict.Dict(fact.EntityId, List(Float)),
    layers: dict.Dict(Int, Layer),
    dimensions: option.Option(Int),
    max_neighbors: Int,
    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.

delete 

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

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

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 default max_neighbors of 16.

new_with_m 

pub fn new_with_m(m: Int) -> VecIndex

Create an empty vector index with custom max_neighbors.

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 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 dimensions do not match the index. This prevents mismatched vectors from receiving a truncated similarity score.

✨ Search Document