Distance functions

[Edit this page](https://github.com/ClickHouse/ClickHouse/tree/master/docs/en/sql-reference/functions/distance-functions.md)

## L1Distance[​](#L1Distance "Direct link to L1Distance")

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**

```
L1Distance(vector1, vector2)
```

**Aliases**: `distanceL1`

**Arguments**

- `vector1` — First vector. [`Tuple(T)`](/docs/sql-reference/data-types/tuple) or [`Array(T)`](/docs/sql-reference/data-types/array)
- `vector2` — Second vector. [`Tuple(T)`](/docs/sql-reference/data-types/tuple) or [`Array(T)`](/docs/sql-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*`](/docs/sql-reference/data-types/int-uint) or [`Float*`](/docs/sql-reference/data-types/float)

**Examples**

**Basic usage**

```
SELECT L1Distance((1, 2), (2, 3))
```

```
┌─L1Distance((1, 2), (2, 3))─┐
│                          2 │
└────────────────────────────┘
```

## L1Norm[​](#L1Norm "Direct link to L1Norm")

Introduced in: v21.11.0

Calculates the sum of absolute elements of a vector.

**Syntax**

```
L1Norm(vector)
```

**Aliases**: `normL1`

**Arguments**

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

**Returned value**

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

**Examples**

**Basic usage**

```
SELECT L1Norm((1, 2))
```

```
┌─L1Norm((1, 2))─┐
│              3 │
└────────────────┘
```

## L1Normalize[​](#L1Normalize "Direct link to L1Normalize")

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**

```
L1Normalize(tuple)
```

**Aliases**: `normalizeL1`

**Arguments**

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

**Returned value**

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

**Examples**

**Basic usage**

```
SELECT L1Normalize((1, 2))
```

```
┌─L1Normalize((1, 2))─────────────────────┐
│ (0.3333333333333333,0.6666666666666666) │
└─────────────────────────────────────────┘
```

## L2Distance[​](#L2Distance "Direct link to L2Distance")

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**

```
L2Distance(vector1, vector2)
```

**Aliases**: `distanceL2`

**Arguments**

- `vector1` — First vector. [`Tuple(T)`](/docs/sql-reference/data-types/tuple) or [`Array(T)`](/docs/sql-reference/data-types/array)
- `vector2` — Second vector. [`Tuple(T)`](/docs/sql-reference/data-types/tuple) or [`Array(T)`](/docs/sql-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*`](/docs/sql-reference/data-types/float)

**Examples**

**Basic usage**

```
SELECT L2Distance((1, 2), (2, 3))
```

```
┌─L2Distance((1, 2), (2, 3))─┐
│         1.4142135623730951 │
└────────────────────────────┘
```

## L2DistanceTransposed[​](#L2DistanceTransposed "Direct link to L2DistanceTransposed")

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**

```
L2DistanceTransposed(vector1, vector2, p)
```

**Aliases**: `distanceL2Transposed`

**Arguments**

- `vectors` — Vectors. [`QBit(T, UInt64)`](/docs/sql-reference/data-types/qbit)
- `reference` — Reference vector. [`Array(T)`](/docs/sql-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`](/docs/sql-reference/data-types/int-uint)

**Returned value**

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

**Examples**

**Basic usage**

```
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;
```

```
┌─L2DistanceTransposed([0, 1], [1, 2], 16)─┐
│                       1.4142135623730951 │
└──────────────────────────────────────────┘
```

## L2Norm[​](#L2Norm "Direct link to L2Norm")

Introduced in: v21.11.0

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

**Syntax**

```
L2Norm(vector)
```

**Aliases**: `normL2`

**Arguments**

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

**Returned value**

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

**Examples**

**Basic usage**

```
SELECT L2Norm((1, 2))
```

```
┌───L2Norm((1, 2))─┐
│ 2.23606797749979 │
└──────────────────┘
```

## L2Normalize[​](#L2Normalize "Direct link to L2Normalize")

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**

```
L2Normalize(tuple)
```

**Aliases**: `normalizeL2`

**Arguments**

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

**Returned value**

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

**Examples**

**Basic usage**

```
SELECT L2Normalize((3, 4))
```

```
┌─L2Normalize((3, 4))─┐
│ (0.6,0.8)           │
└─────────────────────┘
```

## L2SquaredDistance[​](#L2SquaredDistance "Direct link to L2SquaredDistance")

Introduced in: v22.7.0

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

**Syntax**

```
L2SquaredDistance(vector1, vector2)
```

**Aliases**: `distanceL2Squared`

**Arguments**

- `vector1` — First vector. [`Tuple(T)`](/docs/sql-reference/data-types/tuple) or [`Array(T)`](/docs/sql-reference/data-types/array)
- `vector2` — Second vector. [`Tuple(T)`](/docs/sql-reference/data-types/tuple) or [`Array(T)`](/docs/sql-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*`](/docs/sql-reference/data-types/int-uint) or [`Float*`](/docs/sql-reference/data-types/float)

**Examples**

**Basic usage**

```
SELECT L2SquaredDistance([1, 2, 3], [0, 0, 0])
```

```
┌─L2SquaredDis⋯ [0, 0, 0])─┐
│                       14 │
└──────────────────────────┘
```

## L2SquaredNorm[​](#L2SquaredNorm "Direct link to L2SquaredNorm")