Vectorize Search

Upsert text documents as vectors and search them by natural language using Workers AI embeddings and Vectorize at the edge.

API Reference

POST /upsert

Embeds text with Workers AI and upserts the vector into Vectorize with metadata.

Example Request

curl -X POST "https://your-worker.workers.dev/upsert" \
  -H "Content-Type: application/json" \
  -d '{"id":"doc-1","text":"Cloudflare Workers run at the edge"}'

Success Response

id string

The document id that was upserted

{
  "id": "doc-1"
}

Error Response

{
  "error": "Missing or invalid field: text",
  "code": "INVALID_TEXT"
}

Error Codes

• 400 - Invalid JSON body (INVALID_BODY)
• 400 - Missing or invalid id (INVALID_ID)
• 400 - Missing or invalid text (INVALID_TEXT)
• 502 - Embedding or Vectorize operation failed (VECTORIZE_ERROR)

GET /search

Embeds the query with Workers AI and returns the nearest Vectorize matches.

Example Request

curl "https://your-worker.workers.dev/search?q=edge%20computing&topK=5"

Success Response

query string

The search query that was embedded

results array

Matching documents, each with id, score, and text

{
  "query": "edge computing",
  "results": [
    {
      "id": "doc-1",
      "score": 0.87,
      "text": "Cloudflare Workers run at the edge"
    }
  ]
}

Error Response

{
  "error": "Missing or invalid query parameter: q",
  "code": "INVALID_QUERY"
}

Error Codes

• 400 - Missing or invalid q (INVALID_QUERY)
• 400 - Invalid topK (must be 1–20) (INVALID_TOP_K)
• 502 - Embedding or Vectorize operation failed (VECTORIZE_ERROR)

Use Cases

• Build semantic search over product docs or support articles at the edge
• Prototype RAG pipelines with Vectorize as the vector store
• Learn Workers AI embeddings with @cf/baai/bge-base-en-v1.5
• Compare cosine similarity search without running a separate vector database

Limitations

• Demo index; vectors are tied to your Vectorize binding and redeploy lifecycle
• Text length is capped before embedding
• Requires Workers AI and Vectorize bindings
• Semantic search over the demo corpus only; not a production RAG pipeline

Deployment

wrangler vectorize create experiment-search --dimensions=768 --metric=cosine

curl -X POST "https://your-worker.workers.dev/upsert" \
  -H "Content-Type: application/json" \
  -d '{"id":"doc-1","text":"Cloudflare Workers run at the edge"}'

curl "https://your-worker.workers.dev/search?q=edge%20computing&topK=5"

Local Development

cd apps/experiments/vectorize-search
npm install
wrangler vectorize create experiment-search --dimensions=768 --metric=cosine
npm run dev

Test locally:

curl -X POST "http://localhost:8787/upsert" \
  -H "Content-Type: application/json" \
  -d '{"id":"doc-1","text":"Cloudflare Workers run at the edge"}'

curl "http://localhost:8787/search?q=edge%20computing&topK=5"

Cloudflare Features Used

• Workers - Edge compute runtime
• Workers AI - @cf/baai/bge-base-en-v1.5 text embeddings
• Vectorize - experiment-search index (768 dims, cosine)