{"record":{"id":"fe229e1a2c3203bf","repo":"microsoft/semantic-kernel","slug":"distance-function-vector-field-distance-function","errorCode":null,"errorMessage":"Distance function '{vector_field.distance_function}' is not supported by Azure Cosmos DB NoSQL.","messagePattern":"Distance function '(.+?)' is not supported by Azure Cosmos DB NoSQL\\.","errorType":"exception","errorClass":"VectorStoreModelException","httpStatus":null,"severity":"error","filePath":"python/semantic_kernel/connectors/azure_cosmos_db.py","lineNumber":826,"sourceCode":"                    rename[parameter[\"name\"]] = new_name\n                    params.append({\"name\": new_name, \"value\": parameter[\"value\"]})\n                if rename:\n\n                    def _substitute(match: \"re.Match[str]\", mapping: dict[str, str] = rename) -> str:\n                        return mapping[match.group(0)]\n\n                    clause = re.sub(r\"@filter_p\\d+\", _substitute, clause)\n                rendered_clauses.append(clause)\n            where_clauses = (\n                f\"WHERE {rendered_clauses[0]} \"\n                if len(rendered_clauses) == 1\n                else f\"WHERE ({' AND '.join(rendered_clauses)}) \"\n            )\n        vector_field_name = vector_field.storage_name or vector_field.name\n        select_clause = self._build_select_clause(options.include_vectors)\n        params.append({\"name\": \"@vector\", \"value\": vector})\n        if vector_field.distance_function not in DISTANCE_FUNCTION_MAP_NOSQL:\n            raise VectorStoreModelException(\n                f\"Distance function '{vector_field.distance_function}' is not supported by Azure Cosmos DB NoSQL.\"\n            )\n        # Cosmos DB VectorDistance function only accepts 2 parameters: field and vector\n        # Distance function is configured in the vector index, not in the query\n        if search_type == SearchType.VECTOR:\n            distance_clause = f\"VectorDistance(c.{vector_field_name}, @vector)\"\n        elif search_type == SearchType.KEYWORD_HYBRID:\n            # Hybrid search: requires both a vector and keywords\n            params.append({\"name\": \"@keywords\", \"value\": values})\n            text_field = options.additional_property_name\n            if not text_field:\n                raise VectorStoreModelException(\"Hybrid search requires 'keyword_field_name' in options.\")\n            distance_clause = (\n                f\"RRF(VectorDistance(c.{vector_field_name}, @vector), FullTextScore(c.{text_field}, @keywords))\"\n            )\n        else:\n            raise VectorStoreModelException(f\"Search type '{search_type}' is not supported.\")\n        query = (","sourceCodeStart":808,"sourceCodeEnd":844,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/python/semantic_kernel/connectors/azure_cosmos_db.py#L808-L844","documentation":"During NoSQL vector search, the connector validates that the resolved vector field's distance function is in the NoSQL-supported map before building the VectorDistance clause. If the model declares an unsupported metric, the search fails fast with VectorStoreModelException. This mirrors the policy-time check (error 1240) but at query time.","triggerScenarios":"Raised in _inner_search when vector_field.distance_function not in DISTANCE_FUNCTION_MAP_NOSQL. Triggered when the data model's vector field uses a DistanceFunction not supported by NoSQL (anything outside COSINE_SIMILARITY, DOT_PROD, EUCLIDEAN_DISTANCE, DEFAULT).","commonSituations":"Sharing a model definition with a connector that permits a wider metric set. Manually mutating the distance_function after construction. Inconsistent definitions between two deployments.","solutions":["Set the vector field's distance_function to a supported value (cosine, dot product, euclidean, default).","Keep the model consistent with what was used to create the index.","If you need another metric, choose a connector/data model that supports it."],"exampleFix":"// before\nVectorStoreRecordVectorField(name=\"embedding\", dimensions=1536, distance_function=DistanceFunction.MANHATTAN)\n// after\nVectorStoreRecordVectorField(name=\"embedding\", dimensions=1536, distance_function=DistanceFunction.COSINE_SIMILARITY)","handlingStrategy":"validation","validationCode":"from semantic_kernel.connectors.azure_cosmos_db import DISTANCE_FUNCTION_MAP_NOSQL\n\nfor f in definition.vector_fields:\n    if f.distance_function not in DISTANCE_FUNCTION_MAP_NOSQL:\n        raise ValueError(f\"Field '{f.name}' has unsupported distance function {f.distance_function}\")\n","typeGuard":"def is_supported_nosql_distance(fn: DistanceFunction) -> bool:\n    return fn in DISTANCE_FUNCTION_MAP_NOSQL\n","tryCatchPattern":null,"preventionTips":["Validate the model once at startup, not per-query.","Keep model and index definitions aligned after any change.","Unit-test distance-function compatibility per connector."],"tags":["azure-cosmos-db","vector-store","search","data-model"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}