{"record":{"id":"c9601ef10acf3e26","repo":"cocoindex-io/cocoindex","slug":"unsupported-qdrant-distance-metric-distance","errorCode":null,"errorMessage":"Unsupported Qdrant distance metric: {distance}","messagePattern":"Unsupported Qdrant distance metric: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/cocoindex/connectors/qdrant/_target.py","lineNumber":666,"sourceCode":"def _collection_exists(client: QdrantClient, collection_name: str) -> bool:\n    if hasattr(client, \"collection_exists\"):\n        return bool(client.collection_exists(collection_name))\n    try:\n        client.get_collection(collection_name)\n        return True\n    except Exception:\n        return False\n\n\ndef _distance_from_spec(distance: str) -> qdrant_models.Distance:\n    distance_key = distance.lower()\n    if distance_key in (\"cosine\",):\n        return qdrant_models.Distance.COSINE\n    if distance_key in (\"dot\", \"dotproduct\"):\n        return qdrant_models.Distance.DOT\n    if distance_key in (\"euclid\", \"euclidean\", \"l2\"):\n        return qdrant_models.Distance.EUCLID\n    raise ValueError(f\"Unsupported Qdrant distance metric: {distance}\")\n\n\ndef _multivector_comparator(\n    comparator: str,\n) -> qdrant_models.MultiVectorComparator:\n    \"\"\"Convert multivector comparator string to Qdrant enum.\"\"\"\n    if comparator.lower() == \"max_sim\":\n        return qdrant_models.MultiVectorComparator.MAX_SIM\n    raise ValueError(f\"Unsupported multivector comparator: {comparator}\")\n\n\ndef _sparse_modifier_from_spec(\n    modifier: Literal[\"idf\"] | None,\n) -> qdrant_models.Modifier | None:\n    if modifier is None:\n        return None\n    if modifier == \"idf\":\n        return qdrant_models.Modifier.IDF","sourceCodeStart":648,"sourceCodeEnd":684,"githubUrl":"https://github.com/cocoindex-io/cocoindex/blob/e84aa99b3292c5270a4b313b2a7137ad9ce8ab3b/python/cocoindex/connectors/qdrant/_target.py#L648-L684","documentation":"The Qdrant connector maps user-friendly distance strings to qdrant_client Distance enums. Only \"cosine\", \"dot\"/\"dotproduct\", and \"euclid\"/\"euclidean\"/\"l2\" are accepted; any other string in QdrantVectorDef.distance raises this ValueError at collection creation time.","triggerScenarios":"Setting `distance=` on QdrantVectorDef to an unsupported string, e.g. \"Cosine\" (capitalized), \"manhattan\", \"hamming\", or an empty string; the value flows through _vector_params_from_def -> _distance_from_spec when the collection is created.","commonSituations":"Copying distance names from another vector DB (e.g. \"ip\" from Milvus, \"inner_product\"); YAML config with capitalized or hyphenated values like \"Cosine\" or \"cosine-dist\"; typo such as \"cosin\".","solutions":["Change distance to one of: \"cosine\", \"dot\", \"dotproduct\", \"euclid\", \"euclidean\", \"l2\".","Lowercase the value before passing (matching is case-sensitive and exact).","If you need a metric Qdrant does not support via this helper (e.g. manhattan), pick the closest supported one or implement it client-side."],"exampleFix":"// before\nQdrantVectorDef(schema=vec, distance=\"Cosine\")\n// after\nQdrantVectorDef(schema=vec, distance=\"cosine\")","handlingStrategy":"validation","validationCode":"_ALLOWED = {\"cosine\", \"dot\", \"dotproduct\", \"euclid\", \"euclidean\", \"l2\"}\nassert distance in _ALLOWED, f\"distance must be one of {sorted(_ALLOWED)}, got {distance!r}\"","typeGuard":"distance in {\"cosine\", \"dot\", \"dotproduct\", \"euclid\", \"euclidean\", \"l2\"}","tryCatchPattern":"try:\n    schema = await CollectionSchema.create(vectors=QdrantVectorDef(schema=vec, distance=dist))\nexcept ValueError as e:\n    log.error(\"bad distance %r\", dist)\n    raise","preventionTips":["Keep distance strings lowercase in config files and validate at load time.","Centralize the metric string in one constant instead of inlining across call sites.","Map external metric names (e.g. Milvus \"ip\") to Qdrant names in one adapter."],"tags":["qdrant","enum","distance-metric"],"backgroundTag":"invalid-enum-value","analyzedSha":"e84aa99b3292c5270a4b313b2a7137ad9ce8ab3b","analyzedAt":"2026-09-08T15:59:19.997Z","contentChangedAt":"2026-09-08T15:59:19.997Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}