{"record":{"id":"fdbe0f3327af93d7","repo":"cocoindex-io/cocoindex","slug":"unsupported-multivector-comparator-comparator","errorCode":null,"errorMessage":"Unsupported multivector comparator: {comparator}","messagePattern":"Unsupported multivector comparator: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/cocoindex/connectors/qdrant/_target.py","lineNumber":675,"sourceCode":"\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\n    raise ValueError(f\"Unsupported Qdrant sparse vector modifier: {modifier}\")\n\n\ndef _vector_params_from_def(\n    vector_def: _ResolvedQdrantVectorDef,\n) -> qdrant_models.VectorParams:\n    \"\"\"Convert a resolved vector definition to Qdrant VectorParams.\"\"\"\n    resolved_schema = vector_def.schema\n    multivector_config = None","sourceCodeStart":657,"sourceCodeEnd":693,"githubUrl":"https://github.com/cocoindex-io/cocoindex/blob/e84aa99b3292c5270a4b313b2a7137ad9ce8ab3b/python/cocoindex/connectors/qdrant/_target.py#L657-L693","documentation":"For Qdrant multivectors, the connector accepts only the \"max_sim\" comparator (matched case-insensitively), mapping it to qdrant_models.MultiVectorComparator.MAX_SIM. Any other comparator string raises this ValueError when the vector params are built.","triggerScenarios":"Setting multivector_comparator on QdrantVectorDef to anything other than \"max_sim\" (e.g. \"maxsim\", \"dot\", \"euclid\") while using a multivector VectorSchema; triggered via _vector_params_from_def during collection creation.","commonSituations":"Guessing comparator names because Qdrant's API only has MAX_SIM; typos like \"max-sim\" (with hyphen) — note hyphen is NOT accepted, only \"max_sim\" case-insensitively; copying comparator values from other libraries.","solutions":["Set multivector_comparator to \"max_sim\" (case-insensitive: \"MAX_SIM\" also works).","If you don't need multivector behavior, omit multivector_comparator and use a plain VectorSchema.","Check for hyphen vs underscore: use \"max_sim\", not \"max-sim\"."],"exampleFix":"// before\nQdrantVectorDef(schema=mv_schema, distance=\"cosine\", multivector_comparator=\"max-sim\")\n// after\nQdrantVectorDef(schema=mv_schema, distance=\"cosine\", multivector_comparator=\"max_sim\")","handlingStrategy":"validation","validationCode":"assert comparator.lower() == \"max_sim\", f\"only 'max_sim' supported, got {comparator!r}\"","typeGuard":"isinstance(comparator, str) and comparator.lower() == \"max_sim\"","tryCatchPattern":"try:\n    schema = await CollectionSchema.create(vectors=def_)\nexcept ValueError as e:\n    raise ConfigError(f\"multivector comparator invalid: {e}\") from None","preventionTips":["Use the literal \"max_sim\" — Qdrant only offers MAX_SIM today.","Use underscore, not hyphen; case doesn't matter but spelling does.","Omit multivector_comparator entirely unless using a multivector schema."],"tags":["qdrant","multivector","enum"],"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-14T11:17:12.474Z"}