Module vector

Expand description

Exact vector storage and scoring. Persistent HNSW lives in vector_graph.

Storage layout ────────────── Meta table : meta::vector_indexes key : <collection>::<field> (UTF-8) value : postcard-serialised VectorDef

Vector table: vec::<collection>::<field> key : ULID bytes (16 B, big-endian) value : raw f32 LE bytes (dimensions × 4 B)

Structs§

CachedVectors: Decoded vectors for one collection::field, tagged with its vector revision.
HnswOptions: Configuration for an HNSW vector index.
VectorBlock: Contiguous decoded vectors; IDs and values avoid one allocation per vector.
VectorDef
VectorSearchResult: A single result returned by Collection::find_nearest.

DEFAULT_VECTOR_CACHE_BYTES: Maximum retained decoded vector bytes per database. Oversized indexes stream.
META_HNSW_TABLE: Stores HNSW options: key = "{collection}::{field}", value = postcard HnswOptions.
META_VECTOR_TABLE

compute_similarity
cosine_similarity
decode_f32_vec: Decode little-endian bytes back to Vec<f32>. Returns None if bytes.len() is not a multiple of 4.
dot_similarity
encode_f32_vec: Encode a &[f32] as little-endian bytes.
euclidean_similarity: Converts Euclidean distance to a similarity score in (0, 1]. Identical vectors → 1.0; the further apart, the closer to 0.
hnsw_table_name: HNSW graph blob table: hnsw::{collection}::{field}, single key = b"graph".
l2_norm: L2 (Euclidean) norm of a vector. Hoist this out of a scan loop for cosine — the query’s norm is constant across every candidate, so recomputing it per candidate (as cosine_similarity does) wastes one dot+sqrt per stored vector.
new_shared_vector_cache
norm_sq: The norm half of [dot_and_norm_sq], on its own.
score_with_norms: score_with_query_norm with the stored vector’s squared norm also known.
score_with_query_norm: compute_similarity with the query’s L2 norm supplied by the caller.
value_to_f32_vec: Extract a float vector from a document field value. Accepts Value::Array whose elements are all numeric (Float or Int). Returns None if the value is not a numeric array.
vec_meta_key
vec_table_name

SharedVectorCache: Shared across every Collection handle from the same Database, so a write through one handle invalidates reads through another.
VectorCacheMap