Skip to content

vector-distance-transact-sql.md

Latest commit

 

History

History
137 lines (99 loc) · 5.37 KB

vector-distance-transact-sql.md

File metadata and controls

137 lines (99 loc) · 5.37 KB
title VECTOR_DISTANCE (Transact-SQL)
description VECTOR_DISTANCE calculates the distance between two vectors using a specified distance metric.
author WilliamDAssafMSFT
ms.author wiassaf
ms.reviewer damauri, pookam
ms.date 05/01/2025
ms.service sql
ms.subservice t-sql
ms.topic reference
ms.collection
ce-skilling-ai-copilot
f1_keywords
VECTOR_DISTANCE
VECTOR_DISTANCE_TSQL
helpviewer_keywords
VECTOR_DISTANCE function
vector, distance calculation
dev_langs
TSQL
monikerRange =sql-server-ver17 || =sql-server-linux-ver17 || =azuresqldb-current || =azuresqldb-mi-current || =fabric

VECTOR_DISTANCE (Transact-SQL) (Preview)

[!INCLUDE sqlserver2025-asdb-asmi-fabricsqldb]

Note

This data type is in preview and is subject to change. Make sure to read preview usage terms in Service Level Agreements (SLA) for Online Services.

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

:::image type="icon" source="../../includes/media/topic-link-icon.svg" border="false"::: 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

Metric Description Range Examples
cosine Cosine (angular) distance [0, 2] 0: identical vectors
2: opposing vectors
euclidean Euclidean distance [-∞, +∞] 0: identical vectors
dot Dot product-based indication of distance,
obtained by calculating the negative dot product		 [-∞, +∞] Smaller numbers indicate more similar vectors

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