Struct SparseVector 

pub struct SparseVector { /* private fields */ }

A sparse vector — indices[i] carries weight values[i].

Indices are 0-based vocabulary positions, as emitted by the model. Backends convert to their own convention on write (pgvector’s text form is 1-based). Elements are kept sorted by index with zero weights removed, which is what sparsevec expects and what makes intersection cheap.

Implementations

impl SparseVector

pub fn new(indices: Vec<u32>, values: Vec<f32>) -> Option<Self>

Build from parallel indices / values.

Zero weights are dropped and the remaining elements are sorted by index. Returns None when the two slices disagree in length — a mismatch means the caller lost the pairing and silently truncating would corrupt scores.

Both +0.0 and -0.0 are dropped: v != 0.0 is false for both (-0.0 == 0.0 per IEEE-754), so a signed zero cannot sneak through and later tie-break against a genuinely nonzero weight in prune_top_k.

pub fn indices(&self) -> &[u32]

Vocabulary indices, ascending.

pub fn values(&self) -> &[f32]

Weights, aligned with indices.

pub fn nnz(&self) -> usize

Number of non-zero elements.

pub fn is_empty(&self) -> bool

Whether the vector carries no weight at all.

pub fn prune_top_k(&self, k: usize) -> SparseVector

Keep only the k highest-magnitude weights, still sorted by index.

Lexical vectors from models like BGE-M3 carry a long tail of near-zero weights that costs storage and search time while contributing almost nothing to the score. pgvector also refuses to build an HNSW index over a sparsevec beyond a bounded number of non-zero elements (1,000 as of pgvector 0.8), so long vectors must be pruned before indexing.

Trait Implementations

impl Clone for SparseVector

fn clone(&self) -> SparseVector

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for SparseVector

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for SparseVector

fn default() -> SparseVector

Returns the “default value” for a type.

impl PartialEq for SparseVector

fn eq(&self, other: &SparseVector) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for SparseVector