Vector size and distance are required, immutable-per-vector settings
Qdrant requires the vector size and the distance metric at collection creation time, and they are immutable for the lifetime of that vector. If you omit either, the create call fails immediately with a validation error. This is not an oversight - it reflects a fundamental property of a vector index. The size determines the length of every vector that will be stored, which in turn determines the size of the HNSW graph nodes, the payload storage layout, and the memory footprint of the collection. The distance metric determines how similarity is computed during graph construction and query, and it affects how the index is built (cosine normalizes vectors, dot product does not, Euclidean uses a different ordering). You cannot change either without rebuilding the collection because the stored data and the graph structure encode those choices. Qdrant treats these as schema-level decisions, not optional defaults, and it fails fast rather than guessing.
The mechanism is that a vector index is a data structure specialized for a particular dimension and metric. An HNSW graph built for cosine similarity is not valid for Euclidean distance because the neighbor relationships differ - two points that are nearest under cosine may not be nearest under Euclidean. Similarly, a graph built for 768-dimensional vectors cannot store 1536-dimensional vectors because the node layout would be wrong and the distance computations would be undefined. Qdrant enforces these at the schema level so that the index is always valid and every query has well-defined semantics. This is why the answer to 'why does it fail' is instructive: it tells you that the collection config is a contract between the client and the database, and the client must know and honor that contract. It also explains why a model upgrade requires a new collection and a re-index rather than a config change - you cannot mutate the contract after data has been written against it.
Vector size: required, determines node layout and distance computation shape, immutable per vector.
Distance metric: required, determines neighbor relationships and query semantics, immutable per vector.
Failure mode: immediate validation error at create time, not a silent default and not a runtime failure.
Per-vector: in a multi-vector collection, each named vector has its own size and metric.
Model changes: require a new collection and re-embedding, not a config update.
Distance metric choice: cosine for normalized embeddings, dot for models trained with dot-product loss, Euclidean for coordinate-like data.
Multi-vector and sparse vectors: each have their own requirements and, in some cases, constraints on the distance metric.
The trade-off is flexibility against correctness. Requiring the size and metric up front is less flexible than auto-detecting them, but it guarantees that the index is always semantically valid and that queries have predictable behavior. If Qdrant guessed the size, a misconfigured client could silently corrupt the collection. If it defaulted the metric, an application that needed cosine could end up with Euclidean and produce results that look plausible but are wrong. The common mistake is to treat the distance metric as a minor detail and pick cosine by default for everything. That is often correct, but not always: models trained with dot-product loss expect dot product, and using cosine changes the ranking because it normalizes vectors. The second mistake is to assume you can change the metric later. You cannot - it is a rebuild. The third mistake is to create a collection with one vector size, then upgrade the embedding model and try to upsert the new vectors without noticing the mismatch, which produces a dimension error. Version note: the exact set of required parameters and the supported distance metrics have evolved. Binary quantization imposes additional constraints on the metric, and some multi-vector configurations have restrictions on the comparator. Verify the exact schema for your version before designing a collection.
Version-dependent: the required parameters have been size and distance since early Qdrant versions, but the supported distance metrics and the constraints on them have evolved. Binary quantization, for example, is designed for cosine or dot product with normalized vectors, and using it with Euclidean can be problematic. Multi-vector fields have their own comparator configuration and, in some versions, restrictions on which distance metrics are allowed. Read the schema requirements for your version rather than assuming the same options are available everywhere.
0-2 years experience
2-5 years experience
5-8 years experience
8+ years experience
