In Class 21 you learned to ask a database precise questions with SQL: filter by a known field, sort, count, and join related tables. That works beautifully when you know what you are looking for. This lesson asks the next question: what happens when the user does not know the exact words the document uses?

Keyword search is great — when the term is known

Ordinary search — SQL WHERE filters and full-text search — is excellent when the user knows the exact term, name, or filter value. A ticker symbol, a customer ID, a date range, the phrase "Form 10-K": type it exactly and the database finds it fast and deterministically.

That precision is also its limit. Keyword search matches characters, not intent. It finds what you typed, not what you meant.

Consider a team wiki. A new hire searches:

The document that actually answers her question is titled "project handoff notes" and talks about recording open questions, owners, and next steps after each sprint. Not one word overlaps with her query — yet it is exactly the page she needs. A keyword search returns nothing. A frustrated hire asks a colleague instead, and the wiki quietly rots.

This is the gap embeddings exist to close.

Semantic search: related meaning, different words

Semantic search means finding material whose meaning is related to the question, even when the wording differs. "Resetting a login," "cannot get into my account," "locked out," and "password not working" are different strings about the same problem. A semantic system recognizes the family resemblance.

How? With an embedding: a list of numbers, generated by an embedding model — a model whose job is converting text into those number lists so similar meanings land near one another in a mathematical space. Two passages about account access end up close together; a passage about quarterly revenue ends up far away — even if neither shares a single keyword with the query.

You do not need to visualize hundreds of dimensions to use this. The working mental model is simple: same neighborhood, related meaning. The embedding model does the placing; your product does the comparing. When a question arrives, you embed the question the same way, then ask: which stored passages sit nearest to it?

Think of it like a library where the librarian shelves books by topic rather than by title alphabet. You describe your problem in your own words, and she walks you to the right shelf — even though you never named a single book correctly.

What similarity is — and is not

This is the boundary to fix in your mind early, because it protects every later decision:

Embeddings identify similarity, not truth, intent, permission, or the final answer.

• A retrieved passage can be similar yet outdated, wrong for the user's account type, or superseded by a newer policy.
• Similarity says "this text is about the same thing." It does not say "this text is correct, current, allowed for this user, or sufficient to answer."
• The model still has to read the retrieved material, check it against the question, and answer honestly — which is Class 23's subject.

Treat a vector match as a candidate, not a verdict.

Three tools, often combined

Beginners hear "vector search" and assume it replaces everything. It does not. Real products use up to three retrieval tools side by side:

Many real products combine them: filter first by product, date, permissions, and language with SQL, then rank the survivors by meaning with vectors, then let full-text matching boost exact-term hits. Lesson 22.2 makes metadata filters first-class; Lesson 22.3 shows how all of this can live in one Postgres database.

The rule of thumb: use the cheapest tool that answers the question. If the user knows the exact term, keyword search wins. Reach for vectors when phrasing varies and meaning is what matters.

Decision drill: keyword vs. semantic vs. SQL filter

Read each question, pick the cheapest tool first, then check the answer. The point is deciding, not defining.

1. "Show Q3 2026 reports for Acme Corp updated after January, visible to me." 2. "Find the document containing the exact phrase 'handoff notes'." 3. "Software that helps my team remember decisions." 4. "I cannot get into my account — locked out since this morning." 5. "How did the company's margins change, for companies I am allowed to see?"

Answers, explained:

1. SQL filter. Company, date, and visibility are known fields. WHERE company_id = … AND updated_at >= … AND visibility = … answers it exactly — no meaning work needed. 2. Keyword / full-text search. The user supplied the exact phrase. A phrase index finds it fast and deterministically; vectors would only add fuzz. 3. Semantic (vector) search. No word overlaps with the target ("project handoff notes" about owners and next steps). Only meaning-level nearness bridges the gap. 4. Semantic (vector) search. "Cannot get in" and "locked out" share almost nothing with "Resetting your login," yet belong to the same problem family. Keyword catches one phrasing; vectors catch all five. 5. SQL filter first, then semantic. Filter by visibility and product_id / company scope before ranking — then rank survivors by meaning ("margins" vs. "profitability trends and cost structure"). Eligibility before nearness.

Notice question 5: real products combine tools. Filter first, rank second, boost exact hits third.

A support-center example, with a check attached

A support center stores an article titled "Resetting your login." Customers ask for it five different ways: "I cannot get into my account," "locked out since this morning," "password reset not working," "help me sign in," "my login keeps failing."

Keyword search catches one or two of these. Semantic search retrieves the same article for all five — because all five embeddings land in the same neighborhood.

But retrieval is only half the job. Before showing the article, the product must still check currency and applicability: is this the current reset procedure, and does it apply to this user's account type? A similar-but-stale article about last year's login flow is worse than no article. Similarity proposes; filters and freshness checks dispose.

Sonariq faces the same pattern. A reader asks "how did the company's margins change?" while the research section says "profitability trends and cost structure." Different words, same shelf. The retrieval must still confirm the filing period, the source URL, and which company the section belongs to — metadata work you will plan in the next lesson.

Practical exercise: five phrasings, two columns

1. Pick one question your product should answer — for example, "how do I reset my login?" or "what did the latest filing say about revenue?" 2. Write five ways a real customer might phrase it, using different words each time. Make at least two share almost no keywords with the original. 3. For each phrasing, note in two columns: which keywords match the source document, and which phrasings require meaning-level retrieval. 4. Mark the decision: could keyword search alone serve all five? If not, write one sentence saying why semantic retrieval is needed for this question.

Finish line: a short page with five phrasings, the keyword-match vs. meaning column for each, and your one-sentence retrieval decision.

Verify: cover the source title and ask a friend (or an AI) to match each phrasing to the right document using meaning alone. If a human cannot do it reliably, your test set is too ambiguous — rewrite it.

Common failure mode: writing five phrasings that all contain the same keyword ("reset," "reset," "reset") and concluding keyword search is enough. Force yourself to include the awkward, real-world phrasings — "cannot get in," "locked out" — where meaning has to do the work.

Check your understanding

1. When is keyword search the better choice, and when does it fail? 2. In one sentence, what is an embedding? 3. Why don't you need to visualize every dimension to use embeddings well? 4. What four things does similarity *not* guarantee? 5. Name the three retrieval tools and the question each answers best.