Introduction to Vectorize
Vectorize is Cloudflare’s vector database. Vector databases allow you to use machine learning (ML) models to perform semantic search, recommendation, classification and anomaly detection tasks, as well as provide context to LLMs (Large Language Models).
This guide will instruct you through:
- Creating your first Vectorize index.
- Connecting a Cloudflare Worker to your index.
- Inserting and performing a similarity search by querying your index.
To continue, you will need:
- Sign up for a Cloudflare account ↗ if you have not already.
- Install
npm
↗. - Install
Node.js
↗. Use a Node version manager like Volta ↗ or nvm ↗ to avoid permission issues and change Node.js versions. Wrangler requires a Node version of16.17.0
or later.
You will create a new project that will contain a Worker, which will act as the client application for your Vectorize index.
Create a new project named vectorize-tutorial
by running:
npm create cloudflare@latest -- vectorize-tutorial
yarn create cloudflare@latest vectorize-tutorial
pnpm create cloudflare@latest vectorize-tutorial
For setup, select the following options:
- For What would you like to start with?, choose
Hello World example
. - For Which template would you like to use?, choose
Hello World Worker
. - For Which language do you want to use?, choose
TypeScript
. - For Do you want to use git for version control?, choose
Yes
. - For Do you want to deploy your application?, choose
No
(we will be making some changes before deploying).
This will create a new vectorize-tutorial
directory. Your new vectorize-tutorial
directory will include:
- A
"Hello World"
Worker atsrc/index.ts
. - A
wrangler.toml
configuration file.wrangler.toml
is how yourvectorize-tutorial
Worker will access your index.
A vector database is distinct from a traditional SQL or NoSQL database. A vector database is designed to store vector embeddings, which are representations of data, but not the original data itself.
To create your first Vectorize index, change into the directory you just created for your Workers project:
cd vectorize-tutorial
To create an index, you will need to use the wrangler vectorize create
command and provide a name for the index. A good index name is:
- A combination of lowercase and/or numeric ASCII characters, shorter than 32 characters, starts with a letter, and uses dashes (-) instead of spaces.
- Descriptive of the use-case and environment. For example, “production-doc-search” or “dev-recommendation-engine”.
- Only used for describing the index, and is not directly referenced in code.
In addition, you will need to define both the dimensions
of the vectors you will store in the index, as well as the distance metric
used to determine similar vectors when creating the index. A metric
can be euclidean, cosine, or dot product. This configuration cannot be changed later, as a vector database is configured for a fixed vector configuration.
Run the following wrangler vectorize
command:
npx wrangler vectorize create tutorial-index --dimensions=32 --metric=euclidean
🚧 Creating index: 'tutorial-index'✅ Successfully created a new Vectorize index: 'tutorial-index'📋 To start querying from a Worker, add the following binding configuration into 'wrangler.toml':
[[vectorize]]binding = "VECTORIZE" # available in your Worker on env.VECTORIZEindex_name = "tutorial-index"
The command above will create a new vector database, and output the binding configuration needed in the next step.
You must create a binding for your Worker to connect to your Vectorize index. Bindings allow your Workers to access resources, like Vectorize or R2, from Cloudflare Workers. You create bindings by updating the worker’s wrangler.toml
file.
To bind your index to your Worker, add the following to the end of your wrangler.toml
file:
[[vectorize]]binding = "VECTORIZE" # available in your Worker on env.VECTORIZEindex_name = "tutorial-index"
Specifically:
- The value (string) you set for
<BINDING_NAME>
will be used to reference this database in your Worker. In this tutorial, name your bindingVECTORIZE
. - The binding must be a valid JavaScript variable name ↗. For example,
binding = "MY_INDEX"
orbinding = "PROD_SEARCH_INDEX"
would both be valid names for the binding. - Your binding is available in your Worker at
env.<BINDING_NAME>
and the Vectorize client API is exposed on this binding for use within your Workers application.
Vectorize allows you to add metadata along with vectors into your index, and also provides the ability to to filter on the vector metadata while querying vectors. To do so you would need to specify a metadata field as a “metadata index” for your Vectorize index.
To enable vector filtering on a metadata field during a query, use a command like:
npx wrangler vectorize create-metadata-index tutorial-index --property-name=url --type=string
📋 Creating metadata index...✅ Successfully enqueued metadata index creation request. Mutation changeset identifier: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.
Here url
is the metadata field on which filtering would be enabled. The --type
parameter defines the data type for the metadata field; string
, number
and boolean
types are supported.
It typically takes a few seconds for the metadata index to be created. You can check the list of metadata indexes for your Vectorize index by running:
npx wrangler vectorize list-metadata-index tutorial-index
📋 Fetching metadata indexes...┌──────────────┬────────┐│ propertyName │ type │├──────────────┼────────┤│ url │ String │└──────────────┴────────┘
Before you can query a vector database, you need to insert vectors for it to query against. These vectors would be generated from data (such as text or images) you pass to a machine learning model. However, this tutorial will define static vectors to illustrate how vector search works on its own.
First, go to your vectorize-tutorial
Worker and open the src/index.ts
file. The index.ts
file is where you configure your Worker’s interactions with your Vectorize index.
Clear the content of index.ts
, and paste the following code snippet into your index.ts
file. On the env
parameter, replace <BINDING_NAME>
with VECTORIZE
:
export interface Env { // This makes your vector index methods available on env.VECTORIZE.* // For example, env.VECTORIZE.insert() or query() VECTORIZE: Vectorize;}
// Sample vectors: 32 dimensions wide.//// Vectors from popular machine-learning models are typically ~100 to 1536 dimensions// wide (or wider still).const sampleVectors: Array<VectorizeVector> = [ { id: "1", values: [ 0.12, 0.45, 0.67, 0.89, 0.23, 0.56, 0.34, 0.78, 0.12, 0.9, 0.24, 0.67, 0.89, 0.35, 0.48, 0.7, 0.22, 0.58, 0.74, 0.33, 0.88, 0.66, 0.45, 0.27, 0.81, 0.54, 0.39, 0.76, 0.41, 0.29, 0.83, 0.55, ], metadata: { url: "/products/sku/13913913" }, }, { id: "2", values: [ 0.14, 0.23, 0.36, 0.51, 0.62, 0.47, 0.59, 0.74, 0.33, 0.89, 0.41, 0.53, 0.68, 0.29, 0.77, 0.45, 0.24, 0.66, 0.71, 0.34, 0.86, 0.57, 0.62, 0.48, 0.78, 0.52, 0.37, 0.61, 0.69, 0.28, 0.8, 0.53, ], metadata: { url: "/products/sku/10148191" }, }, { id: "3", values: [ 0.21, 0.33, 0.55, 0.67, 0.8, 0.22, 0.47, 0.63, 0.31, 0.74, 0.35, 0.53, 0.68, 0.45, 0.55, 0.7, 0.28, 0.64, 0.71, 0.3, 0.77, 0.6, 0.43, 0.39, 0.85, 0.55, 0.31, 0.69, 0.52, 0.29, 0.72, 0.48, ], metadata: { url: "/products/sku/97913813" }, }, { id: "4", values: [ 0.17, 0.29, 0.42, 0.57, 0.64, 0.38, 0.51, 0.72, 0.22, 0.85, 0.39, 0.66, 0.74, 0.32, 0.53, 0.48, 0.21, 0.69, 0.77, 0.34, 0.8, 0.55, 0.41, 0.29, 0.7, 0.62, 0.35, 0.68, 0.53, 0.3, 0.79, 0.49, ], metadata: { url: "/products/sku/418313" }, }, { id: "5", values: [ 0.11, 0.46, 0.68, 0.82, 0.27, 0.57, 0.39, 0.75, 0.16, 0.92, 0.28, 0.61, 0.85, 0.4, 0.49, 0.67, 0.19, 0.58, 0.76, 0.37, 0.83, 0.64, 0.53, 0.3, 0.77, 0.54, 0.43, 0.71, 0.36, 0.26, 0.8, 0.53, ], metadata: { url: "/products/sku/55519183" }, },];
export default { async fetch(request, env, ctx): Promise<Response> { let path = new URL(request.url).pathname; if (path.startsWith("/favicon")) { return new Response("", { status: 404 }); }
// You only need to insert vectors into your index once if (path.startsWith("/insert")) { // Insert some sample vectors into your index // In a real application, these vectors would be the output of a machine learning (ML) model, // such as Workers AI, OpenAI, or Cohere. const inserted = await env.VECTORIZE.insert(sampleVectors);
// Return the mutation identifier for this insert operation return Response.json(inserted); }
return Response.json({ text: "nothing to do... yet" }, { status: 404 }); },} satisfies ExportedHandler<Env>;
In the code above, you:
- Define a binding to your Vectorize index from your Workers code. This binding matches the
binding
value you set inwrangler.toml
under[[vectorize]]
. - Specify a set of example vectors that you will query against in the next step.
- Insert those vectors into the index and confirm it was successful.
In the next step, you will expand the Worker to query the index and the vectors you insert.
In this step, you will take a vector representing an incoming query and use it to search your index.
First, go to your vectorize-tutorial
Worker and open the src/index.ts
file. The index.ts
file is where you configure your Worker’s interactions with your Vectorize index.
Clear the content of index.ts
. Paste the following code snippet into your index.ts
file. On the env
parameter, replace <BINDING_NAME>
with VECTORIZE
:
export interface Env { // This makes your vector index methods available on env.VECTORIZE.* // For example, env.VECTORIZE.insert() or query() VECTORIZE: Vectorize;}
// Sample vectors: 32 dimensions wide.//// Vectors from popular machine-learning models are typically ~100 to 1536 dimensions// wide (or wider still).const sampleVectors: Array<VectorizeVector> = [ { id: "1", values: [ 0.12, 0.45, 0.67, 0.89, 0.23, 0.56, 0.34, 0.78, 0.12, 0.9, 0.24, 0.67, 0.89, 0.35, 0.48, 0.7, 0.22, 0.58, 0.74, 0.33, 0.88, 0.66, 0.45, 0.27, 0.81, 0.54, 0.39, 0.76, 0.41, 0.29, 0.83, 0.55, ], metadata: { url: "/products/sku/13913913" }, }, { id: "2", values: [ 0.14, 0.23, 0.36, 0.51, 0.62, 0.47, 0.59, 0.74, 0.33, 0.89, 0.41, 0.53, 0.68, 0.29, 0.77, 0.45, 0.24, 0.66, 0.71, 0.34, 0.86, 0.57, 0.62, 0.48, 0.78, 0.52, 0.37, 0.61, 0.69, 0.28, 0.8, 0.53, ], metadata: { url: "/products/sku/10148191" }, }, { id: "3", values: [ 0.21, 0.33, 0.55, 0.67, 0.8, 0.22, 0.47, 0.63, 0.31, 0.74, 0.35, 0.53, 0.68, 0.45, 0.55, 0.7, 0.28, 0.64, 0.71, 0.3, 0.77, 0.6, 0.43, 0.39, 0.85, 0.55, 0.31, 0.69, 0.52, 0.29, 0.72, 0.48, ], metadata: { url: "/products/sku/97913813" }, }, { id: "4", values: [ 0.17, 0.29, 0.42, 0.57, 0.64, 0.38, 0.51, 0.72, 0.22, 0.85, 0.39, 0.66, 0.74, 0.32, 0.53, 0.48, 0.21, 0.69, 0.77, 0.34, 0.8, 0.55, 0.41, 0.29, 0.7, 0.62, 0.35, 0.68, 0.53, 0.3, 0.79, 0.49, ], metadata: { url: "/products/sku/418313" }, }, { id: "5", values: [ 0.11, 0.46, 0.68, 0.82, 0.27, 0.57, 0.39, 0.75, 0.16, 0.92, 0.28, 0.61, 0.85, 0.4, 0.49, 0.67, 0.19, 0.58, 0.76, 0.37, 0.83, 0.64, 0.53, 0.3, 0.77, 0.54, 0.43, 0.71, 0.36, 0.26, 0.8, 0.53, ], metadata: { url: "/products/sku/55519183" }, },];
export default { async fetch(request, env, ctx): Promise<Response> { let path = new URL(request.url).pathname; if (path.startsWith("/favicon")) { return new Response("", { status: 404 }); }
// You only need to insert vectors into your index once if (path.startsWith("/insert")) { // Insert some sample vectors into your index // In a real application, these vectors would be the output of a machine learning (ML) model, // such as Workers AI, OpenAI, or Cohere. let inserted = await env.VECTORIZE.insert(sampleVectors);
// Return the mutation identifier for this insert operation return Response.json(inserted); }
// return Response.json({text: "nothing to do... yet"}, { status: 404 })
// In a real application, you would take a user query. For example, "what is a // vector database" - and transform it into a vector embedding first. // // In this example, you will construct a vector that should // match vector id #4 const queryVector: Array<number> = [ 0.13, 0.25, 0.44, 0.53, 0.62, 0.41, 0.59, 0.68, 0.29, 0.82, 0.37, 0.5, 0.74, 0.46, 0.57, 0.64, 0.28, 0.61, 0.73, 0.35, 0.78, 0.58, 0.42, 0.32, 0.77, 0.65, 0.49, 0.54, 0.31, 0.29, 0.71, 0.57, ]; // vector of dimensions 32
// Query your index and return the three (topK = 3) most similar vector // IDs with their similarity score. // // By default, vector values are not returned, as in many cases the // vector id and scores are sufficient to map the vector back to the // original content it represents. const matches = await env.VECTORIZE.query(queryVector, { topK: 3, returnValues: true, returnMetadata: "all", });
return Response.json({ // This will return the closest vectors: the vectors are arranged according // to their scores. Vectors that are more similar would show up near the top. // In this example, Vector id #4 would turn out to be the most similar to the queried vector. // You return the full set of matches so you can check the possible scores. matches: matches, }); },} satisfies ExportedHandler<Env>;
Before deploying your Worker globally, log in with your Cloudflare account by running:
npx wrangler login
You will be directed to a web page asking you to log in to the Cloudflare dashboard. After you have logged in, you will be asked if Wrangler can make changes to your Cloudflare account. Scroll down and select Allow to continue.
From here, you can deploy your Worker to make your project accessible on the Internet. To deploy your Worker, run:
npx wrangler deploy
Once deployed, preview your Worker at https://vectorize-tutorial.<YOUR_SUBDOMAIN>.workers.dev
.
To insert vectors and then query them, use the URL for your deployed Worker, such as https://vectorize-tutorial.<YOUR_SUBDOMAIN>.workers.dev/
. Open your browser and:
- Insert your vectors first by visiting
/insert
. This should return the below JSON:
// https://vectorize-tutorial.<YOUR_SUBDOMAIN>.workers.dev/insert{ "mutationId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"}
The mutationId here refers to a unique identifier that corresponds to this asynchronous insert operation. Typically it takes a few seconds for inserted vectors to be available for querying.
You can use the index info operation to check the last processed mutation:
npx wrangler vectorize info tutorial-index
📋 Fetching index info...┌────────────┬─────────────┬──────────────────────────────────────┬──────────────────────────┐│ dimensions │ vectorCount │ processedUpToMutation │ processedUpToDatetime │├────────────┼─────────────┼──────────────────────────────────────┼──────────────────────────┤│ 32 │ 5 │ xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx │ YYYY-MM-DDThh:mm:ss.SSSZ │└────────────┴─────────────┴──────────────────────────────────────┴──────────────────────────┘
Subsequent inserts using the same vector ids will return a mutation id, but it would not change the index vector count since the same vector ids cannot be inserted twice. You will need to use an upsert
operation instead to update the vector values for an id that already exists in an index.
- Query your index - expect your query vector of
[0.13, 0.25, 0.44, ...]
to be closest to vector ID4
by visiting the root path of/
. This query will return the three (topK: 3
) closest matches, as well as their vector values and metadata.
You will notice that id: 4
has a score
of 0.46348256
. Because you are using euclidean
as our distance metric, the closer the score to 0.0
, the closer your vectors are.
// https://vectorize-tutorial.<YOUR_SUBDOMAIN>.workers.dev/{ "matches": { "count": 3, "matches": [ { "id": "4", "score": 0.46348256, "values": [ 0.17, 0.29, 0.42, 0.57, 0.64, 0.38, 0.51, 0.72, 0.22, 0.85, 0.39, 0.66, 0.74, 0.32, 0.53, 0.48, 0.21, 0.69, 0.77, 0.34, 0.8, 0.55, 0.41, 0.29, 0.7, 0.62, 0.35, 0.68, 0.53, 0.3, 0.79, 0.49 ], "metadata": { "url": "/products/sku/418313" } }, { "id": "3", "score": 0.52920616, "values": [ 0.21, 0.33, 0.55, 0.67, 0.8, 0.22, 0.47, 0.63, 0.31, 0.74, 0.35, 0.53, 0.68, 0.45, 0.55, 0.7, 0.28, 0.64, 0.71, 0.3, 0.77, 0.6, 0.43, 0.39, 0.85, 0.55, 0.31, 0.69, 0.52, 0.29, 0.72, 0.48 ], "metadata": { "url": "/products/sku/97913813" } }, { "id": "2", "score": 0.6337869, "values": [ 0.14, 0.23, 0.36, 0.51, 0.62, 0.47, 0.59, 0.74, 0.33, 0.89, 0.41, 0.53, 0.68, 0.29, 0.77, 0.45, 0.24, 0.66, 0.71, 0.34, 0.86, 0.57, 0.62, 0.48, 0.78, 0.52, 0.37, 0.61, 0.69, 0.28, 0.8, 0.53 ], "metadata": { "url": "/products/sku/10148191" } } ] }}
From here, experiment by passing a different queryVector
and observe the results: the matches and the score
should change based on the change in distance between the query vector and the vectors in our index.
In a real-world application, the queryVector
would be the vector embedding representation of a query from a user or system, and our sampleVectors
would be generated from real content. To build on this example, read the vector search tutorial that combines Workers AI and Vectorize to build an end-to-end application with Workers.
By finishing this tutorial, you have successfully created and queried your first Vectorize index, a Worker to access that index, and deployed your project globally.
- Build an end-to-end vector search application using Workers AI and Vectorize.
- Learn more about how vector databases work.
- Read examples on how to use the Vectorize API from Cloudflare Workers.
- Euclidean Distance vs Cosine Similarity ↗.
- Dot product ↗.