pg_bestmatch Documentation

Generate Okapi BM25 sparse vectors inside PostgreSQL and run lexical similarity search over pgvector (sparsevec) or pgvecto.rs (svector).

pg_bestmatch (pg_bestmatch.rs) is a PostgreSQL extension for servicing Okapi BM25 text queries inside PostgreSQL by converting documents and queries into BM25-weighted sparse vectors compatible with pgvector (sparsevec) and pgvecto.rs (svector).

Successor Recommendation: vchord_bm25 + pg_tokenizer

pg_bestmatch.rs was TensorChord’s first-generation BM25 extension built on sparse vector dot products. For new production deployments, we recommend vchord_bm25 paired with pg_tokenizer, which replaces HNSW sparse-vector approximation with a native Block-WeakAnd (WAND) inverted index for 100% exact Top-K BM25 scoring and up to 3x higher throughput.

Key Capabilities

In-Database BM25 Sparse Vector Generation: Maintains document frequency, term frequency, and document length statistics inside bm25_catalog and emits BM25-weighted sparse vectors for both documents and queries.
Native pgvector & pgvecto.rs Integration: Outputs standard sparsevec (pgvector 0.7.0+) or svector (pgvecto.rs) values so you can score documents with <#> (negative inner product) and accelerate search with HNSW indexes.
Built-in Tokenization: Ships with a built-in HuggingFace bert-base-uncased WordPiece vocabulary (30,522 dimensions) and a standalone tokenize(text) SQL function.

Documentation Sections

Getting Started

How pg_bestmatch converts BM25 scoring into sparse vector inner products, installation from packages or source, and quickstart setup.

Usage Guide

End-to-end BM25 retrieval workflow on the Stanford LoCo benchmark using pgvector sparsevec or pgvecto.rs svector.

SQL Reference & Comparison

Complete reference for bm25_create, bm25_refresh, bm25_drop, bm25_document_to_svector, bm25_query_to_svector, and tokenize.