vector-database

name	vector-database
description	Use when creating, updating, reviewing, or debugging vector databases, embeddings, semantic search, RAG (Retrieval-Augmented Generation), similarity search, semantic caching, LLM cost optimization, pgvector, Pinecone, Weaviate, Qdrant, Chroma, Milvus, or embedding models.

Vector Database & Semantic Caching

Use this skill for safe, accurate, and cost-efficient vector database and semantic caching implementations.

Rules

• Follow the project's existing vector database or embedding pattern.
• Do not add a new vector database provider or embedding model unless already used or explicitly requested.
• Always chunk documents before embedding; never embed raw, oversized inputs.
• Use deterministic, versioned cache keys that include the embedding model name.
• Prefer approximate nearest neighbor (ANN) for large datasets; exact kNN only for small or offline use cases.
• Never store raw secrets, PII, or full user content in vector databases without explicit consent and encryption.
• Semantic cache hit decisions must include a minimum similarity threshold — never return results below it.
• Semantic caching must scope results to the correct user, tenant, or session when results are private.
• Preserve existing logging, error, and test patterns.
• Avoid unrelated refactors.

Inspect First

Before adding or changing vector/embedding logic, check for:

• existing vector DB client or helper
• embedding model and version in use
• chunk size and overlap strategy
• similarity metric (cosine, dot product, Euclidean)
• similarity threshold for semantic cache hits
• namespace, collection, or index naming
• tenant/user scoping in vector namespace
• metadata stored alongside vectors
• cache TTL and invalidation strategy
• fallback behavior on DB unavailability
• logging and error patterns
• existing tests

Implementation Checklist

Embedding

• Chunk documents at semantically meaningful boundaries (paragraphs, sections).
• Apply consistent chunk size and overlap.
• Use the project's existing embedding model and version — avoid mixing models in the same index.
• Batch embedding requests to minimize API calls and costs.
• Handle token limit errors gracefully.

Indexing & Storage

• Name indexes/collections consistently: {project}_{scope}_{version} pattern.
• Include metadata: source ID, chunk index, created_at, content hash, and tenant/user scope.
• Use namespaces or separate collections to isolate tenants, users, or contexts.
• Select the correct similarity metric for the embedding model (cosine is default for most models).

Querying & RAG

• Embed the query using the same model and version as indexed content.
• Apply a minimum similarity threshold (e.g., score >= 0.75) — discard low-confidence results.
• Limit the number of retrieved chunks (top-k) to avoid context window overflow.
• Add metadata filters to narrow results before vector search when possible.
• Return empty results safely when nothing meets the threshold.

Semantic Cache

• Build deterministic cache keys: {model}:{hash(normalized_query)}:{scope}.
• Normalize queries before hashing: lowercase, trim, collapse whitespace.
• Apply a similarity threshold for cache hits — do not serve unrelated cached answers.
• Include tenant, user, or session ID in the cache key for private data.
• Set explicit TTL; avoid indefinite caching for LLM responses.
• Invalidate cache on source document updates or model version changes.
• Fail gracefully: cache miss or error should fall through to fresh retrieval, not crash.

Cost Optimization

• Cache embeddings of repeated content to avoid re-embedding.
• Deduplicate chunks before indexing.
• Use semantic cache to avoid redundant LLM calls for similar queries.
• Monitor embedding and query volume; add alerts for unexpected spikes.

Security Rules

• Never store raw passwords, API keys, payment data, or high-sensitivity PII in vector indexes.
• Scope all vector queries to the correct tenant, user, or session server-side.
• Do not trust client-provided namespace, collection, or scope parameters.
• Do not expose vectors or raw embeddings in API responses.
• Sanitize and length-limit all text before embedding to prevent prompt injection via retrieved chunks.
• Avoid logging raw query text if it may contain sensitive user data.
• Treat RAG-retrieved content as untrusted input — do not execute or blindly trust it.

Similarity Threshold Guidelines

Use Case	Recommended Minimum Score
Semantic cache hit (exact intent match)	≥ 0.92
FAQ / knowledge base retrieval	≥ 0.80
General RAG document retrieval	≥ 0.75
Exploratory / fuzzy search	≥ 0.60

Always tune thresholds against your specific model and dataset — these are starting points only.

Failure Handling

• Vector DB read failure: fall through to direct LLM call or return an explicit empty result.
• Vector DB write failure: log the error, do not block the main request.
• Embedding API failure: retry with exponential backoff; fail after max retries.
• Semantic cache miss: fall through to fresh retrieval and LLM call transparently.
• Model version mismatch: log a warning; do not serve results from mismatched index versions.

Provider Quick Reference

Provider	Best For	Notes
pgvector	Existing PostgreSQL projects	No new infra; limited ANN scale
Pinecone	Managed, large-scale production	Serverless and pod options
Qdrant	Self-hosted or cloud; rich filtering	Excellent metadata filter support
Weaviate	Multi-modal; built-in modules	GraphQL API; heavier setup
Chroma	Local dev and prototyping	Not for high-scale production
Milvus	High-scale self-hosted	Complex ops; best for very large corpora

Tests

Cover relevant paths:

• successful embedding and upsert
• successful similarity query above threshold
• query result correctly filtered below threshold (empty return)
• semantic cache hit returns correct cached result
• semantic cache miss falls through to retrieval
• cache write failure does not crash main flow
• tenant/user scoping: user A cannot retrieve user B's vectors
• chunk boundary correctness
• embedding model version mismatch detection
• vector DB unavailability fallback