VectorDistance (NoSQL query)
APPLIES TO:
NoSQL
Returns the similarity score between two specified vectors.
Note
For more information, see Geospatial and GeoJSON location data.
Syntax
VECTORDISTANCE(<vector_expr1>, <vector_expr2>, [<bool_expr>], [<obj_expr>])
Arguments
Description | |
---|---|
spatial_expr_1 |
An array of float32 or smaller. |
spatial_expr_2 |
An array of float32 or smaller. |
bool_expr |
A boolean specifying how the computed value is used in an ORDER BY expression. If true , then brute force is used. A value of false leverages any index defined on the vector property, if it exists. Default value is false . |
obj_expr |
A JSON formatted object literal used to specify options for the vector distance calculation. Valid items include distanceFunction and dataType . |
distanceFunction |
The metric used to compute distance/similarity. |
dataType |
The data type of the vectors. float32 , float16 , int8 , uint8 values. Default value is float32 . |
Supported metrics for distanceFunction
are:
- cosine, which has values from -1 (least similar) to +1 (most similar).
- dotproduct, which has values from -inf (least similar) to +inf (most similar).
- euclidean, which has values from 0 (most similar) to +inf (least similar).
Return types
Returns a numeric expression that enumerates the similarity score between two expressions.
Examples
With required arguments
SELECT c.name, VectorDistance(c.vector1, c.vector2) AS SimilarityScore
FROM c
ORDER BY VectorDistance(c.vector1, c.vector2)
With optional arguments
SELECT c.name, VectorDistance(c.vector1, c.vector2, true, {'distanceFunction':'cosine', 'dataType':'float32',}) AS SimilarityScore
FROM c
ORDER BY VectorDistance(c.vector1, c.vector2)
Remarks
- This function requires enrollment in the Azure Cosmos DB NoSQL Vector Search preview feature.
- This function benefits from a vector index
- if
false
is given as the optionalbool_expr
, then the vector index defined on the path is used, if one exists. If no index is defined on the vector path, then this reverts to full scan and incurs higher RU charges and higher latency than if using a vector index. - When
VectorDistance
is used in anORDER BY
clause, no direction can be specified for theORDER BY
, as the results are always sorted in order of most similar (first) to least similar (last) based on the similarity metric used. If a direction such asASC
orDESC
is specified, an error occurs. - The result is expressed as a similarity score.
Related content
Feedback
https://aka.ms/ContentUserFeedback.
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see:Submit and view feedback for