Vectorize

Build vector search and AI applications with Vectorize

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',
  },
});

account_id · string · required

Your Cloudflare account ID

name · string · required

Name for the index

config · object · required

Index configuration object

config.dimensions · number · required

Vector dimensions (e.g., 768 for many embedding models)

config.metric · string · required

Distance metric: ‘cosine’, ‘euclidean’, or ‘dot-product’

description · string

Optional description for the index

name · string

The index name

config · object

The index configuration

created_on · string

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

account_id · string · required

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

index_name · string · required

The index name

account_id · string · required

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

index_name · string · required

The index name to delete

account_id · string · required

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' },
      },
    ],
  }
);

index_name · string · required

The index name

account_id · string · required

Your Cloudflare account ID

vectors · array · required

Array of vector objects to insert (up to 1000 vectors per request)

vectors.id · string · required

Unique identifier for the vector

vectors.values · array · required

Vector values (must match index dimensions)

vectors.metadata · object

Optional metadata to store with the vector (up to 10KB)

count · number

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' },
      },
    ],
  }
);

index_name · string · required

The index name

account_id · string · required

Your Cloudflare account ID

vectors · array · required

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

index_name · string · required

The index name

account_id · string · required

Your Cloudflare account ID

vector · array · required

Query vector (must match index dimensions)

top_k · number

Number of results to return (default: 5, max: 100)

return_values · boolean

Whether to return vector values (default: false)

return_metadata · boolean

Whether to return metadata (default: true)

filter · object

Metadata filters for the search

matches · array

Array of matching vectors

matches.id · string

The vector ID

matches.score · number

Similarity score (interpretation depends on metric)

matches.metadata · object

The vector metadata (if return_metadata=true)

matches.values · array

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'],
  }
);

index_name · string · required

The index name

account_id · string · required

Your Cloudflare account ID

ids · array · required

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'],
  }
);

index_name · string · required

The index name

account_id · string · required

Your Cloudflare account ID

ids · array · required

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

index_name · string · required

The index name

account_id · string · required

Your Cloudflare account ID

limit · number

Maximum number of vectors to return (default: 100, max: 1000)

cursor · string

Pagination cursor for fetching the next page

Index information

Get statistics about an index.

const info = await client.vectorize.indexes.info(
  'my-index',
  { account_id: '023e105f4ecef8ad9ca31a8372d0c353' }
);

vector_count · number

Total number of vectors in the index

dimensions · number

Vector dimensions

metric · string

Distance metric used

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: [...],
  }
);

Then query from your Worker:

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