fastapi-pgsearch-patterns

Combine FastAPI with pgvector and pg_search for hybrid lexical and vector retrieval.

Updated Apr 22, 2026
One-click install
npx skills add https://github.com/Mercurium-Analytics/pg-search-vector --skill fastapi-pgsearch-patterns
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: fastapi-pgsearch-patterns
Source: https://github.com/Mercurium-Analytics/pg-search-vector/tree/main/skills/fastapi-pgsearch-patterns
Command: npx skills add https://github.com/Mercurium-Analytics/pg-search-vector --skill fastapi-pgsearch-patterns

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This skill provides reusable patterns to assemble FastAPI with pg_search and pgvector to enable hybrid lexical + semantic retrieval in API endpoints, accelerating development of AI-powered search services.

Core Features & Use Cases

  • Async FastAPI integration with SQLAlchemy Async, pgvector, and pg_search to support high-throughput search workloads.
  • Patterns for lexical (bm25) and vector (embedding-based) retrieval, plus a simple hybrid ranking workflow for end-to-end APIs.
  • Use cases include building RAG APIs, semantic search endpoints, and streaming results from a retrieval-augmented generation pipeline.

Quick Start

Run a FastAPI app configured with pg_search and pgvector patterns to expose a hybrid retrieval endpoint.

Frequently Asked Questions about fastapi-pgsearch-patterns

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I build a FastAPI endpoint for hybrid lexical and vector retrieval?

Hybrid retrieval in FastAPI combines pg_search for lexical bm25 ranking and pgvector for semantic embedding similarity, merging both result sets in an async SQLAlchemy route. This pattern provides end-to-end integration for AI-powered search APIs.

What is the best way to combine pgvector and pg_search in an async SQLAlchemy application?

Combine pgvector and pg_search in async SQLAlchemy using pattern recipes that configure Vector(768) embeddings and execute safe lexical plus semantic queries. This approach supports high-throughput search workloads in FastAPI applications.

Does this hybrid retrieval pattern support async FastAPI applications with SQLAlchemy?

Yes, this hybrid retrieval pattern explicitly targets async FastAPI applications using SQLAlchemy Async. It provides production-like patterns for integrating pgvector and pg_search to support scalable, high-throughput API search workloads.

What vector dimensions are required for pgvector embeddings in this FastAPI pattern?

This FastAPI pattern enforces Vector(768) dimensions for pgvector embeddings. You must structure your vector embeddings to match this specific dimension to ensure safe and scalable end-to-end API integration.

Can I use these pgvector and pg_search patterns for building RAG APIs?

Yes, you can use these patterns for building RAG APIs, semantic search endpoints, and streaming results from retrieval-augmented generation pipelines. The patterns support end-to-end integration combining FastAPI with lexical and vector retrieval workflows.

When should I use a hybrid ranking workflow instead of standalone vector search in FastAPI?

Use a hybrid ranking workflow in FastAPI when you need to merge lexical bm25 results with semantic vector embeddings for more accurate document search. Standalone vector search lacks the keyword precision that pg_search provides in retrieval-augmented generation pipelines.