With Cloudflare Vectorize, how does a Worker embed a search phrase with Workers AI and query an index for the closest pages?
answer
- two bindings on env
- same model as the indexed pages
- data[0], not the whole response
- topK, returnValues, returnMetadata defaults
basics
~20 sBind the index under vectorize and Workers AI under ai, embed the phrase with env.AI.run() using the model that embedded the pages, then pass its data[0] vector to the index's query() with topK and returnMetadata.
solid answer
~30 sThe Wrangler file declares a `vectorize` binding (`binding` plus `index_name`) and an `ai` binding. In the fetch handler I embed the phrase with `env.AI.run("@cf/baai/bge-base-en-v1.5", { text: [q] })`, the same model that embedded the pages, and pass `result.data[0]` to `env.DOCS_INDEX.query()`; passing the whole response is an error. Each match has an `id` and a `score`. `topK` defaults to 5, `returnValues` to `false` and `returnMetadata` to `"none"`; `"indexed"` is free but returns only indexed fields, `"all"` returns everything more slowly. `topK` can reach 100, or 50 when the query returns values or all metadata.
code
json · 9 lines{
"name": "docs-search",
"main": "src/index.js",
"compatibility_date": "2026-10-01",
"ai": { "binding": "AI" },
"vectorize": [
{ "binding": "DOCS_INDEX", "index_name": "docs-search" }
]
}go deeper
Recall the two bindings, the embed-then-query order and that query() takes the single vector data[0]. Know that topK defaults to 5 and that metadata is not returned unless requested.
Explain the returnMetadata levels, why indexed costs nothing but may truncate, and how returnValues switches to high-precision scoring at a latency cost.
Show the judgment that keeps search honest: one model for pages and queries, scores logged while tuning, and topK and metadata level chosen for the page's latency budget.
Frame the cost of the search path: every query spends a model call and queried vector dimensions, so caching popular phrases or using queryById for related-page boxes is a design lever.
## What the Worker needs A **Vectorize index** is Cloudflare's store for embeddings: fixed-length arrays of numbers that an embedding model produces from text. A Worker never talks to the index over a URL with an API token; it reaches the index through a **binding**, a named object on `env` that the Wrangler file declares. For a documentation site's semantic search, the Worker needs two bindings: - a `vectorize` binding, an array of objects with `binding` (the name the code uses, say `DOCS_INDEX`) and `index_name` (the index created earlier, say `docs-search`); - an `ai` binding to Workers AI, so the same Worker can turn the visitor's search phrase into a vector with the same model that embedded the pages. The model must be the one the pages were embedded with. A query vector from a different model has a different length, or the same length with unrelated meaning, and the scores stop meaning anything. ## The three steps of a search request 1. **Read the phrase** from the request, and return a 400 when it is empty, so no model call is spent on nothing worth searching. 2. **Embed it.** `env.AI.run("@cf/baai/bge-base-en-v1.5", { text: [q] })` returns an object with `shape` (for one input, `[1, 768]`) and `data`, an array holding one vector per input string. 3. **Query the index** with `env.DOCS_INDEX.query(embedding.data[0], options)`. The argument is the single vector `data[0]`. Passing the whole response object, or the `data` array of arrays, makes `query()` return an error. The result is `{ count, matches }`, and each match carries the vector's `id` and a `score` computed with the index's distance metric. The `id` is whatever the indexing job chose, usually the page or chunk identifier, so the Worker can map a match back to a URL. ## The query options and their defaults | Option | Default | What it changes | |---|---|---| | `topK` | `5` | How many matches come back | | `returnValues` | `false` | Adds each match's vector values and switches to high-precision scoring | | `returnMetadata` | `"none"` | `"indexed"` returns only metadata fields that have a metadata index; `"all"` returns every field | | `namespace` | not set | Searches only the vectors written with that namespace | | `filter` | not set | Keeps only vectors whose indexed metadata matches | Three of these carry limits worth remembering: - **`topK`** may reach **100** when the query returns neither values nor full metadata, and **50** when it sets `returnValues: true` or `returnMetadata: "all"`. Before March 2026 that second ceiling was 20. - **`returnMetadata: "indexed"`** adds no latency, but long strings can come back truncated, and only indexed fields appear. - **`returnMetadata: "all"`** reads the full metadata (up to 10 KiB per vector) and makes the query slower. `returnValues: true` is worth knowing for a second reason: by default Vectorize returns **approximate scores**, and asking for the values makes it score the matches against the original vectors, which is more precise and slower. A search page rarely needs the values themselves. ## A related call: queryById When the starting point is already in the index ("pages like this one"), `queryById("page-123", options)` runs the same search using the stored vector of that ID, with the same options. It saves an embedding call, since the vector is already there. ## Habits that keep the results honest - Return the `score` with each match while the feature is new; it makes a wrong model or a wrong metric obvious in review. - Store the page URL and title as metadata at write time, so the search response needs no second lookup for small fields. - Ask for `"indexed"` metadata on hot paths when every field the page shows is indexed, and `"all"` only when a field is not. - Keep `topK` modest. Ten matches fill a results page, and a higher value only spends latency. - Expect a page written a moment ago to be missing: writes reach queries asynchronously, so a search for brand-new content can briefly return older pages instead. - Give the Worker the index's binding only; it never needs an account API token to query, which keeps a credential out of the request path. Calling the model itself (model names, streaming, neurons and limits) is covered with Workers AI inference; this question stops at handing its vector to the index.
- When would you call queryById() instead of query() on a Vectorize binding?When the starting point is already in the index, such as a "related pages" box on a docs page. `queryById("page-123", { topK: 5 })` searches with that vector's stored values and takes the same options as `query()`, so there is no embedding call. It only works once the vector's write has been applied to the index.
- Why might a search page choose returnMetadata: "indexed" over "all"?`"indexed"` returns the fields that have a metadata index with no latency overhead, while `"all"` reads every stored field and caps `topK` at 50. If the page shows only fields that are indexed, `"indexed"` is the cheaper choice; the catch is that long strings can come back truncated, so a title longer than the indexed prefix may need `"all"`.
- Passes the whole env.AI.run() response object straight to query()
- Embeds search phrases with a different model than the indexed pages
- Calls the index over HTTP with an API token from inside the Worker
- Thinks query() returns metadata unless told not to
- Sets topK to 100 while also asking for all metadata
Assumes Vectorize as of 2026-10-10: since March 2026 topK may reach 50 when a query returns values or all metadata, up from 20.