Vectorize

Learning Focus

By the end of this lesson you will understand what a vector database is, how Vectorize stores embeddings, and how to use it for semantic search.

What Is Vectorize?

Vectorize is Cloudflare's managed vector database. It's designed to store and query "embeddings" (mathematical representations of data like text, images, or audio) so you can perform semantic search or find "similar" items.

flowchart TD
    TEXT["Input Text"] --> AI["Workers AI\n(Embeddings Model)"]
    AI -->|"Vector [0.1, -0.4, ...]"| VEC["Vectorize DB\n(Storage)"]
    QUERY["Search Query"] --> AI2["Workers AI\n(Embeddings Model)"]
    AI2 -->|"Search Vector"| VEC
    VEC -->|"Nearest Neighbors"| RESULTS["Top Matches"]

    style VEC fill:#7c3aed,color:#fff,stroke:#6d28d9
    style AI fill:#f6821f,color:#fff,stroke:#e5711e

Free Tier

Resource	Free Plan
Total Vectors	50,000
Dimensions	5 million (cumulative across all vectors)
Indexes	100

Setting Up Vectorize

1. Create an Index

You must define the dimensions of your index (the number of numbers in each vector). This must match the output of the embedding model you use (e.g., bge-small uses 384 dimensions).

Create index

wrangler vectorize create my-index --dimensions=384 --metric=cosine

2. Configure the Binding

wrangler.toml

[[vectorize]]
binding = "VECTOR_INDEX"
index_name = "my-index"

Using Vectorize in a Worker

Inserting Vectors

src/index.ts

export interface Env {
  VECTOR_INDEX: VectorizeIndex;
  AI: any;
}

// ... inside Worker fetch handler
const text = "Cloudflare Vectorize is a powerful vector database.";

// 1. Generate embedding using Workers AI
const embeddingResponse = await env.AI.run("@cf/baai/bge-small-en-v1.5", {
  text: [text],
});
const values = embeddingResponse.data[0];

// 2. Upsert into Vectorize
await env.VECTOR_INDEX.upsert([
  {
    id: "doc-1",
    values: values,
    metadata: { text: text },
  },
]);

Querying (Search)

const query = "How do I store AI data?";

// 1. Generate query embedding
const queryResponse = await env.AI.run("@cf/baai/bge-small-en-v1.5", {
  text: [query],
});
const queryVector = queryResponse.data[0];

// 2. Query Vectorize for top 3 matches
const matches = await env.VECTOR_INDEX.query(queryVector, {
  topK: 3,
  returnValues: true,
  returnMetadata: "all",
});

return Response.json(matches);

Key Takeaways

• Vectorize stores mathematical embeddings for semantic search.
• It is the core storage layer for RAG (Retrieval Augmented Generation) applications.
• Free tier: 50k vectors (up to 5M total dimensions).
• Must match the dimensions of your embedding model (e.g., 384 for bge-small).
• Use Metadata to store the original text or identifiers for quick retrieval.

What's Next

• Continue to Analytics and Observability to learn about monitoring your Cloudflare traffic.