Cloudflare Vectorize

Complete implementation guide for Cloudflare Vectorize - a globally distributed vector database for building semantic search, RAG (Retrieval Augmented Generation), and AI-powered applications with Cloudflare Workers.

Status: Production Ready ✅ Last Updated: 2026-01-21 Dependencies: cloudflare-worker-base (for Worker setup), cloudflare-workers-ai (for embeddings) Latest Versions: [email protected], @cloudflare/[email protected] Token Savings: ~70% Errors Prevented: 14 Dev Time Saved: ~4 hours

What This Skill Provides

Core Capabilities

• ✅ Index Management: Create, configure, and manage vector indexes
• ✅ Vector Operations: Insert, upsert, query, delete, and list vectors (list-vectors added August 2025)
• ✅ Metadata Filtering: Advanced filtering with 10 metadata indexes per index
• ✅ Semantic Search: Find similar vectors using cosine, euclidean, or dot-product metrics
• ✅ RAG Patterns: Complete retrieval-augmented generation workflows
• ✅ Workers AI Integration: Native embedding generation with @cf/baai/bge-base-en-v1.5
• ✅ OpenAI Integration: Support for text-embedding-3-small/large models
• ✅ Document Processing: Text chunking and batch ingestion pipelines
• ✅ Testing Setup: Vitest configuration with Vectorize bindings

Templates Included

1. basic-search.ts - Simple vector search with Workers AI
2. rag-chat.ts - Full RAG chatbot with context retrieval
3. document-ingestion.ts - Document chunking and embedding pipeline
4. metadata-filtering.ts - Advanced filtering patterns

---

⚠️ Vectorize V2 Breaking Changes (September 2024)

IMPORTANT: Vectorize V2 became GA in September 2024 with significant breaking changes.

What Changed in V2

Performance Improvements:

• Index capacity: 200,000 → 5 million vectors per index
• Query latency: 549ms → 31ms median (18× faster)
• TopK limit: 20 → 100 results per query
• Scale limits: 100 → 50,000 indexes per account
• Namespace limits: 100 → 50,000 namespaces per index

Breaking API Changes:

1. Async Mutations - All mutations now asynchronous:

   // V2: Returns mutationId
   const result = await env.VECTORIZE_INDEX.insert(vectors);
   console.log(result.mutationId); // "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
   
   // Vector inserts/deletes may take a few seconds to be reflected
   

2. returnMetadata Parameter - Boolean → String enum:

   // ❌ V1 (deprecated)
   { returnMetadata: true }
   
   // ✅ V2 (required)
   { returnMetadata: 'all' | 'indexed' | 'none' }
   

3. Metadata Indexes Required Before Insert:

   • V2 requires metadata indexes created BEFORE vectors inserted
   • Vectors added before metadata index won't be indexed
   • Must re-upsert vectors after creating metadata index

V1 Deprecation Timeline:

• December 2024: Can no longer create V1 indexes
• Existing V1 indexes: Continue to work (other operations unaffected)
• Migration: Use wrangler vectorize --deprecated-v1 flag for V1 operations

Wrangler Version Required:

• Minimum: [email protected] for V2 commands
• Recommended: [email protected]+ (latest)

Check Mutation Status

// Get index info to check last mutation processed
const info = await env.VECTORIZE_INDEX.describe();
console.log(info.mutationId); // Last mutation ID
console.log(info.processedUpToMutation); // Last processed timestamp

---

Critical Setup Rules

⚠️ MUST DO BEFORE INSERTING VECTORS

# 1. Create the index with FIXED dimensions and metric
npx wrangler vectorize create my-index \
  --dimensions=768 \
  --metric=cosine

# 2. Create metadata indexes IMMEDIATELY (before inserting vectors!)
npx wrangler vectorize create-metadata-index my-index \
  --property-name=category \
  --type=string

npx wrangler vectorize create-metadata-index my-index \
  --property-name=timestamp \
  --type=number

