# Dimension and metric: get them right at creation, they are frozen
## The rule
`dimension` must equal the number of floats your embedding model outputs. `metric` must suit how you compare them:
- `cosine`: normalized embeddings (most text models, e.g. OpenAI text-embedding-3). The common default.
- `dotproduct`: unnormalized embeddings, or sparse-only indexes.
- `euclidean`: when you genuinely need L2 distance.
## Why agents get this wrong
The failure mode is creating the index first and choosing the embedding model later, or swapping models mid-project. text-embedding-3-small outputs 1536 dims; text-embedding-3-large outputs 3072; many open models output 768 or 1024. Upserting 768-dim vectors into a 1536-dim index fails every record with a dimension-mismatch error. There is no alter-index; you delete and recreate, then re-upsert everything.
## Checklist before create_index
1. Decide the embedding model first. Print `len(embedding)` once and use that number.
2. Pick the metric from the list above, not from habit. If your vectors are L2-normalized, cosine and dotproduct agree; if they are not, they do not.
3. If you need sparse vectors (keyword signals), set `vector_type` appropriately at creation too.
4. Name the index after the model and dimension (e.g. `docs-ada-1536`) so a future agent can see the pairing without reading code.
## If you already messed it up
Do not try to "fix" the vectors to fit (truncating or padding silently destroys recall). Create a new index with the right dimension, re-embed, re-upsert. For large indexes use the bulk import path rather than re-upserting one by one.