cloudflare-vectorize

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: 2025-10-21 Dependencies: cloudflare-worker-base (for Worker setup), cloudflare-workers-ai (for embeddings) Latest Versions: wrangler@4.43.0, @cloudflare/workers-types@4.20251014.0 Token Savings: ~65% Errors Prevented: 8 Dev Time Saved: ~3 hours

What This Skill Provides

Core Capabilities

• ✅ Index Management: Create, configure, and manage vector indexes
• ✅ Vector Operations: Insert, upsert, query, delete, and list vectors
• ✅ 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

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 examples

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;
}

Common Operations

1. Insert vs Upsert

// INSERT: Keeps first insertion if ID exists
await env.VECTORIZE_INDEX.insert([
  {
    id: "doc-1",
    values: [0.1, 0.2, 0.3, ...],
    metadata: { title: "First version" }
  }
]);

// UPSERT: Overwrites with latest if ID exists (use this for updates)
await env.VECTORIZE_INDEX.upsert([
  {
    id: "doc-1",
    values: [0.1, 0.2, 0.3, ...],
    metadata: { title: "Updated version" }
  }
]);

2. Query with Filters

// Generate embedding for query
const queryEmbedding = await env.AI.run('@cf/baai/bge-base-en-v1.5', {
  text: "What is Cloudflare Workers?"
});

// Search with metadata filtering
const results = await env.VECTORIZE_INDEX.query(
  queryEmbedding.data[0],
  {
    topK: 5,
    filter: {
      category: "documentation",
      timestamp: { $gte: 1704067200 }  // After Jan 1, 2024
    },
    returnMetadata: 'all',
    returnValues: false,
    namespace: 'prod'
  }
);

3. Metadata Filter Operators

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

// Explicit operators
{ status: { $ne: "archived" } }

// In array
{ category: { $in: ["docs", "tutorials", "guides"] } }

// Not in array
{ category: { $nin: ["deprecated", "draft"] } }

// Range queries (numbers)
{
  timestamp: {
    $gte: 1704067200,  // >= Jan 1, 2024
    $lt: 1735689600    // < Jan 1, 2025
  }
}

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

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

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

4. Namespace Filtering

// Insert with namespace (partition key)
await env.VECTORIZE_INDEX.upsert([
  {
    id: "1",
    values: embedding,
    namespace: "customer-123",
    metadata: { type: "support_ticket" }
  }
]);

// Query only within namespace
const results = await env.VECTORIZE_INDEX.query(queryVector, {
  topK: 5,
  namespace: "customer-123"  // Only search this customer's data
});

5. List and Delete Vectors

// List vector IDs (paginated)
const vectors = await env.VECTORIZE_INDEX.listVectors({
  cursor: null,
  limit: 100
});

// Get specific vectors by ID
const retrieved = await env.VECTORIZE_INDEX.getByIds([
  "doc-1", "doc-2", "doc-3"
]);

// Delete vectors
await env.VECTORIZE_INDEX.deleteByIds([
  "doc-1", "doc-2"
]);

Embedding Generation

Workers AI (Recommended - Free)

const embeddings = await env.AI.run('@cf/baai/bge-base-en-v1.5', {
  text: ["Document 1 content", "Document 2 content"]
});

// embeddings.data is number[][] (array of 768-dim vectors)
const vectors = embeddings.data.map((values, i) => ({
  id: `doc-${i}`,
  values,
  metadata: { source: 'batch-import' }
}));

await env.VECTORIZE_INDEX.upsert(vectors);

OpenAI Embeddings

import OpenAI from 'openai';

const openai = new OpenAI({ apiKey: env.OPENAI_API_KEY });

const response = await openai.embeddings.create({
  model: "text-embedding-3-small",  // 1536 dimensions
  input: "Text to embed"
});

await env.VECTORIZE_INDEX.upsert([{
  id: "doc-1",
  values: response.data[0].embedding,
  metadata: { model: "openai-3-small" }
}]);

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. Key Restrictions

// ❌ INVALID metadata keys
metadata: {
  "": "value",              // Empty key
  "user.name": "John",      // Contains dot (reserved for nesting)
  "$admin": true,           // Starts with $
  "key\"with\"quotes": 1    // Contains quotes
}

// ✅ VALID metadata keys
metadata: {
  "user_name": "John",
  "isAdmin": true,
  "nested": { "allowed": true }  // Access as "nested.allowed" i