Why: Metadata indexes MUST exist before vectors are inserted. Vectors added before a metadata index was created won't be filterable on that property.

Index Configuration (Cannot Be Changed Later)

# Dimensions MUST match your embedding model output:
# - Workers AI @cf/baai/bge-base-en-v1.5: 768 dimensions
# - OpenAI text-embedding-3-small: 1536 dimensions
# - OpenAI text-embedding-3-large: 3072 dimensions

# Metrics determine similarity calculation:
# - cosine: Best for normalized embeddings (most common)
# - euclidean: Absolute distance between vectors
# - dot-product: For non-normalized vectors

Wrangler Configuration

wrangler.jsonc:

{
  "name": "my-vectorize-worker",
  "main": "src/index.ts",
  "compatibility_date": "2025-10-21",
  "vectorize": [
    {
      "binding": "VECTORIZE_INDEX",
      "index_name": "my-index"
    }
  ],
  "ai": {
    "binding": "AI"
  }
}

TypeScript Types

export interface Env {
  VECTORIZE_INDEX: VectorizeIndex;
  AI: Ai;
}

interface VectorizeVector {
  id: string;
  values: number[] | Float32Array | Float64Array;
  namespace?: string;
  metadata?: Record<string, string | number | boolean | string[]>;
}

interface VectorizeMatches {
  matches: Array<{
    id: string;
    score: number;
    values?: number[];
    metadata?: Record<string, any>;
    namespace?: string;
  }>;
  count: number;
}

Metadata Filter Operators (V2)

Vectorize V2 supports advanced metadata filtering with range queries:

// Equality (implicit $eq)
{ category: "docs" }

// Not equals
{ status: { $ne: "archived" } }

// In/Not in arrays
{ category: { $in: ["docs", "tutorials"] } }
{ category: { $nin: ["deprecated", "draft"] } }

// Range queries (numbers) - NEW in V2
{ timestamp: { $gte: 1704067200, $lt: 1735689600 } }

// Range queries (strings) - prefix searching
{ url: { $gte: "/docs/workers", $lt: "/docs/workersz" } }

// Nested metadata with dot notation
{ "author.id": "user123" }

// Multiple conditions (implicit AND)
{ category: "docs", language: "en", "metadata.published": true }

Metadata Best Practices

1. Cardinality Considerations

Low Cardinality (Good for $eq filters):

// Few unique values - efficient filtering
metadata: {
  category: "docs",        // ~10 categories
  language: "en",          // ~5 languages
  published: true          // 2 values (boolean)
}

High Cardinality (Avoid in range queries):

// Many unique values - avoid large range scans
metadata: {
  user_id: "uuid-v4...",         // Millions of unique values
  timestamp_ms: 1704067200123    // Use seconds instead
}

2. Metadata Limits

• Max 10 metadata indexes per Vectorize index
• Max 10 KiB metadata per vector
• String indexes: First 64 bytes (UTF-8)
• Number indexes: Float64 precision
• Filter size: Max 2048 bytes (compact JSON)

3. Vector Dimension Limit

Current Limit: 1536 dimensions per vector Source: GitHub Issue #8729

Supported Embedding Models:

• Workers AI @cf/baai/bge-base-en-v1.5: 768 dimensions ✅
• OpenAI text-embedding-3-small: 1536 dimensions ✅
• OpenAI text-embedding-3-large: 3072 dimensions ❌ (requires dimension reduction)

Unsupported Models (>1536 dimensions):

• nomic-embed-code: 3584 dimensions
• Qodo-Embed-1-7B: >1536 dimensions

Workaround: Use dimensionality reduction (e.g., PCA) to compress embeddings to 1536 or fewer dimensions, though this may reduce semantic quality.

Feature Request: Higher dimension support is under consideration. Use Limit Increase Request Form if this blocks your use case.

4. Key Restrictions

// ❌ INVALID metadata keys
metadata: {
  "": "value",              // Empty key