ClickHouse/docs/en/sql-reference/functions/distance-functions.md

slug
/en/sql-reference/functions/distance-functions

Distance functions

L1Norm

Calculates the sum of absolute values of a vector.

Syntax

L1Norm(vector)

Alias: normL1.

Arguments

• vector — Tuple or Array.

Returned value

• L1-norm or taxicab geometry distance.

Type: UInt, Float or Decimal.

Examples

Query:

SELECT L1Norm((1, 2));

Result:

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

L2Norm

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

Syntax

L2Norm(vector)

Alias: normL2.

Arguments

• vector — Tuple or Array.

Returned value

• L2-norm or Euclidean distance.

Type: Float.

Example

Query:

SELECT L2Norm((1, 2));

Result:

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

LinfNorm

Calculates the maximum of absolute values of a vector.

Syntax

LinfNorm(vector)

Alias: normLinf.

Arguments

• vector — Tuple or Array.

Returned value

• Linf-norm or the maximum absolute value.

Type: Float.

Example

Query:

SELECT LinfNorm((1, -2));

Result:

┌─LinfNorm((1, -2))─┐
│                 2 │
└───────────────────┘

LpNorm

Calculates the root of p-th power of the sum of the absolute values of a vector in the power of p.

Syntax

LpNorm(vector, p)

Alias: normLp.

Arguments

• vector — Tuple or Array.
• p — The power. Possible values: real number in [1; inf). UInt or Float.

Returned value

• Lp-norm

Type: Float.

Example

Query:

SELECT LpNorm((1, -2), 2);

Result:

┌─LpNorm((1, -2), 2)─┐
│   2.23606797749979 │
└────────────────────┘

L1Distance

Calculates the distance between two points (the values of the vectors are the coordinates) in L1 space (1-norm (taxicab geometry distance)).

Syntax

L1Distance(vector1, vector2)

Alias: distanceL1.

Arguments

• vector1 — First vector. Tuple or Array.
• vector2 — Second vector. Tuple or Array.

Returned value

• 1-norm distance.

Type: Float.

Example

Query:

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

Result:

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

L2Distance

Calculates the distance between two points (the values of the vectors are the coordinates) in Euclidean space (Euclidean distance).

Syntax

L2Distance(vector1, vector2)

Alias: distanceL2.

Arguments

• vector1 — First vector. Tuple or Array.
• vector2 — Second vector. Tuple or Array.

Returned value

• 2-norm distance.

Type: Float.

Example

Query:

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

Result:

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

LinfDistance

Calculates the distance between two points (the values of the vectors are the coordinates) in L_{inf} space (maximum norm).

Syntax

LinfDistance(vector1, vector2)

Alias: distanceLinf.

Arguments

• vector1 — First vector. Tuple or Array.
• vector1 — Second vector. Tuple or Array.

Returned value

• Infinity-norm distance.

Type: Float.

Example

Query:

SELECT LinfDistance((1, 2), (2, 3));

Result:

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

LpDistance

Calculates the distance between two points (the values of the vectors are the coordinates) in Lp space (p-norm distance).

Syntax

LpDistance(vector1, vector2, p)

Alias: distanceLp.

Arguments

• vector1 — First vector. Tuple or Array.
• vector2 — Second vector. Tuple or Array.
• p — The power. Possible values: real number from [1; inf). UInt or Float.

Returned value

• p-norm distance.

Type: Float.

Example

Query:

SELECT LpDistance((1, 2), (2, 3), 3);

Result:

┌─LpDistance((1, 2), (2, 3), 3)─┐
│            1.2599210498948732 │
└───────────────────────────────┘

L1Normalize

Calculates the unit vector of a given vector (the values of the tuple are the coordinates) in L1 space (taxicab geometry).

Syntax

L1Normalize(tuple)

Alias: normalizeL1.

Arguments

• tuple — Tuple.

Returned value

• Unit vector.

Type: Tuple of Float.

Example

Query:

SELECT L1Normalize((1, 2));

Result:

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

L2Normalize

Calculates the unit vector of a given vector (the values of the tuple are the coordinates) in Euclidean space (using Euclidean distance).

Syntax

L2Normalize(tuple)

Alias: normalizeL1.

Arguments

• tuple — Tuple.

Returned value

• Unit vector.

Type: Tuple of Float.

Example

Query:

SELECT L2Normalize((3, 4));

Result:

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

LinfNormalize

Calculates the unit vector of a given vector (the values of the tuple are the coordinates) in L_{inf} space (using maximum norm).

Syntax

LinfNormalize(tuple)

Alias: normalizeLinf .

Arguments

• tuple — Tuple.

Returned value

• Unit vector.

Type: Tuple of Float.

Example

Query:

SELECT LinfNormalize((3, 4));

Result:

┌─LinfNormalize((3, 4))─┐
│ (0.75,1)              │
└───────────────────────┘

LpNormalize

Calculates the unit vector of a given vector (the values of the tuple are the coordinates) in Lp space (using p-norm).

Syntax

LpNormalize(tuple, p)

Alias: normalizeLp .

Arguments

• tuple — Tuple.
• p — The power. Possible values: any number from [1;inf). UInt or Float.

Returned value

• Unit vector.

Type: Tuple of Float.

Example

Query:

SELECT LpNormalize((3, 4),5);

Result:

┌─LpNormalize((3, 4), 5)──────────────────┐
│ (0.7187302630182624,0.9583070173576831) │
└─────────────────────────────────────────┘

cosineDistance

Calculates the cosine distance between two vectors (the values of the tuples are the coordinates). The less the returned value is, the more similar are the vectors.

Syntax

cosineDistance(vector1, vector2)

Arguments

• vector1 — First tuple. Tuple or Array.
• vector2 — Second tuple. Tuple or Array.

Returned value

• Cosine of the angle between two vectors substracted from one.

Type: Float.

Examples

Query:

SELECT cosineDistance((1, 2), (2, 3));

Result:

┌─cosineDistance((1, 2), (2, 3))─┐
│           0.007722123286332261 │
└────────────────────────────────┘