dotfiles/.agents/skills/cloudflare-deploy/references/vectorize/patterns.md

Vectorize Patterns

Workers AI Integration

// Generate embedding + query
const result = await env.AI.run("@cf/baai/bge-base-en-v1.5", { text: [query] });
const matches = await env.VECTORIZE.query(result.data[0], { topK: 5 }); // Pass data[0]!

Model	Dimensions
@cf/baai/bge-small-en-v1.5	384
@cf/baai/bge-base-en-v1.5	768 (recommended)
@cf/baai/bge-large-en-v1.5	1024

OpenAI Integration

const response = await openai.embeddings.create({ model: "text-embedding-ada-002", input: query });
const matches = await env.VECTORIZE.query(response.data[0].embedding, { topK: 5 });

RAG Pattern

// 1. Embed query
const emb = await env.AI.run("@cf/baai/bge-base-en-v1.5", { text: [query] });

// 2. Search vectors
const matches = await env.VECTORIZE.query(emb.data[0], { topK: 5, returnMetadata: "indexed" });

// 3. Fetch full docs from R2/D1/KV
const docs = await Promise.all(matches.matches.map(m => env.R2.get(m.metadata.key).then(o => o?.text())));

// 4. Generate with context
const answer = await env.AI.run("@cf/meta/llama-3-8b-instruct", {
  prompt: `Context:\n${docs.filter(Boolean).join("\n\n")}\n\nQuestion: ${query}\n\nAnswer:`
});

Multi-Tenant

Namespaces (< 50K tenants, fastest)

await env.VECTORIZE.upsert([{ id: "1", values: emb, namespace: `tenant-${id}` }]);
await env.VECTORIZE.query(vec, { namespace: `tenant-${id}`, topK: 10 });

Metadata Filter (> 50K tenants)

wrangler vectorize create-metadata-index my-index --property-name=tenantId --type=string

await env.VECTORIZE.upsert([{ id: "1", values: emb, metadata: { tenantId: id } }]);
await env.VECTORIZE.query(vec, { filter: { tenantId: id }, topK: 10 });

Hybrid Search

const matches = await env.VECTORIZE.query(vec, {
  topK: 20,
  filter: {
    category: { $in: ["tech", "science"] },
    published: { $gte: lastMonthTimestamp }
  }
});

Batch Ingestion

const BATCH = 500;
for (let i = 0; i < vectors.length; i += BATCH) {
  await env.VECTORIZE.upsert(vectors.slice(i, i + BATCH));
}

Best Practices

1. Pass data[0] not data or full response
2. Batch 500 vectors per upsert
3. Create metadata indexes before inserting
4. Use namespaces for tenant isolation (faster than filters)
5. returnMetadata: "indexed" for best speed/data balance
6. Handle 5-10s mutation delay in async operations