11 — Vectorize: Vector Search at the Edge

"A vector database for Workers, I guess" was my Vectorize summary, and it buried the primitive underneath. The model that surfaced it: Vectorize is an index of high-dimensional vectors that answers "which stored vectors are nearest to this query vector?" — and that single question is the primitive that makes semantic search, recommendations, and retrieval-augmented generation work. [1] The vector database isn't the interesting part; the _embedding_ that produces the vectors is, and Vectorize is the layer that stores and searches them.

The framing that landed is the pipeline shape. Vectors don't appear from nowhere — they're the output of an embedding model, which turns text (or images, or audio) into a fixed-length array of floats where semantic similarity maps to geometric proximity [2]. Two pieces of text with similar meaning produce vectors that are close together in the embedding space. Vectorize's job is to store those vectors and, given a query vector, quickly return the stored vectors that are nearest to it. Workers AI does the embedding; Vectorize does the search.

Vector embeddings

The non-negotiable prerequisite is understanding what an embedding actually _is_ [2]. An embedding model maps a piece of content — a sentence, a paragraph, an image — to a fixed-length vector (often 768 or 1536 floats). The model is trained so that content with similar meaning lands at nearby points in that vector space. "How do I deploy?" and "What's the deployment process?" produce vectors that are nearly on top of each other; "How do I deploy?" and "Recipe for pancakes" produce vectors that are far apart.

The critical implication: the embedding model is a shared coordinate system. Every vector in my index has to come from the _same_ model, because proximity only means something within one model's space. Mixing embeddings from different models produces a broken index.

Similarity search

Vectorize answers the nearest-neighbor question: given a query vector, return the stored vectors closest to it, ranked by distance [3]. The distance metric (cosine similarity is the common default) measures how "similar" two vectors are. The result is a ranked list of stored items, each with a similarity score.

The mechanics that matter for me as a user:

• Indexing is offline-ish. I embed my corpus (documents, product descriptions, support articles) once and insert the vectors into the index, each with an identifier pointing back to the source content.
• Querying is two-step. At search time, I embed the query with the same model, then ask Vectorize for the nearest vectors. The identifiers come back, and I fetch the actual content from wherever it lives (D1, R2, KV).
• The index is approximate, not exact. Vectorize (like most vector databases at scale) uses approximate nearest neighbor (ANN) algorithms, which trade a tiny amount of recall for large speed gains. For most use cases the approximation is invisible; for exact-match requirements, it's a known trade.

AI-powered search

The full pipeline that makes Vectorize useful in practice — the reference calls it "AI-powered search" — has four steps [4]:

1. Embed the corpus. Run every piece of searchable content through a Workers AI embedding model, store the resulting vectors in Vectorize alongside an ID pointing back to the source.
2. Store the source content. Keep the actual documents in D1, R2, or KV, keyed by the same ID. Vectorize holds the vectors; something else holds the text.
3. Embed the query. When a user searches, run their query through the same embedding model.
4. Search and return. Ask Vectorize for the nearest vectors to the query, take the IDs, fetch the source content, return it as results.

The payoff is search that understands meaning, not just keywords. A query of "deployment problems" finds documents about "build failures during publish" because the embeddings capture the semantic relationship, even with zero shared words. This is the basis of semantic search and of retrieval-augmented generation (RAG) — where the retrieved chunks become context for an LLM's answer.

Where Vectorize fits

The decision rule:

• Use Vectorize for: semantic search over a corpus, "find similar items" recommendations, deduplication of near-identical content, RAG context retrieval.
• Don't use Vectorize for: exact-key lookup (that's KV), structured relational queries (that's D1), or anything that doesn't reduce to "find nearby vectors."

A common mistake is reaching for a vector database when a simpler tool would do. If the search is keyword-based and the corpus is small, full-text search in D1 (SQLite's FTS) may be enough. Vectorize earns its complexity when meaning-based retrieval is the actual requirement.

How I use this

The pattern I keep: pick one embedding model and stick with it for the life of the index, embed the corpus as a batch job (a scheduled Worker or a one-off script), store the source content in D1 keyed by the same IDs, and at query time embed the query with the same model and fetch the top-K matches' source from D1. The index is a routing layer that tells me _which_ records to read; it's never the source of truth for the content itself. When I'm tempted to treat Vectorize as a general database, that's the signal to step back — it's a search index, and it's at its best when its job is precisely that.

References

[1] Cloudflare, "Introduction to Vectorize — Cloudflare Docs," Cloudflare Docs, 2024. [Online]. Available: https://developers.cloudflare.com/vectorize/get-started/intro/

[2] Cloudflare, "Vector database — Cloudflare Docs," Cloudflare Docs, 2024. [Online]. Available: https://developers.cloudflare.com/vectorize/reference/what-is-a-vector-database/

[3] Cloudflare, "Cloudflare Vectorize," Cloudflare Docs, 2024. [Online]. Available: https://developers.cloudflare.com/vectorize/

[4] C. Tehio, "How to use Cloudflare Workers AI for building an AI-powered search," dev.to, 2024. [Online]. Available: https://dev.to/charlestehio/how-to-use-cloudflare-workers-ai-for-building-an-ai-powered-search-bar-51jn