Building a Semantic Search API with Spring Boot and pgvector - Part 1: Architecture

The problem with Keyword Search Keyword search breaks more often than most engineers realize. A few months ago, I was building an internal document management tool. Users could upload policy documents, product guides, and support articles — and search through them. I implemented a simple keyword search, deployed it, and assumed I was done. Then the complaints started. One support engineer searched for "billing retries" and got zero results. The document absolutely existed. It was titled "Payment Failure Handling Policy" and covered exactly what they were looking for. The problem wasn’t the content. The problem was the search engine. It was doing exactly what keyword search is designed to do: scanning documents for the exact words “billing” and “retries.” Those words weren't in the document. So the system concluded there was no match. Query: "billing retries" Document: "Payment Failure Handling Policy" Keyword search: ❌ No match — strings don't overlap Semantic search: ✅ Strong match —