Vectorize API
This page covers the Vectorize API available within Cloudflare Workers, including usage examples.
Inserts vectors into the index. Returns the count of vectors inserted and their IDs.
If vectors with the same vector ID already exist in the index, only the vectors with new IDs will be inserted. The returned VectorizeVectorMutation
will return a count
and an ids
array with IDs of the vectors inserted into the index, and omit IDs that already exist in the index.
If you need to update existing vectors, use the upsert operation.
Upserts vectors into an index. Returns the count of vectors upserted and their IDs.
An upsert operation will insert vectors into the index if vectors with the same ID do not exist, and overwrite vectors with the same ID.
Upserting does not merge or combine the values or metadata of an existing vector with the upserted vector: the upserted vector replaces the existing vector in full.
Query an index with the provided vector, returning the score(s) of the closest vectors based on the configured distance metric.
- Configure the number of returned matches by setting
topK
(default: 3) - Return vector values by setting
returnValues: true
(default: false) - Return vector metadata by setting
returnMetadata: true
(default: false)
Retrieves the specified vectors by their ID, including values and metadata.
Deletes the vector IDs provided from the current index. Returns a count of the IDs provided and the list of vector IDs.
Retrieves the configuration of a given index directly, including its configured dimensions
and distance metric
.
A vector represents the vector embedding output from a machine learning model.
id
- a uniquestring
identifying the vector in the index. This should map back to the ID of the document, object or database identifier that the vector values were generated from.namespace
- an optional partition key within a index. Operations are performed per-namespace, so this can be used to create isolated segments within a larger index.values
- an array ofnumber
,Float32Array
, orFloat64Array
as the vector embedding itself. This must be a dense array, and the length of this array must match thedimensions
configured on the index.metadata
- an optional set of key-value pairs that can be used to store additional metadata alongside a vector.
Bindings allow you to attach resources, including Vectorize indexes or R2 buckets, to your Worker.
Bindings are defined in either the wrangler.toml
configuration associated with your Workers project, or via the Cloudflare dashboard for your project.
Vectorize indexes are bound by name. A binding for an index named production-doc-search
would resemble the below:
Refer to the bindings documentation for more details.
New Workers projects created via npm create cloudflare@latest
automatically include the relevant TypeScript types for Vectorize.
Older projects, or non-Workers projects looking to use Vectorize’s REST API in a TypeScript project, should ensure @cloudflare/workers-types
version 4.20230922.0
or later is installed.