Vector Embeddings, explained properly

Who this is for

You’ve heard “vector embeddings” in a meeting. Maybe you’ve been handed a ticket mentioning semantic search, or RAG, or “we should use a vector database.” You can code perfectly well. Nobody has just sat down and explained this particular thing without either dumbing it down or burying you in linear algebra.

That’s what this is. No machine learning background needed. If you can write a for-loop, you’re qualified.

You can start without an API key

The C# and Java guides both open with a version that runs immediately — no account, no card, no cost — using numbers we write by hand so the machinery is visible. Real models come second, and only one function changes.

The 30-second version

An embedding is a list of numbers that stands in for a piece of text. Similar meanings get similar numbers. That’s the whole trick.

Once meaning is numbers, “find me something like this” becomes arithmetic, and computers are extremely good at arithmetic.

"the spare set for the front door is in the kitchen drawer"
                        ↓
        [0.021, -0.145, 0.083, ... 1533 more numbers]

Ask “where did I put my keys?”, turn that into numbers too, and look for the closest match. The note comes back, despite never containing the word “keys”.

And the note that does contain the word “key” — “the standing desk needs a 4mm hex key” — correctly loses. A keyword search would have ranked those two in exactly the opposite order.

What makes this guide different

One example, all the way through

Every guide builds the same tiny app: eight handwritten notes, and a search that finds the right one even when you can’t remember the words you used.

Six ways to build it

Python, C#, Java, TypeScript, Go — and pure SQL, with no application code at all. The syntax differs; what the code does is identical.

Every sample actually runs

Every sample is compiled, and the no-API-key ones are run, before publishing — their output is real terminal output. Where a sample needs a paid API, the code is compiled but the scores shown are illustrative, and the page says so.

Honest about the rough edges

Where this technology is weak, we say so plainly rather than selling it. There is a whole page on when to use something else instead.

What’s here

Twenty pages, in five parts. Start anywhere.

Start HereWhat a vector embedding is, and getting real numbers on your screen in five minutes.

ConceptsHow text becomes numbers, cosine similarity, chunking, RAG, and when to use something else entirely.

Using EmbeddingsWorking code in Python, C#, Java, TypeScript, Go and pure SQL. Several run with no API key at all.

In ProductionMeasuring whether your search is any good, what it costs at scale, and the security questions you'll be asked.

ReferenceChoosing a model, 69 databases that store vectors, and a glossary for every term on the site.

Three questions people arrive with

“What even is this?” → What is a vector embedding? — the idea, with pictures and no maths.

“I’ve been asked to build RAG.” → RAG, without the mystique — it’s search plus a prompt, and the search is the hard part.

“Is this the right tool at all?” → Alternatives to vector embeddings — often it isn’t, and that page says so.

References

If you’d rather go straight to primary sources:

• OpenAI — Embeddings guide — the official explanation, model list and token limits
• Attention Is All You Need — Vaswani et al., 2017, the architecture behind modern embeddings
• Efficient Estimation of Word Representations in Vector Space — Mikolov et al., 2013, where this idea became practical
• MTEB leaderboard — how embedding models currently compare
• SBERT — Sentence Transformers — running embedding models on your own machine
• pgvector — storing vectors in Postgres, the usual production answer