Appendix A. Vector Search with Storage

This appendix explains how to add semantic search to the RSS reader built earlier by extending the existing storage layer rather than redesigning the application. It begins by contrasting keyword search with vector search, showing why exact word matching misses relevant content when users phrase questions differently or when related concepts are expressed with different terms. Semantic search addresses this by turning text into embeddings, numeric vectors that place related meanings close together in vector space.

The implementation uses Ollama to generate embeddings locally and Qdrant to store and search those vectors efficiently. The storage module is expanded with clean domain interfaces for embedding and search, and the design favors a decorator pattern: a searchable wrapper adds vector indexing and semantic lookup on top of any storage backend while leaving the underlying persistence code unchanged. Article data continues to live in bbolt, while Qdrant holds vector representations and metadata for similarity search, with context support added to allow cancellation and timeouts during embedding generation.

The final integration shows how the same wrapped storage instance can serve both traditional CRUD handlers and a new search handler through interface segregation. When articles are added, they are first persisted to bbolt and then embedded and stored in Qdrant, with failures in the search path logged but not allowed to break core storage. At query time, the search endpoint embeds the user’s query, finds the nearest vectors in Qdrant, and fetches the matching articles from bbolt, delivering results ranked by semantic similarity while preserving backward compatibility and graceful degradation if the vector services are unavailable.

• Vector search finds content by semantic meaning rather than exact keyword matches, using embedding models that convert text into high-dimensional numerical vectors representing meaning.
• The decorator pattern allows you to add search capabilities to any existing Storage implementation without modifying it. SearchStore wraps the base storage, delegating CRUD operations while adding embedding generation and search.
• Interface segregation keeps dependencies minimal—handlers depend only on Storage (for CRUD) or Searchable (for search), not both. The SearchableStorage interface combines them through composition when needed.
• The dual write pattern maintains consistency across storage systems: bbolt serves as the source of truth for article persistence, while Qdrant provides the search index. Secondary write failures don’t fail the operation, providing eventual consistency.
• Graceful degradation ensures system resilience—if vector search infrastructure (Qdrant or Ollama) fails, the system continues operating with traditional storage, logging warnings but maintaining core functionality.
• Qdrant (vector database) and Ollama (embedding service) enable local semantic search capabilities without cloud dependencies, using Docker Compose for straightforward local development and deployment.

FAQ