Cloudflare Vectorize vector database for semantic search and RAG. Use for vector indexes, embeddings, similarity search, or encountering dimension mismatches, filter errors.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Cloudflare Vectorize vector database for semantic search and RAG. Use for vector indexes, embeddings, similarity search, or encountering dimension mismatches, filter errors.
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
Recommended chunk sizes: 300-500 characters for semantic coherence.
Key metadata for chunks:
doc_id: Parent document ID
chunk_index: Position in document
content: Text for retrieval display
📄 Full chunking implementation: See templates/document-ingestion.ts for complete chunking pipeline.
Common Errors & Solutions
Error 1: Metadata Index Created After Vectors Inserted
Problem: Filtering doesn't work on existing vectors
Solution: Delete and re-insert vectors OR create metadata indexes BEFORE inserting
Error 2: Dimension Mismatch
Problem: "Vector dimensions do not match index configuration"
Solution: Ensure embedding model output matches index dimensions:
- Workers AI bge-base: 768
- OpenAI small: 1536
- OpenAI large: 3072
Problem: "Filter exceeds 2048 bytes"
Solution: Simplify filter or split into multiple queries
Error 5: Range Query on High Cardinality
Problem: Slow queries or reduced accuracy
Solution: Use lower cardinality fields for range queries, or use seconds instead of milliseconds for timestamps
Error 6: Insert vs Upsert Confusion
Problem: Updates not reflecting in index
Solution: Use upsert() to overwrite existing vectors, not insert()
Error 7: Missing Bindings
Problem: "VECTORIZE_INDEX is not defined"
Solution: Add [[vectorize]] binding to wrangler.jsonc
Error 8: Namespace vs Metadata Confusion
Problem: Unclear when to use namespace vs metadata filtering
Solution:
- Namespace: Partition key, applied BEFORE metadata filters
- Metadata: Flexible key-value filtering within namespace
Wrangler CLI Reference
Essential commands:
# Create index (dimensions/metric are PERMANENT)
bunx wrangler vectorize create <name> --dimensions=768 --metric=cosine
# Create metadata index (MUST be before inserting vectors!)
bunx wrangler vectorize create-metadata-index <name> --property-name=category --type=string
# Get index info
bunx wrangler vectorize info <name>
📄 Full CLI reference: Load references/wrangler-commands.md for all vectorize commands.
Performance Tips
Batch Operations: Insert/upsert in batches of 100-1000 vectors
Selective Return: Only use returnValues: true when needed (saves bandwidth)
Metadata Cardinality: Keep indexed metadata fields low cardinality for range queries
Namespace Filtering: Apply namespace filter before metadata filters (processed first)
Query Optimization: Use topK=3-10 for best latency (larger values increase search time)
When to Use This Skill
✅ Use Vectorize when:
Building semantic search over documents, products, or content
Implementing RAG chatbots with context retrieval
Creating recommendation engines based on similarity
Building multi-tenant applications (use namespaces)
Need global distribution and low latency
❌ Don't use Vectorize for:
Traditional relational data (use D1)
Key-value lookups (use KV)
Large file storage (use R2)
Real-time collaborative state (use Durable Objects)
When to Load References
Reference File
Load When...
references/vector-operations.md
Need full insert/upsert/query/delete code examples
references/metadata-guide.md
Setting up metadata indexes, filtering best practices
references/wrangler-commands.md
Using Vectorize CLI commands
references/integration-workers-ai-bge-base.md
Integrating Workers AI embeddings
references/integration-openai-embeddings.md
Integrating OpenAI embeddings
references/embedding-models.md
Comparing embedding model options
references/index-operations.md
Index lifecycle management
Templates
Template
Purpose
templates/basic-search.ts
Simple vector search
templates/rag-chat.ts
Complete RAG chatbot
templates/document-ingestion.ts
Document chunking pipeline
templates/metadata-filtering.ts
Advanced filtering
Secure Installation
When installing vector database packages, follow supply chain security best practices:
Block post-install scripts — npm config set ignore-scripts true (or Bun: disabled by default)
Cooldown period — Wait 7 days for new package versions to be vetted by the community
Audit before installing — Run socket package score npm <pkg> or use socket npm install <pkg> to check packages
Load the dependency-upgrade skill for full security configuration including Socket CLI integration, cooldown setup, lockfile validation, and CI enforcement.
