1# Cloudflare Vectorize
2 
3Globally distributed vector database for AI applications. Store and query vector embeddings for semantic search, recommendations, RAG, and classification.
4 
5**Status:** Generally Available (GA) | **Last Updated:** 2026-01-27
6 
7## Quick Start
8 
9```typescript
10// 1. Create index
11// npx wrangler vectorize create my-index --dimensions=768 --metric=cosine
12 
13// 2. Configure binding (wrangler.jsonc)
14// { "vectorize": [{ "binding": "VECTORIZE", "index_name": "my-index" }] }
15 
16// 3. Query vectors
17const matches = await env.VECTORIZE.query(queryVector, { topK: 5 });
18```
19 
20## Key Features
21 
22- **10M vectors per index** (V2)
23- Dimensions up to 1536 (32-bit float)
24- Three distance metrics: cosine, euclidean, dot-product
25- Metadata filtering (up to 10 indexes)
26- Namespace support (50K namespaces paid, 1K free)
27- Seamless Workers AI integration
28- Global distribution
29 
30## Reading Order
31 
32| Task | Files to Read |
33|------|---------------|
34| New to Vectorize | README only |
35| Implement feature | README + api + patterns |
36| Setup/configure | README + configuration |
37| Debug issues | gotchas |
38| Integrate with AI | README + patterns |
39| RAG implementation | README + patterns |
40 
41## File Guide
42 
43- **README.md** (this file): Overview, quick decisions
44- **api.md**: Runtime API, types, operations (query/insert/upsert)
45- **configuration.md**: Setup, CLI, metadata indexes
46- **patterns.md**: RAG, Workers AI, OpenAI, LangChain, multi-tenant
47- **gotchas.md**: Limits, pitfalls, troubleshooting
48 
49## Distance Metric Selection
50 
51Choose based on your use case:
52 
53```
54What are you building?
55├─ Text/semantic search → cosine (most common)
56├─ Image similarity → euclidean
57├─ Recommendation system → dot-product
58└─ Pre-normalized vectors → dot-product
59```
60 
61| Metric | Best For | Score Interpretation |
62|--------|----------|---------------------|
63| `cosine` | Text embeddings, semantic similarity | Higher = closer (1.0 = identical) |
64| `euclidean` | Absolute distance, spatial data | Lower = closer (0.0 = identical) |
65| `dot-product` | Recommendations, normalized vectors | Higher = closer |
66 
67**Note:** Index configuration is immutable. Cannot change dimensions or metric after creation.
68 
69## Multi-Tenancy Strategy
70 
71```
72How many tenants?
73├─ < 50K tenants → Use namespaces (recommended)
74│   ├─ Fastest (filter before vector search)
75│   └─ Strict isolation
76├─ > 50K tenants → Use metadata filtering
77│   ├─ Slower (post-filter after vector search)
78│   └─ Requires metadata index
79└─ Per-tenant indexes → Only if compliance mandated
80    └─ 50K index limit per account (paid plan)
81```
82 
83## Common Workflows
84 
85### Semantic Search
86 
87```typescript
88// 1. Generate embedding
89const result = await env.AI.run("@cf/baai/bge-base-en-v1.5", { text: [query] });
90 
91// 2. Query Vectorize
92const matches = await env.VECTORIZE.query(result.data[0], {
93  topK: 5,
94  returnMetadata: "indexed"
95});
96```
97 
98### RAG Pattern
99 
100```typescript
101// 1. Generate query embedding
102const embedding = await env.AI.run("@cf/baai/bge-base-en-v1.5", { text: [query] });
103 
104// 2. Search Vectorize
105const matches = await env.VECTORIZE.query(embedding.data[0], { topK: 5 });
106 
107// 3. Fetch full documents from R2/D1/KV
108const docs = await Promise.all(matches.matches.map(m => 
109  env.R2.get(m.metadata.key).then(obj => obj?.text())
110));
111 
112// 4. Generate LLM response with context
113const answer = await env.AI.run("@cf/meta/llama-3-8b-instruct", {
114  prompt: `Context: ${docs.join("\n\n")}\n\nQuestion: ${query}\n\nAnswer:`
115});
116```
117 
118## Critical Gotchas
119 
120See `gotchas.md` for details. Most important:
121 
1221. **Async mutations**: Inserts take 5-10s to be queryable
1232. **500 batch limit**: Workers API enforces 500 vectors per call (undocumented)
1243. **Metadata truncation**: `"indexed"` returns first 64 bytes only
1254. **topK with metadata**: Max 20 (not 100) when using returnValues or returnMetadata: "all"
1265. **Metadata indexes first**: Must create before inserting vectors
127 
128## Resources
129 
130- [Official Docs](https://developers.cloudflare.com/vectorize/)
131- [Client API Reference](https://developers.cloudflare.com/vectorize/reference/client-api/)
132- [Workers AI Models](https://developers.cloudflare.com/workers-ai/models/#text-embeddings)
133- [Discord: #vectorize](https://discord.cloudflare.com)
134