> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-8c05c8a2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> Documentation for distance functions

# Distance functions

{/*AUTOGENERATED_START*/}

<h2 id="L1Distance">
  L1Distance
</h2>

Introduced in: v21.11.0

Calculates the distance between two points (the elements of the vectors are the coordinates) in `L1` space (1-norm ([taxicab geometry](https://en.wikipedia.org/wiki/Taxicab_geometry) distance)).

**Syntax**

```sql theme={null}
L1Distance(vector1, vector2)
```

**Aliases**: `distanceL1`

**Arguments**

* `vector1` — First vector. [`Tuple(T)`](/reference/data-types/tuple) or [`Array(T)`](/reference/data-types/array)
* `vector2` — Second vector. [`Tuple(T)`](/reference/data-types/tuple) or [`Array(T)`](/reference/data-types/array)

**Returned value**

Returns the 1-norm distance. For `Array` inputs, returns `Float32` if the least common supertype of the element types is `Float32` or `BFloat16`, otherwise `Float64`. For `Tuple` inputs, the return type follows the arithmetic result type of the element-wise operations (integer types are preserved). [`(U)Int*`](/reference/data-types/int-uint) or [`Float*`](/reference/data-types/float)

**Examples**

**Basic usage**

```sql title=Query theme={null}
SELECT L1Distance((1, 2), (2, 3))
```

```response title=Response theme={null}
┌─L1Distance((1, 2), (2, 3))─┐
│                          2 │
└────────────────────────────┘
```

<h2 id="L1Norm">
  L1Norm
</h2>

Introduced in: v21.11.0

Calculates the sum of absolute elements of a vector.

**Syntax**

```sql theme={null}
L1Norm(vector)
```

**Aliases**: `normL1`

**Arguments**

* `vector` — Vector or tuple of numeric values. [`Array(T)`](/reference/data-types/array) or [`Tuple(T)`](/reference/data-types/tuple)

**Returned value**

Returns the L1-norm or [taxicab geometry](https://en.wikipedia.org/wiki/Taxicab_geometry) distance. [`UInt*`](/reference/data-types/int-uint) or [`Float*`](/reference/data-types/float) or [`Decimal`](/reference/data-types/decimal)

**Examples**

**Basic usage**

```sql title=Query theme={null}
SELECT L1Norm((1, 2))
```

```response title=Response theme={null}
┌─L1Norm((1, 2))─┐
│              3 │
└────────────────┘
```

<h2 id="L1Normalize">
  L1Normalize
</h2>

Introduced in: v21.11.0

Calculates the unit vector of a given vector (the elements of the tuple are the coordinates) in `L1` space ([taxicab geometry](https://en.wikipedia.org/wiki/Taxicab_geometry)).

**Syntax**

```sql theme={null}
L1Normalize(tuple)
```

**Aliases**: `normalizeL1`

**Arguments**

* `tuple` — A tuple of numeric values. [`Tuple(T)`](/reference/data-types/tuple)

**Returned value**

Returns the unit vector. [`Tuple(Float64)`](/reference/data-types/tuple)

**Examples**

**Basic usage**

```sql title=Query theme={null}
SELECT L1Normalize((1, 2))
```

```response title=Response theme={null}
┌─L1Normalize((1, 2))─────────────────────┐
│ (0.3333333333333333,0.6666666666666666) │
└─────────────────────────────────────────┘
```

<h2 id="L2Distance">
  L2Distance
</h2>

Introduced in: v21.11.0

Calculates the distance between two points (the elements of the vectors are the coordinates) in Euclidean space ([Euclidean distance](https://en.wikipedia.org/wiki/Euclidean_distance)).

**Syntax**

```sql theme={null}
L2Distance(vector1, vector2)
```

**Aliases**: `distanceL2`

**Arguments**

* `vector1` — First vector. [`Tuple(T)`](/reference/data-types/tuple) or [`Array(T)`](/reference/data-types/array)
* `vector2` — Second vector. [`Tuple(T)`](/reference/data-types/tuple) or [`Array(T)`](/reference/data-types/array)

**Returned value**

Returns the 2-norm distance. For `Array` inputs, returns `Float32` if the least common supertype of the element types is `Float32` or `BFloat16`, otherwise `Float64`. For `Tuple` inputs, always returns `Float64`. [`Float*`](/reference/data-types/float)

**Examples**

**Basic usage**

```sql title=Query theme={null}
SELECT L2Distance((1, 2), (2, 3))
```

```response title=Response theme={null}
┌─L2Distance((1, 2), (2, 3))─┐
│         1.4142135623730951 │
└────────────────────────────┘
```

<h2 id="L2DistanceTransposed">
  L2DistanceTransposed
</h2>

Introduced in: v25.10.0

Calculates the approximate distance between two points (the values of the vectors are the coordinates) in Euclidean space ([Euclidean distance](https://en.wikipedia.org/wiki/Euclidean_distance)).

**Syntax**

```sql theme={null}
L2DistanceTransposed(vector1, vector2, p)
```

**Aliases**: `distanceL2Transposed`

**Arguments**

* `vectors` — Vectors. [`QBit(T, UInt64)`](/reference/data-types/qbit)
* `reference` — Reference vector. [`Array(T)`](/reference/data-types/array)
* `p` — Number of bits from each vector element to use in the distance calculation (1 to element bit-width). The quantization level controls the precision-speed trade-off. Using fewer bits results in faster I/O and calculations with reduced accuracy, while using more bits increases accuracy at the cost of performance. [`UInt`](/reference/data-types/int-uint)

**Returned value**

Returns the approximate 2-norm distance. Always returns `Float64`. [`Float64`](/reference/data-types/float)

**Examples**

**Basic usage**

```sql title=Query theme={null}
CREATE TABLE qbit (id UInt32, vec QBit(Float64, 2)) ENGINE = Memory;
INSERT INTO qbit VALUES (1, [0, 1]);
SELECT L2DistanceTransposed(vec, array(1, 2), 16) FROM qbit;
```

```response title=Response theme={null}
┌─L2DistanceTransposed([0, 1], [1, 2], 16)─┐
│                       1.4142135623730951 │
└──────────────────────────────────────────┘
```

<h2 id="L2Norm">
  L2Norm
</h2>

Introduced in: v21.11.0

Calculates the square root of the sum of the squares of the vector elements.

**Syntax**

```sql theme={null}
L2Norm(vector)
```

**Aliases**: `normL2`

**Arguments**

* `vector` — Vector or tuple of numeric values. [`Tuple(T)`](/reference/data-types/tuple) or [`Array(T)`](/reference/data-types/array)

**Returned value**

Returns the L2-norm or [Euclidean distance](https://en.wikipedia.org/wiki/Euclidean_distance). [`UInt*`](/reference/data-types/int-uint) or [`Float*`](/reference/data-types/float)

**Examples**

**Basic usage**

```sql title=Query theme={null}
SELECT L2Norm((1, 2))
```

```response title=Response theme={null}
┌───L2Norm((1, 2))─┐
│ 2.23606797749979 │
└──────────────────┘
```

<h2 id="L2Normalize">
  L2Normalize
</h2>

Introduced in: v21.11.0

Calculates the unit vector of a given vector (the elements of the tuple are the coordinates) in Euclidean space (using [Euclidean distance](https://en.wikipedia.org/wiki/Euclidean_distance)).

**Syntax**

```sql theme={null}
L2Normalize(tuple)
```

**Aliases**: `normalizeL2`

**Arguments**

* `tuple` — A tuple of numeric values. [`Tuple(T)`](/reference/data-types/tuple)

**Returned value**

Returns the unit vector. [`Tuple(Float64)`](/reference/data-types/tuple)

**Examples**

**Basic usage**

```sql title=Query theme={null}
SELECT L2Normalize((3, 4))
```

```response title=Response theme={null}
┌─L2Normalize((3, 4))─┐
│ (0.6,0.8)           │
└─────────────────────┘
```

<h2 id="L2SquaredDistance">
  L2SquaredDistance
</h2>

Introduced in: v22.7.0

Calculates the sum of the squares of the difference between the corresponding elements of two vectors.

**Syntax**

```sql theme={null}
L2SquaredDistance(vector1, vector2)
```

**Aliases**: `distanceL2Squared`

**Arguments**

* `vector1` — First vector. [`Tuple(T)`](/reference/data-types/tuple) or [`Array(T)`](/reference/data-types/array)
* `vector2` — Second vector. [`Tuple(T)`](/reference/data-types/tuple) or [`Array(T)`](/reference/data-types/array)

**Returned value**

Returns the sum of the squares of the differences between the corresponding elements of two vectors. For `Array` inputs, returns `Float32` if the least common supertype of the element types is `Float32` or `BFloat16`, otherwise `Float64`. For `Tuple` inputs, the return type follows the arithmetic result type of the element-wise operations (integer types are preserved). [`(U)Int*`](/reference/data-types/int-uint) or [`Float*`](/reference/data-types/float)

**Examples**

**Basic usage**

```sql title=Query theme={null}
SELECT L2SquaredDistance([1, 2, 3], [0, 0, 0])
```

```response title=Response theme={null}
┌─L2SquaredDis⋯ [0, 0, 0])─┐
│                       14 │
└──────────────────────────┘
```

<h2 id="L2SquaredNorm">
  L2SquaredNorm
</h2>

Introduced in: v22.7.0

Calculates the square root of the sum of the squares of the vector elements (the [`L2Norm`](#L2Norm)) squared.

**Syntax**

```sql theme={null}
L2SquaredNorm(vector)
```

**Aliases**: `normL2Squared`

**Arguments**

* `vector` — Vector or tuple of numeric values. [`Array(T)`](/reference/data-types/array) or [`Tuple(T)`](/reference/data-types/tuple)

**Returned value**

Returns the L2-norm squared. [`UInt*`](/reference/data-types/int-uint) or [`Float*`](/reference/data-types/float) or [`Decimal`](/reference/data-types/decimal)

**Examples**

**Basic usage**

```sql title=Query theme={null}
SELECT L2SquaredNorm((1, 2))
```

```response title=Response theme={null}
┌─L2SquaredNorm((1, 2))─┐
│                     5 │
└───────────────────────┘
```

<h2 id="LinfDistance">
  LinfDistance
</h2>

Introduced in: v21.11.0

Calculates the distance between two points (the elements of the vectors are the coordinates) in `L_{inf}` space ([maximum norm](https://en.wikipedia.org/wiki/Norm_\(mathematics\)#Maximum_norm_\(special_case_of:_infinity_norm,_uniform_norm,_or_supremum_norm\))).

**Syntax**

```sql theme={null}
LinfDistance(vector1, vector2)
```

**Aliases**: `distanceLinf`

**Arguments**

* `vector1` — First vector. [`Tuple(T)`](/reference/data-types/tuple) or [`Array(T)`](/reference/data-types/array)
* `vector2` — Second vector. [`Tuple(T)`](/reference/data-types/tuple) or [`Array(T)`](/reference/data-types/array)

**Returned value**

Returns the infinity-norm distance. For `Array` inputs, returns `Float32` if the least common supertype of the element types is `Float32` or `BFloat16`, otherwise `Float64`. For `Tuple` inputs, always returns `Float64`. [`Float*`](/reference/data-types/float)

**Examples**

**Basic usage**

```sql title=Query theme={null}
SELECT LinfDistance((1, 2), (2, 3))
```

```response title=Response theme={null}
┌─LinfDistance((1, 2), (2, 3))─┐
│                            1 │
└──────────────────────────────┘
```

<h2 id="LinfNorm">
  LinfNorm
</h2>

Introduced in: v21.11.0

Calculates the maximum of absolute elements of a vector.

**Syntax**

```sql theme={null}
LinfNorm(vector)
```

**Aliases**: `normLinf`

**Arguments**

* `vector` — Vector or tuple of numeric values. [`Array(T)`](/reference/data-types/array) or [`Tuple(T)`](/reference/data-types/tuple)

**Returned value**

Returns the Linf-norm or the maximum absolute value. [`Float64`](/reference/data-types/float)

**Examples**

**Basic usage**

```sql title=Query theme={null}
SELECT LinfNorm((1, -2))
```

```response title=Response theme={null}
┌─LinfNorm((1, -2))─┐
│                 2 │
└───────────────────┘
```

<h2 id="LinfNormalize">
  LinfNormalize
</h2>

Introduced in: v21.11.0

Calculates the unit vector of a given vector (the elements of the tuple are the coordinates) in `L_{inf}` space (using [maximum norm](https://en.wikipedia.org/wiki/Norm_\(mathematics\)#Maximum_norm_\(special_case_of:_infinity_norm,_uniform_norm,_or_supremum_norm\))).

**Syntax**

```sql theme={null}
LinfNormalize(tuple)
```

**Aliases**: `normalizeLinf`

**Arguments**

* `tuple` — A tuple of numeric values. [`Tuple(T)`](/reference/data-types/tuple)

**Returned value**

Returns the unit vector. [`Tuple(Float64)`](/reference/data-types/tuple)

**Examples**

**Basic usage**

```sql title=Query theme={null}
SELECT LinfNormalize((3, 4))
```

```response title=Response theme={null}
┌─LinfNormalize((3, 4))─┐
│ (0.75,1)              │
└───────────────────────┘
```

<h2 id="LpDistance">
  LpDistance
</h2>

Introduced in: v21.11.0

Calculates the distance between two points (the elements of the vectors are the coordinates) in `Lp` space ([p-norm distance](https://en.wikipedia.org/wiki/Norm_\(mathematics\)#p-norm)).

**Syntax**

```sql theme={null}
LpDistance(vector1, vector2, p)
```

**Aliases**: `distanceLp`

**Arguments**

* `vector1` — First vector. [`Tuple(T)`](/reference/data-types/tuple) or [`Array(T)`](/reference/data-types/array)
* `vector2` — Second vector. [`Tuple(T)`](/reference/data-types/tuple) or [`Array(T)`](/reference/data-types/array)
* `p` — The power. Possible values: real number from `[1; inf)`. [`UInt*`](/reference/data-types/int-uint) or [`Float*`](/reference/data-types/float)

**Returned value**

Returns the p-norm distance. For `Array` inputs, returns `Float32` if the least common supertype of the element types is `Float32` or `BFloat16`, otherwise `Float64`. For `Tuple` inputs, always returns `Float64`. [`Float*`](/reference/data-types/float)

**Examples**

**Basic usage**

```sql title=Query theme={null}
SELECT LpDistance((1, 2), (2, 3), 3)
```

```response title=Response theme={null}
┌─LpDistance((1, 2), (2, 3), 3)─┐
│            1.2599210498948732 │
└───────────────────────────────┘
```

<h2 id="LpNorm">
  LpNorm
</h2>

Introduced in: v21.11.0

Calculates the p-norm of a vector, which is the p-th root of the sum of the p-th powers of the absolute elements of its elements.

Special cases:

* When p=1, it's equivalent to L1Norm (Manhattan distance).
* When p=2, it's equivalent to L2Norm (Euclidean distance).
* When p=∞, it's equivalent to LinfNorm (maximum norm).

**Syntax**

```sql theme={null}
LpNorm(vector, p)
```

**Aliases**: `normLp`

**Arguments**

* `vector` — Vector or tuple of numeric values. [`Tuple(T)`](/reference/data-types/tuple) or [`Array(T)`](/reference/data-types/array)
* `p` — The power. Possible values are real numbers in the range `[1; inf)`. [`UInt*`](/reference/data-types/int-uint) or [`Float*`](/reference/data-types/float)

**Returned value**

Returns the [Lp-norm](https://en.wikipedia.org/wiki/Norm_\(mathematics\)#p-norm). [`Float64`](/reference/data-types/float)

**Examples**

**Basic usage**

```sql title=Query theme={null}
SELECT LpNorm((1, -2), 2)
```

```response title=Response theme={null}
┌─LpNorm((1, -2), 2)─┐
│   2.23606797749979 │
└────────────────────┘
```

<h2 id="LpNormalize">
  LpNormalize
</h2>

Introduced in: v21.11.0

Calculates the unit vector of a given vector (the elements of the tuple are the coordinates) in `Lp` space (using [p-norm](https://en.wikipedia.org/wiki/Norm_\(mathematics\)#p-norm)).

**Syntax**

```sql theme={null}
LpNormalize(tuple, p)
```

**Aliases**: `normalizeLp`

**Arguments**

* `tuple` — A tuple of numeric values. [`Tuple(T)`](/reference/data-types/tuple)
* `p` — The power. Possible values are any number in the range range from `[1; inf)`. [`UInt*`](/reference/data-types/int-uint) or [`Float*`](/reference/data-types/float)

**Returned value**

Returns the unit vector. [`Tuple(Float64)`](/reference/data-types/tuple)

**Examples**

**Usage example**

```sql title=Query theme={null}
SELECT LpNormalize((3, 4), 5)
```

```response title=Response theme={null}
┌─LpNormalize((3, 4), 5)──────────────────┐
│ (0.7187302630182624,0.9583070173576831) │
└─────────────────────────────────────────┘
```

<h2 id="cosineDistance">
  cosineDistance
</h2>

Introduced in: v21.11.0

Calculates the [cosine distance](https://en.wikipedia.org/wiki/Cosine_similarity#Cosine_distance) between two vectors (the elements of the tuples are the coordinates). The smaller the returned value is, the more similar are the vectors.

**Syntax**

```sql theme={null}
cosineDistance(vector1, vector2)
```

**Aliases**: `distanceCosine`

**Arguments**

* `vector1` — First tuple. [`Tuple(T)`](/reference/data-types/tuple) or [`Array(T)`](/reference/data-types/array)
* `vector2` — Second tuple. [`Tuple(T)`](/reference/data-types/tuple) or [`Array(T)`](/reference/data-types/array)

**Returned value**

Returns the cosine distance (one minus the cosine similarity). For `Array` inputs, returns `Float32` if the least common supertype of the element types is `Float32` or `BFloat16`, otherwise `Float64`. For `Tuple` inputs, always returns `Float64`. [`Float*`](/reference/data-types/float)

**Examples**

**Basic usage**

```sql title=Query theme={null}
SELECT cosineDistance((1, 2), (2, 3));
```

```response title=Response theme={null}
┌─cosineDistance((1, 2), (2, 3))─┐
│           0.007722123286332261 │
└────────────────────────────────┘
```

<h2 id="cosineDistanceTransposed">
  cosineDistanceTransposed
</h2>

Introduced in: v26.1.0

Calculates the approximate [cosine distance](https://en.wikipedia.org/wiki/Cosine_similarity#Cosine_distance) between two points (the values of the vectors are the coordinates). The smaller the returned value is, the more similar are the vectors.

**Syntax**

```sql theme={null}
cosineDistanceTransposed(vector1, vector2, p)
```

**Aliases**: `distanceCosineTransposed`

**Arguments**

* `vectors` — Vectors. [`QBit(T, UInt64)`](/reference/data-types/qbit)
* `reference` — Reference vector. [`Array(T)`](/reference/data-types/array)
* `p` — Number of bits from each vector element to use in the distance calculation (1 to element bit-width). The quantization level controls the precision-speed trade-off. Using fewer bits results in faster I/O and calculations with reduced accuracy, while using more bits increases accuracy at the cost of performance. [`UInt`](/reference/data-types/int-uint)

**Returned value**

Returns the approximate cosine distance (one minus the cosine similarity). Always returns Float64. [`Float64`](/reference/data-types/float)

**Examples**

**Basic usage**

```sql title=Query theme={null}
CREATE TABLE qbit (id UInt32, vec QBit(Float64, 2)) ENGINE = Memory;
INSERT INTO qbit VALUES (1, [0, 1]);
SELECT cosineDistanceTransposed(vec, array(1, 2), 16) FROM qbit;
```

```response title=Response theme={null}
┌─cosineDistanceTransposed([0, 1], [1, 2], 16)─┐
│                          0.10557281085638826 │
└──────────────────────────────────────────────┘
```