Cloudflare Vectorize is a globally distributed vector database for building AI-powered applications. Use the API to create indexes, insert vectors, and perform similarity searches.
Overview
Access the Vectorize API:
import Cloudflare from 'cloudflare';
const client = new Cloudflare({
apiToken: process.env.CLOUDFLARE_API_TOKEN,
});
// Access Vectorize resources
const vectorize = client.vectorize;
Indexes
Manage vector indexes for similarity search.
Create an index
Create a new vector index.
const index = await client.vectorize.indexes.create({
account_id: '023e105f4ecef8ad9ca31a8372d0c353',
name: 'my-index',
config: {
dimensions: 768,
metric: 'cosine',
},
});
Your Cloudflare account ID
Index configuration object
Vector dimensions (e.g., 768 for many embedding models)
Distance metric: ‘cosine’, ‘euclidean’, or ‘dot-product’
Optional description for the index
ISO 8601 timestamp when the index was created
List indexes
Retrieve all vector indexes in your account.
for await (const index of client.vectorize.indexes.list({
account_id: '023e105f4ecef8ad9ca31a8372d0c353',
})) {
console.log(index);
}
Your Cloudflare account ID
Get an index
Retrieve details about a specific index.
const index = await client.vectorize.indexes.get(
'my-index',
{ account_id: '023e105f4ecef8ad9ca31a8372d0c353' }
);
Your Cloudflare account ID
Delete an index
Delete a vector index and all its data.
await client.vectorize.indexes.delete(
'my-index',
{ account_id: '023e105f4ecef8ad9ca31a8372d0c353' }
);
Your Cloudflare account ID
Vectors
Manage vectors within an index.
Insert vectors
Insert vectors into an index.
const response = await client.vectorize.indexes.insert(
'my-index',
{
account_id: '023e105f4ecef8ad9ca31a8372d0c353',
vectors: [
{
id: 'doc-1',
values: [0.1, 0.2, 0.3, ...], // 768 dimensions
metadata: { title: 'Document 1' },
},
{
id: 'doc-2',
values: [0.4, 0.5, 0.6, ...],
metadata: { title: 'Document 2' },
},
],
}
);
Your Cloudflare account ID
Array of vector objects to insert (up to 1000 vectors per request)
Unique identifier for the vector
Vector values (must match index dimensions)
Optional metadata to store with the vector (up to 10KB)
Number of vectors successfully inserted
Upsert vectors
Insert or update vectors.
const response = await client.vectorize.indexes.upsert(
'my-index',
{
account_id: '023e105f4ecef8ad9ca31a8372d0c353',
vectors: [
{
id: 'doc-1',
values: [0.1, 0.2, 0.3, ...],
metadata: { title: 'Updated Document 1' },
},
],
}
);
Your Cloudflare account ID
Array of vector objects to upsert
Query vectors
Perform a similarity search.
const results = await client.vectorize.indexes.query(
'my-index',
{
account_id: '023e105f4ecef8ad9ca31a8372d0c353',
vector: [0.1, 0.2, 0.3, ...], // 768 dimensions
top_k: 5,
return_values: true,
return_metadata: true,
}
);
Your Cloudflare account ID
Query vector (must match index dimensions)
Number of results to return (default: 5, max: 100)
Whether to return vector values (default: false)
Whether to return metadata (default: true)
Metadata filters for the search
Array of matching vectors
Similarity score (interpretation depends on metric)
The vector metadata (if return_metadata=true)
The vector values (if return_values=true)
Get vectors by ID
Retrieve specific vectors by their IDs.
const vectors = await client.vectorize.indexes.getByIds(
'my-index',
{
account_id: '023e105f4ecef8ad9ca31a8372d0c353',
ids: ['doc-1', 'doc-2'],
}
);
Your Cloudflare account ID
Array of vector IDs to retrieve (up to 100 IDs)
Delete vectors by ID
Delete specific vectors from an index.
await client.vectorize.indexes.deleteByIds(
'my-index',
{
account_id: '023e105f4ecef8ad9ca31a8372d0c353',
ids: ['doc-1', 'doc-2'],
}
);
Your Cloudflare account ID
Array of vector IDs to delete (up to 1000 IDs)
List vectors
List all vectors in an index.
const vectors = await client.vectorize.indexes.listVectors(
'my-index',
{
account_id: '023e105f4ecef8ad9ca31a8372d0c353',
limit: 100,
}
);
Your Cloudflare account ID
Maximum number of vectors to return (default: 100, max: 1000)
Pagination cursor for fetching the next page
const info = await client.vectorize.indexes.info(
'my-index',
{ account_id: '023e105f4ecef8ad9ca31a8372d0c353' }
);
Total number of vectors in the index
Using Vectorize in Workers
Bind a Vectorize index to your Worker:
const version = await client.workers.beta.workers.versions.create(
workerId,
{
account_id: accountId,
main_module: 'worker.mjs',
compatibility_date: '2024-03-01',
bindings: [
{
type: 'vectorize',
name: 'VECTORIZE',
index_name: 'my-index',
},
],
modules: [...],
}
);
export default {
async fetch(request, env) {
// Insert vectors
await env.VECTORIZE.insert([
{
id: 'doc-1',
values: embeddings,
metadata: { title: 'Document 1' },
},
]);
// Query for similar vectors
const results = await env.VECTORIZE.query(
queryEmbedding,
{ topK: 5 }
);
return Response.json(results);
},
};