Semantic Search vs Keyword Search: What Changes With Embeddings

Imagine a knowledge base about mobile money in Kenya. A user searches: "send money from my phone."

Keyword search (Postgres full-text):

SELECT title, ts_rank(search_vector, query) AS rank
FROM articles,
  to_tsquery('english', 'send & money & phone') AS query
WHERE search_vector @@ query
ORDER BY rank DESC;

-- Results:
-- 1. "How to Send Money via M-Pesa" (contains "send", "money")
-- 2. "Phone Verification for Payments" (contains "phone")
-- (Misses: "Mobile Wallet Transfer Guide" because it
--  doesn't contain the word "send")

Semantic search (pgvector):

-- Embed the query: "send money from my phone" -> [0.12, -0.34, ...]

SELECT title, 1 - (embedding <=> query_embedding) AS similarity
FROM articles
ORDER BY embedding <=> query_embedding
LIMIT 5;

-- Results:
-- 1. "How to Send Money via M-Pesa" (0.91 similarity)
-- 2. "Mobile Wallet Transfer Guide" (0.87 similarity)
-- 3. "M-Pesa for Beginners" (0.83 similarity)
-- 4. "Airtel Money vs M-Pesa" (0.78 similarity)

The semantic search found "Mobile Wallet Transfer Guide" because it understood that "send money from my phone" and "mobile wallet transfer" mean the same thing. Keyword search missed it because the words do not match.

Keyword search uses an inverted index. Each word in your documents maps to a list of documents that contain it. When you search, the engine looks up each query word in the index and returns documents that match. Advanced keyword engines (Postgres full-text, Elasticsearch) support stemming ("running" matches "run"), stop word removal, and ranking by term frequency.

Semantic search uses embedding vectors. Each document is converted to a numerical vector that captures its meaning. The query is also converted to a vector. The search engine finds vectors closest to the query vector using distance metrics like cosine similarity. Two texts about the same topic produce similar vectors, regardless of the specific words used.

The fundamental difference: keyword search operates on tokens (exact word forms). Semantic search operates on meaning (the concept the words express).

Keyword search is not obsolete. It wins in specific scenarios:

• Exact term matching. Searching for error code "ERR_CONNECTION_REFUSED" or transaction ID "RCA3B7X1KD". Semantic search might return vaguely related errors instead of the exact one.
• Known vocabulary. When users know the exact terms (product names, technical jargon, legal clauses), keyword search is faster and more predictable.
• Filtering by specific fields. "Show me all documents from 2026 containing the word SACCO." This is a structured query, not a meaning question.
• Speed and cost. Keyword search requires no embedding model, no vector storage, no API calls. It runs on any database with a text index. Zero marginal cost per search.
• Transparency. You can explain why a keyword search returned a result ("this document contains the word X"). Semantic search results are harder to explain ("this vector was 0.87 similar to the query vector").

Semantic search shines when user language diverges from document language:

• Natural language queries. "How do I get my money back?" should find your refund policy, even if the document uses the word "reimbursement" instead of "money back."
• Multilingual matching. If your query is in English but some documents are in Swahili, semantic search (with a multilingual embedding model) can match across languages.
• Synonym handling. "cheap apartments" should match "affordable housing." Keyword search requires manual synonym dictionaries. Semantic search handles this automatically.
• Exploratory search. When users do not know the right terms to search for, semantic search helps them find relevant content by meaning rather than exact wording.

Many production systems combine both approaches. Run keyword search and semantic search in parallel, then merge the results.

async function hybridSearch(
  query: string,
  queryEmbedding: number[],
  topK: number = 5
): Promise<SearchResult[]> {
  // Run both searches in parallel
  const [keywordResults, semanticResults] = await Promise.all([
    // Postgres full-text search
    supabase
      .from('articles')
      .select('id, title, content')
      .textSearch('search_vector', query)
      .limit(topK),

    // pgvector semantic search
    supabase.rpc('match_articles', {
      query_embedding: queryEmbedding,
      match_count: topK,
    }),
  ]);

  // Merge and deduplicate by article ID
  const seen = new Set<string>();
  const merged: SearchResult[] = [];

  // Interleave: take top results from each
  const maxLen = Math.max(
    keywordResults.data?.length ?? 0,
    semanticResults.data?.length ?? 0
  );

  for (let i = 0; i < maxLen; i++) {
    const kw = keywordResults.data?.[i];
    const sem = semanticResults.data?.[i];

    if (kw && !seen.has(kw.id)) {
      seen.add(kw.id);
      merged.push(kw);
    }
    if (sem && !seen.has(sem.id)) {
      seen.add(sem.id);
      merged.push(sem);
    }
  }

  return merged.slice(0, topK);
}

This approach gives you the precision of keyword search (exact matches rank high) with the recall of semantic search (synonym and meaning matches are included). It is more complex to build and maintain, but it produces noticeably better results in practice.