VECTOR_DISTANCE (Transact-SQL) (Preview)

Applies to: SQL Server 2025 (17.x) Preview Azure SQL Database Azure SQL Managed Instance SQL database in Microsoft Fabric

Calculates the distance between two vectors using a specified distance metric. Vector distance is always exact and doesn't use any vector index, even if available. In order to use a vector index and thus perform an approximate vector search, you must use the VECTOR_SEARCH function. To learn more about how vector indexing and vector search works, and the differences between exact and approximate search, refer to Vectors in the SQL Database Engine.

Syntax

Transact-SQL syntax conventions

VECTOR_DISTANCE ( distance_metric, vector1, vector2 )

Arguments

distance_metric

A string with the name of the distance metric to use to calculate the distance between the two given vectors. The following distance metrics are supported:

• cosine - Cosine distance
• euclidean - Euclidean distance
• dot - (Negative) Dot product

vector1

An expression that evaluates to vector data type.

vector2

An expression that evaluates to vector data type.

Distance Metrics

Return value

The function returns a scalar float value that represents the distance between the two vectors using the specified distance metric.

An error is returned if distance_metric isn't a valid metric and if the provided vectors are not of the vector data type.

Examples

Details of the database used in the sample can be found here: Download and import the Wikipedia Article with Vector Embeddings.

Examples assume the existence of a table named wikipedia_articles with a column title_vector of type vector that stores title's embeddings of Wikipedia articles. title_vector is assumed to be an embedding generated with an embedding model like text-embedding-ada-002 or text-embedding-3-small , which returns vectors with 1,536 dimensions.

For more examples, including end-to-end solutions, go to the Azure SQL Database Vector Search Samples GitHub repo.

Example 1

The following example creates a vector with three dimensions from a string with a JSON array.

DECLARE @v1 VECTOR(2) = '[1,1]';
DECLARE @v2 VECTOR(2) = '[-1,-1]';

SELECT 
    VECTOR_DISTANCE('euclidean', @v1, @v2) AS euclidean,
    VECTOR_DISTANCE('cosine', @v1, @v2) AS cosine,
    VECTOR_DISTANCE('dot', @v1, @v2) AS negative_dot_product;

Example 2

The following example returns the top 10 most similar articles to a given article, based on the cosine distance between their title vectors.

DECLARE @v AS VECTOR(1536);
SELECT @v = title_vector FROM [dbo].[wikipedia_articles] WHERE title = 'Alan Turing';

SELECT TOP(10) 
  id, 
  title, 
  VECTOR_DISTANCE('cosine', @v, title_vector) AS distance 
FROM 
  [dbo].[wikipedia_articles] 
ORDER BY
  distance

Example 3

The following example returns all the similar articles to a given article, based on the cosine distance between their title vectors, selecting only those with a distance less than 0.3.

DECLARE @v AS VECTOR(1536);
SELECT @v = title_vector FROM [dbo].[wikipedia_articles] WHERE title = 'Alan Turing';

SELECT  
  id, 
  title,
  VECTOR_DISTANCE('cosine', @v, title_vector) AS distance
FROM 
  [dbo].[wikipedia_articles] 
WHERE
  VECTOR_DISTANCE('cosine', @v, title_vector) < 0.3
ORDER BY
  distance

Related content

• Overview of vectors in the SQL Database Engine
• Azure SQL Database Vector Search Samples
• Vector data type