Postgres Hybrid Text Search

This combines PostgreSQL's BM25 keyword search with pgvector semantic search using Reciprocal Rank Fusion to merge results. You run two queries in parallel (one for exact term matching, one for meaning), then fuse them client-side in Python or TypeScript. It's the right move when your users mix specific terms like product codes with conceptual queries, though it adds complexity over single-method search. The guide uses pg_textsearch for true BM25 ranking, which is currently in prerelease. Includes weighting strategies if you want to favor one method over the other, plus optional ML reranking with cross-encoders for the final candidate set.

skills.sh installs: 391
GitHub stars: 1.9K
last updated: Aug 21, 2026

View on GitHub

Install

$ npx -y skills add timescale/pg-aiguide --skill postgres-hybrid-text-search --agent claude-code

Installs into .claude/skills of the current project.

Files

Hybrid Text Search

Hybrid search combines keyword search (BM25) with semantic search (vector embeddings) to get the best of both: exact keyword matching and meaning-based retrieval. Use Reciprocal Rank Fusion (RRF) to merge results from both methods into a single ranked list.

This guide covers combining pg_textsearch (BM25) with pgvector. Requires both extensions. For high-volume setups, filtering, or advanced pgvector tuning (binary quantization, HNSW parameters), see the pgvector-semantic-search skill.

pg_textsearch is a new BM25 text search extension for PostgreSQL, fully open-source and available hosted on Tiger Cloud as well as for self-managed deployments. It provides true BM25 ranking, which often improves relevance compared to PostgreSQL's built-in ts_rank and can offer better performance at scale. Note: pg_textsearch is currently in prerelease and not yet recommended for production use. pg_textsearch currently supports PostgreSQL 17 and 18.