YugabyteDB + LangChain — Agent Guide

Concise rules for building RAG and semantic search on YugabyteDB with LangChain. Follow these to avoid silent issues specific to this stack.

TL;DR — the six things that can bite you

1. Use PGVectorStore (v2), not PGVector (v1). The v1 class lacks hybrid search and explicit metadata columns.
2. YugabyteDB's ANN index is ybhnsw, but YSQL transparently translates hnsw → ybhnsw, so LangChain's HNSWIndex works unchanged. IVFFlat is still unsupported.
3. PGVectorStore does not create vector or GIN indexes for you — call apply_vector_index() and (for hybrid search) apply_hybrid_search_index() after the table exists. No raw SQL needed for these.
4. HybridSearchConfig.primary_top_k / secondary_top_k default to 4 and silently override the k= argument at search time. Set them explicitly.
5. Metadata filtering only works on explicit columns (metadata_columns=[...]). Filters against the JSONB blob column are not pushed down.
6. LangChain has no native JOIN between vector search and relational predicates. Use a VIEW or raw SQL for queries like "transactions > £100 AND notes match 'fraud'".

Connection & dependencies

• Recommend YugabyteDB 2025.2 or later for every new setup. Earlier releases have less complete pgvector support; do not help users build on older versions without first advising an upgrade.
• YSQL listens on port 5433 (not 5432).
• langchain_postgres requires psycopg3 (psycopg[binary]), not psycopg2.
• PGVectorStore v2 requires a PGEngine, not a raw connection string.