What must an Elasticsearch dense_vector mapping declare before a knn search can use it?

## What a dense_vector field is `dense_vector` is the Elasticsearch field type that holds a fixed-length array of numbers — typically the output of an embedding model, where semantically similar text lands close together in the vector space. Unlike `text` or `keyword`, it is not analysed into terms; it is stored as a numeric array, and optionally indexed into a graph structure that supports approximate nearest-neighbour (ANN) lookup. ## dims — the length contract Every vector in the field must have the same number of dimensions. In older versions you declared `dims` explicitly; in recent 8.x you may omit it and Elasticsearch fixes it from the first document indexed. Either way it becomes immutable for that field. Indexing a 768-dimension vector into a field fixed at 384 is rejected. Because embedding models have a fixed output width, switching models almost always means a new field and a reindex. ## index — whether ANN is available `index: true` (the default in recent 8.x) tells Elasticsearch to build an HNSW graph over the field's vectors, which is what the `knn` search option traverses. With `index: false` the vectors are stored but there is no graph: you can still read them and score them with `script_score` vector functions such as `cosineSimilarity` or `dotProduct`, but that is an exhaustive scan over every document the surrounding query matches. Exhaustive scoring is exact and perfectly reasonable for a few thousand candidates; it is hopeless for millions. ## similarity — the distance function The `similarity` parameter selects how closeness is measured and how the raw distance is turned into a positive `_score`: - **cosine** — angle between vectors. Elasticsearch normalizes vectors to unit length at index time, so internally it degenerates to a dot product. Score is `(1 + cosine) / 2`, so it lands in [0, 1]. - **dot_product** — raw inner product, and Elasticsearch requires the indexed and query vectors to already be unit length; a vector with a different magnitude is rejected at index time. If your model already emits normalized vectors, this is the cheapest choice. - **l2_norm** — Euclidean distance, turned into a score that decreases as distance grows. - **max_inner_product** — inner product without the unit-length requirement, for models where magnitude carries meaning. The metric must match the model. Embeddings trained under cosine similarity ranked with `l2_norm` will not be catastrophically wrong, but they will be subtly worse, and that is the kind of relevance bug nobody notices for months. ## element_type and index_options `element_type` defaults to `float` (32-bit). `byte` stores each dimension in one signed byte, and `bit` stores one bit per dimension for models that emit binary codes — both shrink the field dramatically at some cost in fidelity. `index_options` picks the graph flavour and its build parameters: `hnsw` for raw float graphs, `int8_hnsw` / `int4_hnsw` / `bbq_hnsw` for quantized graphs, and `flat` variants for brute-force-only storage. Recent 8.x defaults float vectors to a scalar-quantized `int8_hnsw` graph rather than raw `hnsw`, because the memory saving usually outweighs the small recall loss. `m` and `ef_construction` inside `index_options` control graph connectivity and build effort. ## What you cannot change later Dimensions, similarity and element type are baked into the field. There is no in-place mapping update for them; the fix is a new field (or a new index) plus a reindex, usually behind an alias so search traffic never sees the switch. This is why the mapping conversation happens before the first bulk load, not after. ## Common failure modes A `knn` search that errors with a message about the field not being indexed for search means `index: false`. A search that returns nothing sensible often means the query vector came from a different model than the indexed ones — same dimension count, completely different space, and nothing in Elasticsearch can detect that for you. An index-time rejection about vector magnitude means `dot_product` with unnormalized vectors. And a field that quietly eats a lot of memory usually means raw `hnsw` on float32 vectors where a quantized graph would have done.