/cloudflare-vectorize

name: cloudflare-vectorize
description: "Cloudflare Vectorize vector database for semantic search and RAG. Use for vector indexes, embeddings, similarity search, or encountering dimension mismatches, filter errors."

metadata:
  keywords:
    - vectorize
    - vector database
    - vector index
    - vector search
    - similarity search
    - semantic search
    - nearest neighbor
    - knn search
    - ann search
    - RAG
    - retrieval augmented generation
    - chat with data
    - document search
    - semantic Q&A
    - context retrieval
    - bge-base
    - "@cf/baai/bge-base-en-v1.5"
    - text-embedding-3-small
    - text-embedding-3-large
    - Workers AI embeddings
    - openai embeddings
    - insert vectors
    - upsert vectors
    - query vectors
    - delete vectors
    - metadata filtering
    - namespace filtering
    - topK search
    - cosine similarity
    - euclidean distance
    - dot product
    - wrangler vectorize
    - metadata index
    - create vectorize index
    - vectorize dimensions
    - vectorize metric
    - vectorize binding

license: MIT

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-11-21 **Dependencies**: cloudflare-worker-base (for Worker setup), cloudflare-workers-ai (for embeddings) **Latest Versions**: wrangler@4.81.0, @cloudflare/workers-types@4.20260408.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
bunx wrangler vectorize create my-index \
  --dimensions=768 \
  --metric=cosine

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

bunx 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

Quick Reference

| Operation | Method | Key Point | |-----------|--------|-----------| | **Insert** | `insert([...])` | Keeps first if ID exists | | **Upsert** | `upsert([...])` | Overwrites if ID exists (use for updates) | | **Query** | `query(vector, { topK, filter })` | Returns similar vectors | | **Delete** | `deleteByIds([...])` | Remove by ID array | | **Get** | `getByIds([...])` | Retrieve specific vectors |

Filter Operators

| Operator | Example | Description | |----------|---------|-------------| | `$eq` | `{ category: "docs" }` | Equality (implicit) | | `$ne` | `{ status: { $ne: "archived" } }` | Not equal | | `$in` | `{ category: { $in: ["a", "b"] } }` | In array | | `$nin` | `{ category: { $nin: ["x"] } }` | Not in array | | `$gte/$lt` | `{ timestamp: { $gte: 123 } }` | Range queries |

📄 **Full operations guide**: Load `references/vector-operations.md` for complete insert/upsert/query/delete examples with code.

Embedding Generation

| Model | Provider | Dimensions | Best For | |-------|----------|------------|----------| | `@cf/baai/bge-base-en-v1.5` | Workers AI | 768 | Free, general purpose | | `text-embedding-3-small` | OpenAI | 1536 | Balance quality/cost | | `text-embedding-3-large` | OpenAI | 3072 | Highest quality |

📄 **Integration guides**:

• Load `references/integration-workers-ai-bge-base.md` for Workers AI setup
• Load `references/integration-openai-embeddings.md` for OpenAI integration

Met