# EUCLIDEAN\_DISTANCE

The `EUCLIDEAN_DISTANCE` function returns the euclidean distance between two vector values. `EUCLIDEAN_DISTANCE` takes as input two vectors and returns a numeric value.

A common use of `EUCLIDEAN_DISTANCE` is to calculate the similarity between vectors (vector similarity), which is used in semantic text search, generative AI, searches of images and audio files, and other applications. A typical query using `EUCLIDEAN_DISTANCE` is to find a set of vectors that most closely match a query vector.

SingleStore supports a native vector data type and indexed approximate-nearest-neighbor (ANN) search that provides high-performance vector search and easier building of vector-based applications.

See [Vector Type](https://docs.singlestore.com/db/v9.1/reference/sql-reference/data-types/vector-type.md), [Vector Indexing](https://docs.singlestore.com/db/v9.1/reference/sql-reference/vector-functions/vector-indexing.md), and [Working with Vector Data](https://docs.singlestore.com/db/v9.1/developer-resources/functional-extensions/working-with-vector-data.md) for more information about using vectors in SingleStore.

## Syntax

```text
vector_expression <-> vector_expression

EUCLIDEAN_DISTANCE(vector_expression, vector_expression)
```

## Arguments

* `vector_expression`: An expression that evaluates to a vector. Vectors can be stored in SingleStore using the native `VECTOR` type ([Vector Type](https://docs.singlestore.com/db/v9.1/reference/sql-reference/data-types/vector-type.md)) or the `BLOB` type ([Binary String Types](https://docs.singlestore.com/db/v9.1/reference/sql-reference/data-types/binary-string-types.md)). SingleStore recommends using the `VECTOR` type when possible.
* JSON strings are allowed as `vector_expression`s when the other argument is of type `VECTOR`.

## Remarks

* If both arguments are of type `VECTOR`, those arguments must have the same element types and the same number of elements.&#x20;
* If one argument is a `VECTOR`, the other argument (which may be a JSON string or a `BLOB`) will be converted to the type of the `VECTOR` argument.

  * It will cause an error if the JSON string has a different number of elements than the `VECTOR` argument.
  * It will cause an error if the length of the `BLOB` is such that the `BLOB` cannot be converted to the type of the `VECTOR`. Note that there is no type checking in this conversion, so ensure that the `BLOB`s were encoded with the same type as the `VECTOR` argument.
* If both arguments are `BLOB`s, both arguments will be treated as vectors with 32-bit floating-point numbers. It will cause an error if the arguments are different lengths.

* If the result is infinity, negative infinity, or not a number (NaN), `NULL` will be returned instead.
* See [Using Suffixes for Other Element Types with BLOBs](https://docs.singlestore.com/#UUID-317e1af0-af41-98cb-f6a1-31cedf998e40.md) for information on using `EUCLIDEAN_DISTANCE` with vectors with element types other than 32-bit floating-point numbers.
* The default element type for vector storage and processing is 32-bit floating-point (`F32`). The` EUCLIDEAN_DISTANCE` function assumes the vector inputs are encoded as 32-bit floating-point numbers and returns a `DOUBLE`.
* `EUCLIDEAN_DISTANCE(v1, v2)` is computationally equivalent to `SQRT(DOT_PRODUCT(VECTOR_SUB(v1, v2), VECTOR_SUB(v1, v2)))`. However, the `EUCLIDEAN_DISTANCE()` function is more efficient than the latter.

## Output Format for Examples

Vectors can be output in JSON or binary format. Use JSON format for examples and for output readability. For production, use the default binary for efficiency.

Use the following command to output vectors in JSON format.

```sql
SET vector_type_project_format = JSON;
```

Use the following command to set the output format back to binary.

```sql
SET vector_type_project_format = BINARY;
```

## Using EUCLIDEAN\_DISTANCE with the VECTOR Data Type

The following example shows the use of  `EUCLIDEAN_DISTANCE()` to calculate the similarity between a query vector and a set of vectors in a table.

Create a table with a column of type `VECTOR`, insert data into the table, and then verify the contents of the table.

```sql
CREATE TABLE vectors (id int, vec VECTOR(4) not null);

INSERT INTO vectors VALUES (1, '[0.45, 0.55, 0.495, 0.5]');
INSERT INTO vectors VALUES (2, '[0.1, 0.8, 0.2, 0.555]');
INSERT INTO vectors VALUES (3, '[-0.5, -0.03, -0.1, 0.86]');
INSERT INTO vectors VALUES (4, '[0.5, 0.3, 0.807, 0.1]');
```

```sql

SET vector_type_project_format = JSON;  /* to make vector output readable */

SELECT id, vec
FROM vectors
ORDER BY id;


```

```output

+------+---------------------------------------------------+
| id   | vec                                               |
+------+---------------------------------------------------+
|    1 | [0.449999988,0.550000012,0.495000005,0.5]         |
|    2 | [0.100000001,0.800000012,0.200000003,0.555000007] |
|    3 | [-0.5,-0.0299999993,-0.100000001,0.860000014]     |
|    4 | [0.5,0.300000012,0.806999981,0.100000001]         |
+------+---------------------------------------------------+
```

Notice that the results of the `SELECT` do not exactly match the values in the `INSERT`. This is because elements in the `VECTOR` data type are stored as floating-point numbers and the values in the `INSERT` statement are not perfectly representable in floating-point.

After you've created a table and inserted data, set up a query vector. The queries below will evaluate vector similarity between the vectors in the `vectors` table and `@query_vec`.

This query finds the similarities between vectors and `@query_vec` using the `EUCLIDEAN_DISTANCE` infix operator `<->`. The `ORDER BY` clause is included so the order of your results match the results shown below.

Lower values of `EUCLIDEAN_DISTANCE` indicate higher similarity. The value of `EUCLIDEAN_DISTANCE` is always greater than `0`.&#x20;

The `@query_vec` variable is cast to a `VECTOR` to ensure that `@query_vec` is a valid `VECTOR` and to improve performance.

```sql
SET @query_vec = ('[0.44, 0.554, 0.34, 0.62]'):>VECTOR(4);

SELECT vec <-> @query_vec AS score
FROM vectors
ORDER BY score ASC;


```

```output

+---------------------+
| score               |
+---------------------+
| 0.19631861943383927 |
| 0.44714763700937277 |
|  0.7460596366393402 |
|  1.2148481657187131 |
+---------------------+
```

## Using EUCLIDEAN\_DISTANCE (<->) in Filters, Joins, and Ordering

`EUCLIDEAN_DISTANCE` can appear wherever a floating-point expression can be used in a query, including in filters, ordering, joins, and cross products.

The [DOT\_PRODUCT](https://docs.singlestore.com/db/v9.1/reference/sql-reference/vector-functions/dot-product.md) page shows examples of using `DOT_PRODUCT` in various ways in SQL queries. `EUCLIDEAN_DISTANCE` can be used similarly. Remember that sort order is `ASC` when using `EUCLIDEAN_DISTANCE` and `DESC` with `DOT_PRODUCT`.

Below is one example of using `EUCLIDEAN_DISTANCE` (`<->`) in a join query. Both arguments can be table fields or derived from table fields.

Use the `vectors` table and the `@query_vec` created above, in addition to the new table created below, when running the following query.

```sql
CREATE TABLE vectors_2 (id_2 int, vec_2 VECTOR(4) not null);

INSERT INTO vectors_2 VALUES (5, '[0.4, 0.49, 0.16, 0.555]');
INSERT INTO vectors_2 VALUES (6, '[-0.01, -0.1, -0.2, 0.975]');
```

```sql
SELECT v1.id, v2.id_2, v1.vec <-> v2.vec_2 AS score
FROM vectors v1, vectors_2 v2
WHERE v1.vec <-> v2.vec_2 < 0.7
ORDER BY score ASC;


```

```output

+------+------+---------------------+
| id   | id_2 | score               |
+------+------+---------------------+
|    1 |    5 | 0.34835327652980475 |
|    2 |    5 |  0.4332435843558954 |
|    3 |    6 |  0.5179044162849211 |
+------+------+---------------------+
```

## Automatic Type Conversions

As described in [Remarks](https://docs.singlestore.com/#section-idm4651133790457634210783096502.md), in some cases, SingleStore will do automatic type conversions between JSON strings, `BLOB`s, and `VECTOR`s. Three examples of those automatic type conversions are provided below.

> **📝 Note**: The examples below use the dot product infix operator `<->`; all the functionality shown also works with the `EUCLIDEAN_DISTANCE` function.

## Example 1 - VECTOR(4, F32) <-> JSON

Use the `vectors` table created above. Recall this table has an attribute of type `VECTOR` that holds vectors of length 4 with element type of 32-bit floating-point (`F32`).

The following SQL searches for vectors that are similar to the vector `'[0.44, 0.554, 0.34, 0.62]'`. The database will detect that the left-hand argument to `<->` is a vector of length 4 with element-type 32-bit floating-point number and will convert the JSON string (the right-hand argument) to that vector type.

```sql

SET vector_type_project_format = JSON;  /* to make vector output readable */

SELECT vec, vec <-> '[0.44, 0.554, 0.34, 0.62]' AS score
FROM vectors
ORDER BY score ASC;


```

```output

+---------------------------------------------------+---------------------+
| vec                                               | score               |
+---------------------------------------------------+---------------------+
| [0.449999988,0.550000012,0.495000005,0.5]         | 0.19631861943383927 |
| [0.100000001,0.800000012,0.200000003,0.555000007] | 0.44714763700937277 |
| [0.5,0.300000012,0.806999981,0.100000001]         |  0.7460596366393402 |
| [-0.5,-0.0299999993,-0.100000001,0.860000014]     |  1.2148481657187131 |
+---------------------------------------------------+---------------------+

```

> **📝 Note**: In the above example, the JSON string is directly included in the `SELECT` clause as a constant. Including the JSON directly in the `SELECT` clause is fine for queries that are run once. However, if this is a query that will be run multiple times, SingleStore recommends casting the JSON string to a `VECTOR` and use that `VECTOR` in the query as shown in Example 3 below.

## Example 2: Vector(3,I16)  <-> JSON STRING

Create a table of vectors of length 3 and element type 16-bit integer (`I16`) and insert data into that table.

```sql
CREATE TABLE vectors_i16(id INT, vec VECTOR(3, I16));

INSERT INTO vectors_i16 VALUES(1, '[1, 2, 3]');
INSERT INTO vectors_i16 VALUES(2, '[4, 5, 6]');
INSERT INTO vectors_i16 VALUES(3, '[1, 4, 8]');
```

The following SQL calculates the dot product between the `@query_vec` and the vectors in the `vectors_i16` table. The database will detect that the left-hand argument to `<->` in the `SELECT` clause is a vector of length 3 with element-type 16-bit integer and will convert the JSON string (the right-hand argument) to that vector type.

```sql
SELECT id, '[3, 2, 1]' <-> vectors_i16.vec AS score
FROM vectors_i16
ORDER BY score ASC;


```

```output

+------+--------------------+
| id   | score              |
+------+--------------------+
|    1 | 2.8284271247461903 |
|    2 |  5.916079783099616 |
|    3 |   7.54983443527075 |
+------+--------------------+
```

## Example 3 - VECTOR(4, F32) <-> BLOB

Create a table with a BLOB column type to store the vectors and use the JSON\_ARRAY\_PACK() built-in function to easily insert properly formatted vectors.

```sql
CREATE TABLE vectors_b (id int, vec BLOB not null);

INSERT INTO vectors_b VALUES (1, JSON_ARRAY_PACK('[0.1, 0.8, 0.2, 0.555]'));
INSERT INTO vectors_b VALUES (2, JSON_ARRAY_PACK('[0.45, 0.55, 0.495, 0.5]'));
```

The following SQL calculates the dot product between the `@query_vec` and the vectors stored as BLOBs in the vectors\_b table. The database will detect that the left-hand argument to `<->` in the `SELECT` clause is a vector of length 4 with element type 32-bit floating-point number and will convert the `BLOB` (the right-hand argument) to that vector type.

```sql
SET @query_vec = '[0.44, 0.554, 0.34, 0.62]':>VECTOR(4);

SELECT id, @query_vec <*> vectors_b.vec AS score
FROM vectors_b
ORDER BY score DESC;


```

```output

+------+--------------------+
| id   | score              |
+------+--------------------+
|    2 | 0.9810000061988831 |
|    1 | 0.8993000388145447 |
+------+--------------------+
```

> **❗ Important**: When using vectors stored as `BLOB`s it is important to ensure that the `BLOB`s store vectors of the same length and element type as the query vector with which you are calculating the dot product. The system verifies that the length of the `BLOB` matches the length expected for the `VECTOR` based on the number of elements and element type of the `VECTOR`; however, the system cannot check that the element types used in the `BLOB` and the `VECTOR` are the same.

## Using EUCLIDEAN\_DISTANCE with Vectors as BLOBs

The following example shows the use of  `EUCLIDEAN_DISTANCE()` to calculate the similarity between a query vector and a set of vectors in a table with the vectors stored as BLOBs.

Create a table with a column of type `BLOB` to store the vectors. The second column in this table, with column name `vec` and type `BLOB`, will store the vectors. This example demonstrates storing vector data using `BLOB`s, hence the column of type `BLOB` named `vec`.

Then insert data using the `JSON_ARRAY_PACK()` built-in function to easily insert properly formatted vectors.

```sql
CREATE TABLE vectors_b (id int, vec BLOB not null);

INSERT INTO vectors_b VALUES (1, JSON_ARRAY_PACK('[0.1, 0.8, 0.2, 0.555]'));
INSERT INTO vectors_b VALUES (2, JSON_ARRAY_PACK('[0.45, 0.55, 0.495, 0.5]'));
```

To demonstrate the contents of the table, use the `JSON_ARRAY_UNPACK()` function to return the table elements in JSON format:

```sql
SELECT JSON_ARRAY_UNPACK(vec) FROM vectors_b;


```

```output

+---------------------------------------------------+
| JSON_ARRAY_UNPACK(vec)                            |
+---------------------------------------------------+
| [0.449999988,0.550000012,0.495000005,0.5]         |
| [0.100000001,0.800000012,0.200000003,0.555000007] |
+---------------------------------------------------+
```

You can also use the `HEX()` built-in function to return a printable form of the binary data:

```sql
SELECT HEX(vec) FROM vectors_b;


```

```output

+----------------------------------+
| HEX(vec)                         |
+----------------------------------+
| 6666E63ECDCC0C3FA470FD3E0000003F |
| CDCCCC3DCDCC4C3FCDCC4C3E7B140E3F |
+----------------------------------+
```

Query the table using the `EUCLIDEAN_DISTANCE()` function in a `SELECT` statement.

The SQL below sets up query vector (`@query_vec`) and then calculates the `EUCLIDEAN_DISTANCE` of the query vector and the vectors in the `vectors_b` table.

```sql
SET @query_vec = JSON_ARRAY_PACK('[0.44, 0.554, 0.34, 0.62]');

SELECT EUCLIDEAN_DISTANCE(vec, @query_vec) AS score 
FROM vectors_b;


```

```output

+---------------------+
| score               |
+---------------------+
| 0.19631861943383927 |
| 0.44714763700937277 |
+---------------------+
```

## EUCLIDEAN\_DISTANCE() with JSON\_ARRAY\_PACK()

The `JSON_ARRAY_PACK()` function makes it easier to input properly-formatted vectors. `JSON_ARRAY_PACK()` should be used when loading vectors into tables as is shown in the example below. That is, vectors should be formatted with `JSON_ARRAY_PACK()` at the time they are loaded into a table so that the data stored in the `BLOB` attribute in the table is in packed binary format. SingleStore does not recommend storing vectors as JSON strings in tables, doing so will have a negative performance impact.

`JSON_ARRAY_PACK()` should not normally be used as an argument to the `EUCLIDEAN_DISTANCE` function except when `JSON_ARRAY_PACK()` is being used to build a constant vector value as is shown in the query below.

```sql
SELECT EUCLIDEAN_DISTANCE(JSON_ARRAY_PACK('[0.44, 0.554, 0.34, 0.62]'), vec) AS score
FROM vectors_b
ORDER BY score ASC;


```

```output

+---------------------+
| score               |
+---------------------+
| 0.19631861943383927 |
| 0.44714763700937277 |
+---------------------+
```

> **📝 Note**: SingleStore does not recommend using the `EUCLIDEAN_DISTANCE` infix operator (`<->`) with vectors stored as `BLOB`s. When used with `BLOB` data, the infix operator (`<->`) will interpret vector elements as 32-bit floating-point numbers.

## Using Suffixes for Other Element Types with BLOBs

The default element type for vector storage and processing is 32-bit floating point (`F32`). However, other element types are supported.

You can specify the datatype of the vector elements to be used in the operation by adding a suffix to the function. All operations are done using the specified datatype. Omitting the suffix from the function is equivalent to suffixing it with `_F32`.

When using a suffix, the return type will be the type specified by the suffix.

> **📝 Note**: Vector functions with suffixes do not work with the `VECTOR` type. However, vector functions without suffixes are overloaded to work on `VECTOR` values of any element type.

The following table lists the suffixes and their data type.

| Suffix | Data Type                                           |
| ------ | --------------------------------------------------- |
| `_I8`  | 8-bit signed integer                                |
| `_I16` | 16-bit signed integer                               |
| `_I32` | 32-bit signed integer                               |
| `_I64` | 64-bit signed integer                               |
| `_F32` | 32-bit floating-point number (IEEE standard format) |
| `_F64` | 64-bit floating-point number (IEEE standard format) |

## EUCLIDEAN\_DISTANCE on BLOBs with 16-bit Integers

Below is an example of using `JSON_ARRAY_PACK` and `EUCLIDEAN_DISTANCE` with 16-bit signed integers.

```sql
CREATE TABLE vectors_b_i (id int, vec BLOB not null);

INSERT INTO vectors_b_i VALUES (1, JSON_ARRAY_PACK_I16('[1, 3, 2, 5]'));
INSERT INTO vectors_b_i VALUES(2, JSON_ARRAY_PACK_I16('[23, 4, 1, 8]'));
```

```sql
SET @qv = JSON_ARRAY_PACK_I16('[1, 2, 3, 4]');

SELECT EUCLIDEAN_DISTANCE_I16(@qv, vec) as EuclidDist
FROM vectors_b_i;


```

```output

+--------------------+
| EuclidDist         |
+--------------------+
| 22.538855339169288 |
| 1.7320508075688772 |
+--------------------+

```

The result is an integer as indicated by the `_I16` suffix.

When using suffixed versions of `EUCLIDEAN_DISTANCE`, the return type will be the type of the suffix.

> **📝 Note**: Be sure that the suffixes you use to pack the vector data match the suffixes you use to unpack the data and the suffixes you use on functions to process that data.

## Formatting Binary Vector Data for BLOBs

When using the `BLOB` type for vector operations, vector data can be formatted using `JSON_ARRAY_PACK`. If your vector data is already in a packed binary format, you can load that data into the `BLOB`s. The data must be encoded as a `BLOB` containing packed numbers in little-endian byte order. Vectors stored as `BLOB`s can be of any length; however, the input blob length must be divisible by the size of the packed vector elements .

## Related Topics

* [Vector Type](https://docs.singlestore.com/db/v9.1/reference/sql-reference/data-types/vector-type.md)
* [Vector Indexing](https://docs.singlestore.com/db/v9.1/reference/sql-reference/vector-functions/vector-indexing.md)
* [Working with Vector Data](https://docs.singlestore.com/db/v9.1/developer-resources/functional-extensions/working-with-vector-data.md)
* [Inserting Vectors as Blobs from an External Application](https://docs.singlestore.com/db/v9.1/reference/sql-reference/vector-functions/using-vector-functions.md)
* [JSON\_ARRAY\_PACK](https://docs.singlestore.com/db/v9.1/reference/sql-reference/vector-functions/json-array-pack.md)
* [JSON\_ARRAY\_UNPACK](https://docs.singlestore.com/db/v9.1/reference/sql-reference/vector-functions/json-array-unpack.md)
* [Vector Normalization](https://docs.singlestore.com/db/v9.1/reference/sql-reference/vector-functions/vector-normalization.md)
* [DOT\_PRODUCT](https://docs.singlestore.com/db/v9.1/reference/sql-reference/vector-functions/dot-product.md)

***

Modified at: July 14, 2025

Source: [/db/v9.1/reference/sql-reference/vector-functions/euclidean-distance/](https://docs.singlestore.com/db/v9.1/reference/sql-reference/vector-functions/euclidean-distance/)

(An index of the documentation is available at /llms.txt)