Cloudflare.Vectorize reference

SearchIndex

Source: src/Cloudflare/Vectorize/SearchIndex.ts

Bind a Index to a Worker and obtain the Effect-native Vectorize client (describe, query, upsert, …).

SearchIndex is a single identifier that is simultaneously the binding’s Context tag, its type, and the callable — yield* Cloudflare.Vectorize.SearchIndex(index).

SearchIndex: Examples

const vec = yield* Cloudflare.Vectorize.SearchIndex(MyIndex);
const matches = yield* vec.query([0.1, 0.2, 0.3], { topK: 5 });

Index

Source: src/Cloudflare/Vectorize/VectorizeIndex.ts

A Cloudflare Vectorize index for storing and querying vector embeddings.

Vectorize is a globally distributed vector database. Create an index as a resource, then bind it to a Worker to insert, upsert, and query vectors.

A Vectorize index is identified by its name and is immutable: its dimensions, metric, preset, and description are all fixed at creation. Changing any of them triggers a replacement.

Index: Creating an Index

Index with explicit dimensions and metric

const index = yield* Cloudflare.Vectorize.Index("my-index", {
  dimensions: 768,
  metric: "cosine",
});

Index from a managed embedding model preset

A preset fixes the dimensions and metric to match the named model.

const index = yield* Cloudflare.Vectorize.Index("my-index", {
  preset: "@cf/baai/bge-base-en-v1.5",
});

Index with a description

const index = yield* Cloudflare.Vectorize.Index("my-index", {
  dimensions: 1536,
  metric: "euclidean",
  description: "Product catalog embeddings",
});

Index: Binding to a Worker

const index = yield* Cloudflare.Vectorize.SearchIndex(MyIndex);

// Insert vectors
yield* index.upsert([
  { id: "1", values: [0.1, 0.2, 0.3], metadata: { title: "doc" } },
]);

// Query the nearest neighbors
const matches = yield* index.query([0.1, 0.2, 0.3], { topK: 5 });

MetadataIndex

Source: src/Cloudflare/Vectorize/VectorizeMetadataIndex.ts

A metadata index on a Cloudflare Vectorize index.

Metadata indexes enable filtering query results by metadata properties. Without a metadata index on a property, that property cannot be used in the filter of a query() call.

A metadata index is identified by its parent index and propertyName and is immutable — changing the property name, type, or parent index triggers a replacement.

MetadataIndex: Creating a Metadata Index

Index a string metadata property

const index = yield* Cloudflare.Vectorize.Index("my-index", {
  dimensions: 768,
  metric: "cosine",
});

yield* Cloudflare.Vectorize.MetadataIndex("CategoryMetaIndex", {
  indexName: index.indexName,
  propertyName: "category",
  indexType: "string",
});

Index a numeric metadata property

yield* Cloudflare.Vectorize.MetadataIndex("PriceMetaIndex", {
  indexName: index.indexName,
  propertyName: "price",
  indexType: "number",
});