{"record":{"id":"b57be5e320b0ce62","repo":"microsoft/semantic-kernel","slug":"field-distance-function-not-supported-in-azure-a","errorCode":null,"errorMessage":"{field.distance_function} not supported in Azure AI Search.","messagePattern":"(.+?) not supported in Azure AI Search\\.","errorType":"exception","errorClass":"VectorStoreOperationException","httpStatus":null,"severity":"error","filePath":"python/semantic_kernel/connectors/azure_ai_search.py","lineNumber":263,"sourceCode":"                )\n            )\n        elif field.field_type == FieldTypes.KEY:\n            fields.append(\n                SimpleField(\n                    name=field.storage_name or field.name,\n                    type=\"Edm.String\",  # hardcoded, only allowed type for key\n                    key=True,\n                    filterable=True,\n                    searchable=True,\n                )\n            )\n        elif field.field_type == FieldTypes.VECTOR:\n            if not field.type_:\n                logger.debug(f\"Field {field.name} has not specified type, defaulting to Collection(Edm.Single).\")\n            if field.index_kind not in INDEX_ALGORITHM_MAP:\n                raise VectorStoreOperationException(f\"{field.index_kind} not supported in Azure AI Search.\")\n            if field.distance_function not in DISTANCE_FUNCTION_MAP:\n                raise VectorStoreOperationException(f\"{field.distance_function} not supported in Azure AI Search.\")\n\n            profile_name = f\"{field.storage_name or field.name}_profile\"\n            algo_name = f\"{field.storage_name or field.name}_algorithm\"\n            fields.append(\n                SearchField(\n                    name=field.storage_name or field.name,\n                    type=TYPE_MAP_VECTOR[field.type_ or \"default\"],\n                    searchable=True,\n                    vector_search_dimensions=field.dimensions,\n                    vector_search_profile_name=profile_name,\n                    hidden=False,\n                )\n            )\n            search_profiles.append(\n                VectorSearchProfile(\n                    name=profile_name,\n                    algorithm_configuration_name=algo_name,\n                )","sourceCodeStart":245,"sourceCodeEnd":281,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/python/semantic_kernel/connectors/azure_ai_search.py#L245-L281","documentation":"Raised in _definition_to_azure_ai_search_index when a VECTOR field's distance_function is not a key in DISTANCE_FUNCTION_MAP. Azure AI Search supports COSINE_DISTANCE, DOT_PROD, EUCLIDEAN_DISTANCE, HAMMING, and DEFAULT. Other functions in the DistanceFunction enum (COSINE_SIMILARITY, EUCLIDEAN_SQUARED_DISTANCE, MANHATTAN) are not accepted by Azure AI Search, so index creation fails with a VectorStoreOperationException.","triggerScenarios":"Calling ensure_collection_exists() with a vector field whose distance_function is DistanceFunction.COSINE_SIMILARITY, EUCLIDEAN_SQUARED_DISTANCE, or MANHATTAN. Fires at index-build time, after the index_kind check.","commonSituations":"Using COSINE_SIMILARITY (a common choice in other stores) instead of COSINE_DISTANCE; copying a definition from a store that supports squared-Euclidean or Manhattan metrics.","solutions":["Switch the distance_function to DistanceFunction.COSINE_DISTANCE (Azure AI Search's cosine option), DOT_PROD, EUCLIDEAN_DISTANCE, or DEFAULT.","Note the semantic flip: COSINE_SIMILARITY is 'higher is better' while COSINE_DISTANCE is 'lower is closer' — adjust any score thresholds accordingly.","Validate vector field distance functions against DISTANCE_FUNCTION_MAP before creating the collection."],"exampleFix":"// before\nfield(type_='float', name='embedding', distance_function=DistanceFunction.COSINE_SIMILARITY)\n\n// after\nfield(type_='float', name='embedding', distance_function=DistanceFunction.COSINE_DISTANCE)","handlingStrategy":"validation","validationCode":"from semantic_kernel.connectors.azure_ai_search import DISTANCE_FUNCTION_MAP\n\ndef validate_vector_distance_functions(definition) -> list[str]:\n    bad = []\n    for f in definition.fields:\n        if f.field_type.value == \"vector\" and f.distance_function not in DISTANCE_FUNCTION_MAP:\n            bad.append(f\"{f.name}: {f.distance_function}\")\n    return bad\n\nassert not validate_vector_distance_functions(definition)","typeGuard":null,"tryCatchPattern":"from semantic_kernel.exceptions import VectorStoreOperationException\ntry:\n    await collection.ensure_collection_exists()\nexcept VectorStoreOperationException as e:\n    if \"not supported in Azure AI Search\" in str(e) and \"distance\" in str(e).lower():\n        # switch to COSINE_DISTANCE / DOT_PROD / EUCLIDEAN_DISTANCE / HAMMING\n        ...\n    raise","preventionTips":["Use DistanceFunction.COSINE_DISTANCE (not COSINE_SIMILARITY) for Azure AI Search.","Remember score direction flips between similarity and distance metrics; adjust thresholds.","Validate distance_function against DISTANCE_FUNCTION_MAP per store in a test."],"tags":["schema","vector-index","azure-ai-search","data-model"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}