For AI agents: The documentation index is at https://docs.digitalocean.com/llms.txt. Markdown versions of pages use the same URL with index.html.md in place of the HTML page (for example, append index.html.md to the directory path instead of opening the HTML document).

Advanced PostgreSQL vector workloads often need more than a single pgvector index. As your corpus grows, you may need disk-resident vector search, smaller indexes, hybrid retrieval, retrieval-augmented generation, read scaling, or stricter capacity planning.

Use these guidelines to decide when to move beyond standard pgvector search patterns and how to structure larger PostgreSQL vector workloads.

For guidance on distance operators, HNSW, IVFFlat, query-time tuning, filters, partial indexes, and basic vector index maintenance, see Best Practices for PostgreSQL Vector Search.

Start with Standard pgvector

Start with standard pgvector search before adding advanced architecture.

For most workloads, use:

• Exact search for small tables, small filtered candidate sets, or validation tests.
• HNSW as the default approximate index for most small-to-medium production workloads.
• IVFFlat when faster builds or lower memory usage matter more than recall.

Move beyond standard pgvector only when you have measured a specific limit, such as:

• The HNSW index no longer fits comfortably in memory.
• Index builds take too long.
• Ingest volume makes index maintenance too expensive.
• Query latency increases because the workload has outgrown available RAM.
• You need to search a corpus that is too large for a memory-resident vector index.

For most workloads under a few million rows, start with pgvector HNSW, measure performance, and move to pgvectorscale only when memory, ingest rate, or index build time becomes a bottleneck.

Use pgvectorscale for Larger Corpora

pgvectorscale extends pgvector with indexes designed for larger vector workloads. It is a good fit when your corpus grows beyond what standard memory-resident HNSW can handle efficiently.

Use pgvectorscale when:

• You need to search tens of millions to hundreds of millions of vectors.
• Your vector index is too large to keep fully resident in memory.
• You need disk-resident vector search.
• You need to reduce memory pressure from large vector indexes.
• Index build time or ingest volume becomes a bottleneck.

pgvectorscale adds two important capabilities:

• StreamingDiskANN, a disk-resident vector index that keeps hot graph data in memory and streams the rest from disk.
• Statistical Binary Quantization, or SBQ, which compresses vectors in the index to reduce index size.

Do not start with pgvectorscale by default. Start with pgvector HNSW, measure recall, latency, memory usage, and index build time, then move to pgvectorscale when standard pgvector indexes no longer meet the workload’s requirements.

Use StreamingDiskANN for Disk-Resident Search

StreamingDiskANN is designed for vector workloads that exceed available RAM. Instead of requiring the full vector graph to stay in memory, it keeps frequently used graph data in memory and reads the rest from disk.

Use StreamingDiskANN when:

• Your vector corpus is too large for a memory-resident HNSW index.
• You need to reduce memory pressure.
• You want vector search to remain usable as your dataset grows.
• You can accept additional disk I/O compared to fully memory-resident search.

StreamingDiskANN isn’t always the right first choice. If HNSW fits in memory and meets your latency and recall goals, HNSW is usually simpler.

Use SBQ to Reduce Index Size

Statistical Binary Quantization compresses vectors in the index. This can reduce index size for large corpora.

Use SBQ when:

• Index size is a major concern.
• Memory pressure affects query latency.
• You need to store larger vector corpora more efficiently.
• You can accept an approximate compressed search stage before final reranking.

With memory_optimized storage, pgvectorscale searches the compressed graph first, then reranks candidates against the full-precision vectors.

This gives you a balance between smaller indexes and better final ranking quality.

Tune Recall and Latency Together

Approximate nearest-neighbor search trades recall for speed. For advanced workloads, tune query-time parameters with representative queries and known relevant results.

For StreamingDiskANN, increase diskann.query_rescore when you need higher recall and can accept higher query latency. Lower it when latency matters more and lower recall is acceptable.

Track at least three signals together:

• Recall: Whether the expected relevant results appear.
• Latency: How long queries take under realistic load.
• Resource usage: How much CPU, memory, and disk I/O the workload uses.

Avoid tuning only for latency. A query can become faster because it is returning worse results.

Use Hybrid Search for Better Relevance

Use hybrid search when vector search alone misses exact terms or full-text search alone misses semantic matches.

Vector search is strong at semantic similarity, paraphrases, and concept matching. PostgreSQL full-text search is strong at exact terms, rare tokens, product codes, commands, IDs, filenames, and error messages.

Hybrid search is useful when queries include:

• Natural-language descriptions.
• Exact product names or identifiers.
• Commands, filenames, or error messages.
• Domain-specific terms that embeddings may not rank highly enough.

A common pattern is to retrieve candidates from both vector search and full-text search, then combine their rankings with Reciprocal Rank Fusion.

For implementation guidance, see Query with Hybrid Search.

Use RAG for Grounded Generation

Retrieval-augmented generation, or RAG, combines PostgreSQL retrieval with a generative model. PostgreSQL retrieves the most relevant chunks, and the model generates an answer using those chunks as context.

Use RAG when you need generated answers grounded in your own documents, such as support articles, product docs, internal knowledge bases, or customer-specific content.

A minimal RAG workflow has three parts:

• A table of chunked documents with embeddings.
• An embedding model that turns the user’s question into a query vector.
• A chat or completion model that answers using retrieved chunks.

Keep the retriever simple at first. Start with top-k vector search, then add filters, hybrid search, reranking, or pgvectorscale only when you need them.

Design Filters for Access Control and Tenancy

Most production vector workloads need filters for access control, tenancy, recency, status, language, or document type.

Use ordinary PostgreSQL columns for metadata and combine them with vector queries. Add regular PostgreSQL indexes, such as B-tree, GIN, or partial indexes, for common filters.

For multi-tenant systems, make sure every query filters by tenant or access permissions before results reach the application.

Design access-control filters as part of the retrieval query, not only as an application-side post-processing step. Filtering after retrieval can leak metadata, return fewer useful results, or produce inconsistent ranking.

Plan for Read Scaling

Similarity search can be CPU- and memory-heavy. For production workloads, consider routing heavy search traffic to read-only nodes so search queries do not interfere with writes on the primary database.

Read scaling is useful when you have:

• High query volume.
• Expensive reranking.
• Large vector indexes.
• Many concurrent users.
• Mixed transactional and search workloads on the same cluster.

Keep write-heavy ingestion and read-heavy search traffic separated where possible. This helps reduce latency spikes and protects write performance on the primary database.

Monitor Capacity and Relevance

Monitor both infrastructure metrics and search quality.

For infrastructure, watch:

• RAM usage.
• Disk usage.
• CPU usage.
• Query latency.
• Index size.
• Disk I/O for disk-resident indexes.

For relevance, keep a small labeled test set of representative queries and expected results. Use it when you change embedding models, index types, query-time settings, filters, or ranking logic.

Resize or change architecture before the index or workload reaches capacity.

Rebuild or Re-embed When the Corpus Changes

Rebuild vector indexes when your data distribution changes enough to affect search quality.

Common reasons to rebuild include:

• Changing embedding models.
• Changing vector dimensions.
• Re-embedding a large portion of your corpus.
• Adding a large new content domain.
• Shifting from one content domain to another.
• Seeing recall degrade after major data changes.

Changing embedding models or vector dimensions usually requires re-embedding the source content and rebuilding affected indexes.

For large indexes, plan rebuilds carefully and make sure you have a recent backup or recovery point.