skip to content

In Cloudflare Vectorize, why are an index's dimensions and distance metric fixed at creation, and how do you choose them?

level: middleimportance: must knowfreq 32%

answer

  1. the model decides, not you
  2. --dimensions and --metric, or --preset
  3. 768 for bge-base
  4. new model means new index

basics

~20 s

A Vectorize index is built for one vector length and one scoring function, so wrangler vectorize create fixes both. Copy the dimensions from the embedding model (768 for bge-base), use its intended metric, and create a new index when the model changes.

solid answer

~30 s

`wrangler vectorize create docs-search --dimensions=768 --metric=cosine` sets the two values, or `--preset=@cf/baai/bge-base-en-v1.5` sets both from the model. The configuration cannot change afterwards: every vector, and every query vector, must have exactly the configured length, and each metric (`cosine`, `euclidean`, `dot-product`) scores differently. The dimensions come from the embedding model, 384, 768 or 1024 for the small, base and large BGE models, up to Vectorize's 1536 limit. Changing models therefore means a new index: re-embed, recreate the metadata indexes before loading, repoint the binding's `index_name`, deploy, then delete the old index.

code

bash · 8 lines
bash
# Explicit configuration, matching @cf/baai/bge-base-en-v1.5
npx wrangler vectorize create docs-search --dimensions=768 --metric=cosine

# Or let Vectorize configure it from the model name
npx wrangler vectorize create docs-search-v2 --preset=@cf/baai/bge-base-en-v1.5

# Confirm what an index was created with
npx wrangler vectorize info docs-search

go deeper

for a junior

Recall the create command with --dimensions and --metric, that the dimensions come from the embedding model, and that neither value can be changed later.

for a middle

Explain why the values are fixed, how --preset sets them from a model name, and what each metric's score means, including that euclidean and dot-product scores are better when lower.

for a senior

Show how a model change is run as a migration: a parallel index, metadata indexes first, a bulk re-embed, and the binding and query model switched together.

for a principal

Weigh the model's dimension count against cost and quality, since Vectorize bills queried and stored dimensions and every model change costs a full re-embed.

## Creating an index A Vectorize index is created once, with three inputs, and two of them can never change: - a **name** in kebab case, such as `docs-search`, unique among the account's active indexes (the name of a deleted index may be reused); - the **dimensions**, the length of every vector the index will hold; - the **distance metric**, the function that turns two vectors into a similarity score. With Wrangler that is `wrangler vectorize create docs-search --dimensions=768 --metric=cosine`. The command refuses to run with only one of the two flags: it needs both `--dimensions` and `--metric`, or a `--preset`. The same configuration can be sent to the REST API in a `config` object with `dimensions` and `metric`. ## Why the configuration is fixed The documentation states plainly that the configuration of an index cannot be changed after creation: an index is configured for one vector shape and one scoring function. - **Dimensions.** An index expects dense vectors of exactly the configured length, and a query vector must match it as well. Vectors of another length cannot be compared with the stored ones at all, so a "resize" would mean re-embedding every vector, which is what a new index is for. - **Metric.** Each metric has a different scoring function, and the scores mean different things. A stored index scored one way cannot start answering in another metric's terms. ## Choosing the dimensions The dimension count is not a tuning knob; it is a property of the embedding model. Read it off the model and copy it: | Embedding model | Output dimensions | |---|---| | `@cf/baai/bge-small-en-v1.5` | 384 | | `@cf/baai/bge-base-en-v1.5` | 768 | | `@cf/baai/bge-large-en-v1.5` | 1024 | The index limit is **1536 dimensions** per vector, stored at 32-bit precision; a `Float64Array` is converted to float32 when it is stored. The choice of model still has consequences, because Vectorize bills on **queried and stored vector dimensions**: a 1024-dimension model stores and queries more than a 384-dimension one for the same pages. `--preset` removes the copying step. `wrangler vectorize create docs-search --preset=@cf/baai/bge-base-en-v1.5` lets Vectorize set the dimensions and metric for that model. Its accepted values are the three `@cf/baai/bge-*-en-v1.5` models above plus two external models. ## Choosing the metric | Metric | Score range | Closer means | |---|---|---| | `cosine` | -1 to 1 | a score nearer `1` | | `euclidean` | 0 upward | a score nearer `0` | | `dot-product` | any | a lower score (the index reports a negative dot product) | The metric should be the one the model was trained to be compared with; for the BGE text models the Cloudflare examples use `cosine`. A metric picked at random still returns results ordered by its own scoring, which is why a mismatch is easy to miss. The scores themselves are only meaningful relative to each other: a cosine score of 0.85 says two vectors are close, not that two pages are about the same thing. ## When the model has to change Because nothing can be edited, switching to a new model is a migration, not a setting: 1. Create a second index with the new model's dimensions and metric, for example `docs-search-v2`. 2. Re-embed every page with the new model and write it there, in large batches. 3. Create the same metadata indexes on it **before** loading, so filters cover every vector. 4. Point the Worker's `vectorize` binding at the new `index_name` and deploy; queries and pages must switch models in the same release. 5. Delete the old index once nothing reads it. The account limits leave room for this: 50,000 indexes per account on Workers Paid and 100 on the Free plan, so running an old and a new index side by side during a migration is affordable. ## Habits - Read the dimensions from the model card, or use `--preset`, never from memory. - Put the model name in the index name or description, so the binding and the model cannot drift apart unnoticed. - Check the live configuration with `wrangler vectorize info` or the binding's `describe()`, which report the index's dimensions. How each metric's geometry behaves, and how approximate-nearest-neighbour indexes are built, are covered with vector indexes; this question stays with what Vectorize fixes and why.

  • What does a team do when it wants to move its docs search to a 1024-dimension model?
    It cannot edit the existing index, so it creates a second one with `--dimensions=1024` and the model's metric, creates the metadata indexes on it, re-embeds and writes every page in large batches, then points the Worker's `vectorize` binding at the new `index_name` in the same release that switches the query model. The old index is deleted once nothing reads it.
  • How do you read a cosine score of 0.85 from a Vectorize query?
    With `cosine`, scores run from -1 to 1 and nearer 1 means closer, so 0.85 says the vectors are close. It does not prove the pages are about the same thing; that depends on how well the model represents them. Scores are best compared with each other for one query, not against a fixed threshold copied from another model.

  • Believes dimensions can be raised later on an existing index
  • Picks dimensions as a tuning knob rather than from the model
  • Thinks the metric only changes score labels, not the scoring
  • Swaps the query model without rebuilding the index
  • Assumes a euclidean score near 1 means a near-identical match