Introduction to Vectorize·续

// 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:

1. Define a binding to your Vectorize index from your Workers code. This binding matches the `binding` value you set in the `wrangler.jsonc` file under the `"vectorise"` key.
2. Specify a set of example vectors that you will query against in the next step.
3. 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.

## 6. Query vectors

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`:

```typescript
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&lt;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&lt;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&lt;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&lt;Env>;

You can also use the Vectorize queryById() operation to search for vectors similar to a vector that is already present in the index.

7. Deploy your Worker

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.

8. Query your index

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:

  1. Insert your vectors first by visiting /insert. This should return the below JSON:
// https://vectorize-tutorial.&lt;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.

  1. Query your index - expect your query vector of [0.13, 0.25, 0.44, ...] to be closest to vector ID 4 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.&lt;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.

Was this helpful?

YesNo

On this page

Introduction to Vectorize·续 - 图1Docs

{"@context":"https://schema.org","@type":"TechArticle","@id":"https://developers.cloudflare.com/vectorize/get-started/intro/#page","headline":"Introduction to Vectorize","description":"Create your first Vectorize index, connect a Worker, and run a similarity search.","url":"https://developers.cloudflare.com/vectorize/get-started/intro/","inLanguage":"en","image":"https://developers.cloudflare.com/vectorize/get-started/intro/og.png?v=1fcc76bbfb5c04b8","dateModified":"2026-10-12","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"}}

description: Learn how to create Vectorize indexes, configure dimensions, and choose distance metrics. title: Create indexes image: https://developers.cloudflare.com/vectorize/best-practices/create-indexes/og.png?v=7b217488a34f63be

Skip to content

Documentation Index
Fetch the complete documentation index at: https://developers.cloudflare.com/vectorize/llms.txt
Use this file to discover all available pages before exploring further.