Struct PgSparseVectorIndex 

pub struct PgSparseVectorIndex { /* private fields */ }

PostgreSQL sparse vector index — the lexical half of hybrid retrieval.

Stores sparsevec(N) rows (N = vocabulary size, e.g. 250 002 for BGE-M3’s XLM-R vocabulary) and ranks by inner product, which is how learned-lexical weights (BGE-M3 sparse, SPLADE) are scored. Deliberately not an AsyncVectorIndex — that trait speaks dense Vec<f32>. Pair it with a PgVectorIndex and combine the two result lists with Fusion.

Requires the pgvector extension ≥ 0.7 (sparsevec + sparsevec_ip_ops). pgvector caps the number of non-zero elements it will index, so prune long lexical vectors with SparseVector::prune_top_k before inserting.

Implementations

impl PgSparseVectorIndex

pub async fn new(url: &str, table: &str, dim: usize) -> Result<Self>

Connect and create the sparsevec table + HNSW inner-product index.

dim is the vocabulary size and is enforced by the sparsevec(dim) column; vectors carrying an index ≥ dim are rejected on insert.

pub fn dim(&self) -> usize

Vocabulary size of the indexed vectors.

pub fn pool(&self) -> &PgPool

Underlying connection pool — see PgVectorIndex::pool.

pub async fn add(&self, vectors: &[SparseVector], ids: &[u64]) -> Result<()>

Upsert sparse vectors by external ID.

pub async fn search( &self, query: &SparseVector, k: usize, ) -> Result<Vec<SearchHit>>

Top-k by inner product. An empty query matches nothing by definition (its inner product with every row is zero), so it short-circuits.

pub async fn search_filtered( &self, query: &SparseVector, k: usize, allowlist: &[u64], ) -> Result<Vec<SearchHit>>

Top-k by inner product, restricted to allowlist.

pub async fn remove(&self, ids: &[u64]) -> Result<()>

Remove vectors by external ID.

pub async fn remove_in_tx( &self, tx: &mut PgConnection, ids: &[u64], ) -> Result<()>

Remove within a caller-provided transaction — see PgVectorIndex::remove_in_tx. Lets a dense index, a sparse index and the caller’s own tables be pruned atomically together.

pub async fn len(&self) -> Result<usize>

Number of stored vectors.

pub async fn is_empty(&self) -> Result<bool>

Whether the index holds no vectors.