Skip to main content
Skip to main content
Edit this page

Distance functions

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 distance)).

Syntax

L1Distance(vector1, vector2)

Aliases: distanceL1

Arguments

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

Examples

Basic usage

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

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

L1Norm​

Introduced in: v21.11.0

Calculates the sum of absolute elements of a vector.

Syntax

L1Norm(vector)

Aliases: normL1

Arguments

Returned value

Returns the L1-norm or taxicab geometry distance. UInt* or Float* or Decimal

Examples

Basic usage

SELECT L1Norm((1, 2))

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

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).

Syntax

L1Normalize(tuple)

Aliases: normalizeL1

Arguments

  • tuple — A tuple of numeric values. Tuple(T)

Returned value

Returns the unit vector. Tuple(Float64)

Examples

Basic usage

SELECT L1Normalize((1, 2))

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

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).

Syntax

L2Distance(vector1, vector2)

Aliases: distanceL2

Arguments

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*

Examples

Basic usage

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

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

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).

Syntax

L2DistanceTransposed(vector1, vector2, p[, used_dims])

Aliases: distanceL2Transposed

Arguments

  • vectors — Vectors. QBit(T, UInt64[, UInt64])
  • reference — Reference vector. Array(T)
  • 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
  • used_dims — Optional. Number of leading dimensions to read, for a reduced-dimension (Matryoshka) search on a strided QBit. Must be a multiple of the QBit stride not exceeding its dimension, and the reference vector must have exactly this many elements. Only the stride groups covering these dimensions are read. UInt

Returned value

Returns the approximate 2-norm distance. Always returns Float64. Float64

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 │
└──────────────────────────────────────────┘

L2DistanceTransposedQuantized​

Introduced in: v26.7.0

Calculates the approximate Euclidean distance between a QBit(Int8) of quantizeBFloat16ToInt8 codes (dequantized on the fly) and a reference vector. A Float reference (query) vector is compared directly at Float32 precision -- the reconstruction precision of the dequantized codes, so a Float64 query is narrowed to Float32 while a BFloat16 query widens to it exactly (asymmetric distance computation); an Array(Int8) reference is itself treated as quantizeBFloat16ToInt8 codes and dequantized to its reconstruction levels. Note that p truncates only the stored QBit codes; the Array(Int8) reference is a complete query and is always reconstructed at full 8-bit precision, so this is a symmetric quantized-vs-quantized distance only at p = 8 (for p < 8 only the stored side is read at coarser precision). It must live in the same space as the values were in before quantization (i.e. after the same random rotation and scaling), which is the caller's responsibility. Cosine distance is scale-invariant; dot product and L2 distance are not.

Syntax

L2DistanceTransposedQuantized(vectors, reference, p[, used_dims])

Arguments

  • vectors — Vectors of quantizeBFloat16ToInt8 codes. QBit(Int8, UInt64[, UInt64])
  • reference — Reference (query) vector: a Float array (the query, compared at Float32 precision -- a Float64 query is narrowed to Float32), or an Array(Int8) of quantizeBFloat16ToInt8 codes dequantized on the fly. Array(Float32) or Array(Int8)
  • p — Number of top bits of each stored QBit code to use (1 to 8). Fewer bits reconstruct a coarser embedded quantizer for faster I/O with reduced accuracy; 8 bits is the full-precision reconstruction. p truncates only the stored QBit; an Array(Int8) reference is always reconstructed at full 8-bit precision. UInt
  • used_dims — Optional. Number of leading dimensions to read, for a reduced-dimension (Matryoshka) search on a strided QBit. Must be a multiple of the QBit stride not exceeding its dimension, and the reference vector must have exactly this many elements. Only the stride groups covering these dimensions are read. UInt

Returned value

Returns the approximate 2-norm distance. Always returns Float64. Float64

Examples

Basic usage

CREATE TABLE qbit (id UInt32, vec QBit(Int8, 2)) ENGINE = Memory;
INSERT INTO qbit VALUES (1, arrayMap(x -> quantizeBFloat16ToInt8(x), [0.1, -0.5]::Array(BFloat16)));
SELECT L2DistanceTransposedQuantized(vec, [0.1, -0.5]::Array(Float32), 8) FROM qbit;

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

Returned value

Returns the L2-norm or Euclidean distance. UInt* or Float*

Examples

Basic usage

SELECT L2Norm((1, 2))

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

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).

Syntax

L2Normalize(tuple)

Aliases: normalizeL2

Arguments

  • tuple — A tuple of numeric values. Tuple(T)

Returned value

Returns the unit vector. Tuple(Float64)

Examples

Basic usage

SELECT L2Normalize((3, 4))

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

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

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

Examples

Basic usage

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

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

L2SquaredNorm​

Introduced in: v22.7.0

Calculates the square root of the sum of the squares of the vector elements (the L2Norm) squared.

Syntax

L2SquaredNorm(vector)

Aliases: normL2Squared

Arguments

Returned value

Returns the L2-norm squared. UInt* or Float* or Decimal

Examples

Basic usage

SELECT L2SquaredNorm((1, 2))

┌─L2SquaredNorm((1, 2))─┐
│                     5 │
└───────────────────────┘

LinfDistance​

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).

Syntax

LinfDistance(vector1, vector2)

Aliases: distanceLinf

Arguments

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*

Examples

Basic usage

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

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

LinfNorm​

Introduced in: v21.11.0

Calculates the maximum of absolute elements of a vector.

Syntax

LinfNorm(vector)

Aliases: normLinf

Arguments

Returned value

Returns the Linf-norm or the maximum absolute value. Float64

Examples

Basic usage

SELECT LinfNorm((1, -2))

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

LinfNormalize​

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).

Syntax

LinfNormalize(tuple)

Aliases: normalizeLinf

Arguments

  • tuple — A tuple of numeric values. Tuple(T)

Returned value

Returns the unit vector. Tuple(Float64)

Examples

Basic usage

SELECT LinfNormalize((3, 4))

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

LpDistance​

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).

Syntax

LpDistance(vector1, vector2, p)

Aliases: distanceLp

Arguments

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*

Examples

Basic usage

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

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

LpNorm​

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

LpNorm(vector, p)

Aliases: normLp

Arguments

  • vector — Vector or tuple of numeric values. Tuple(T) or Array(T)
  • p — The power. Possible values are real numbers in the range [1; inf). UInt* or Float*

Returned value

Returns the Lp-norm. Float64

Examples

Basic usage

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

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

LpNormalize​

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).

Syntax

LpNormalize(tuple, p)

Aliases: normalizeLp

Arguments

  • tuple — A tuple of numeric values. Tuple(T)
  • p — The power. Possible values are any number in the range range from [1; inf). UInt* or Float*

Returned value

Returns the unit vector. Tuple(Float64)

Examples

Usage example

SELECT LpNormalize((3, 4), 5)

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

cosineDistance​

Introduced in: v21.11.0

Calculates the 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

cosineDistance(vector1, vector2)

Aliases: distanceCosine

Arguments

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*

Examples

Basic usage

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

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

cosineDistanceTransposed​

Introduced in: v26.1.0

Calculates the approximate 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

cosineDistanceTransposed(vector1, vector2, p[, used_dims])

Aliases: distanceCosineTransposed

Arguments

  • vectors — Vectors. QBit(T, UInt64[, UInt64])
  • reference — Reference vector. Array(T)
  • 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
  • used_dims — Optional. Number of leading dimensions to read, for a reduced-dimension (Matryoshka) search on a strided QBit. Must be a multiple of the QBit stride not exceeding its dimension, and the reference vector must have exactly this many elements. Only the stride groups covering these dimensions are read. UInt

Returned value

Returns the approximate cosine distance (one minus the cosine similarity). Always returns Float64. Float64

Examples

Basic usage

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;

┌─cosineDistanceTransposed([0, 1], [1, 2], 16)─┐
│                          0.10557281085638826 │
└──────────────────────────────────────────────┘

cosineDistanceTransposedQuantized​

Introduced in: v26.7.0

Calculates the approximate cosine distance between a QBit(Int8) of quantizeBFloat16ToInt8 codes (dequantized on the fly) and a reference vector. The smaller the returned value, the more similar the vectors. A Float reference (query) vector is compared directly at Float32 precision -- the reconstruction precision of the dequantized codes, so a Float64 query is narrowed to Float32 while a BFloat16 query widens to it exactly (asymmetric distance computation); an Array(Int8) reference is itself treated as quantizeBFloat16ToInt8 codes and dequantized to its reconstruction levels. Note that p truncates only the stored QBit codes; the Array(Int8) reference is a complete query and is always reconstructed at full 8-bit precision, so this is a symmetric quantized-vs-quantized distance only at p = 8 (for p < 8 only the stored side is read at coarser precision). It must live in the same space as the values were in before quantization (i.e. after the same random rotation and scaling), which is the caller's responsibility. Cosine distance is scale-invariant; dot product and L2 distance are not.

Syntax

cosineDistanceTransposedQuantized(vectors, reference, p[, used_dims])

Arguments

  • vectors — Vectors of quantizeBFloat16ToInt8 codes. QBit(Int8, UInt64[, UInt64])
  • reference — Reference (query) vector: a Float array (the query, compared at Float32 precision -- a Float64 query is narrowed to Float32), or an Array(Int8) of quantizeBFloat16ToInt8 codes dequantized on the fly. Array(Float32) or Array(Int8)
  • p — Number of top bits of each stored QBit code to use (1 to 8). Fewer bits reconstruct a coarser embedded quantizer for faster I/O with reduced accuracy; 8 bits is the full-precision reconstruction. p truncates only the stored QBit; an Array(Int8) reference is always reconstructed at full 8-bit precision. UInt
  • used_dims — Optional. Number of leading dimensions to read, for a reduced-dimension (Matryoshka) search on a strided QBit. Must be a multiple of the QBit stride not exceeding its dimension, and the reference vector must have exactly this many elements. Only the stride groups covering these dimensions are read. UInt

Returned value

Returns the approximate cosine distance (one minus the cosine similarity). Always returns Float64. Float64

Examples

Basic usage

CREATE TABLE qbit (id UInt32, vec QBit(Int8, 2)) ENGINE = Memory;
INSERT INTO qbit VALUES (1, arrayMap(x -> quantizeBFloat16ToInt8(x), [0.1, -0.5]::Array(BFloat16)));
SELECT cosineDistanceTransposedQuantized(vec, [0.1, -0.5]::Array(Float32), 8) FROM qbit;

dotProductTransposed​

Introduced in: v26.7.0

Calculates the approximate dot product (inner product) of two vectors (the values of the vectors are the coordinates). Unlike the distance functions, this is a similarity measure: the larger the returned value, the more similar the vectors are.

Syntax

dotProductTransposed(vector1, vector2, p[, used_dims])

Aliases: scalarProductTransposed

Arguments

  • vectors — Vectors. QBit(T, UInt64[, UInt64])
  • reference — Reference vector. Array(T)
  • p — Number of bits from each vector element to use in the 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
  • used_dims — Optional. Number of leading dimensions to read, for a reduced-dimension (Matryoshka) search on a strided QBit. Must be a multiple of the QBit stride not exceeding its dimension, and the reference vector must have exactly this many elements. Only the stride groups covering these dimensions are read. UInt

Returned value

Returns the approximate dot product of the two vectors. Always returns Float64. Float64

Examples

Basic usage

CREATE TABLE qbit (id UInt32, vec QBit(Float64, 2)) ENGINE = Memory;
INSERT INTO qbit VALUES (1, [0, 1]);
SELECT dotProductTransposed(vec, array(1, 2), 16) FROM qbit;

┌─dotProductTransposed([0, 1], [1, 2], 16)─┐
│                                        2 │
└──────────────────────────────────────────┘

dotProductTransposedQuantized​

Introduced in: v26.7.0

Calculates the approximate dot product (inner product) between a QBit(Int8) of quantizeBFloat16ToInt8 codes (dequantized on the fly) and a reference vector. This is a similarity measure: the larger the returned value, the more similar the vectors. A Float reference (query) vector is compared directly at Float32 precision -- the reconstruction precision of the dequantized codes, so a Float64 query is narrowed to Float32 while a BFloat16 query widens to it exactly (asymmetric distance computation); an Array(Int8) reference is itself treated as quantizeBFloat16ToInt8 codes and dequantized to its reconstruction levels. Note that p truncates only the stored QBit codes; the Array(Int8) reference is a complete query and is always reconstructed at full 8-bit precision, so this is a symmetric quantized-vs-quantized distance only at p = 8 (for p < 8 only the stored side is read at coarser precision). It must live in the same space as the values were in before quantization (i.e. after the same random rotation and scaling), which is the caller's responsibility. Cosine distance is scale-invariant; dot product and L2 distance are not.

Syntax

dotProductTransposedQuantized(vectors, reference, p[, used_dims])

Arguments

  • vectors — Vectors of quantizeBFloat16ToInt8 codes. QBit(Int8, UInt64[, UInt64])
  • reference — Reference (query) vector: a Float array (the query, compared at Float32 precision -- a Float64 query is narrowed to Float32), or an Array(Int8) of quantizeBFloat16ToInt8 codes dequantized on the fly. Array(Float32) or Array(Int8)
  • p — Number of top bits of each stored QBit code to use (1 to 8). Fewer bits reconstruct a coarser embedded quantizer for faster I/O with reduced accuracy; 8 bits is the full-precision reconstruction. p truncates only the stored QBit; an Array(Int8) reference is always reconstructed at full 8-bit precision. UInt
  • used_dims — Optional. Number of leading dimensions to read, for a reduced-dimension (Matryoshka) search on a strided QBit. Must be a multiple of the QBit stride not exceeding its dimension, and the reference vector must have exactly this many elements. Only the stride groups covering these dimensions are read. UInt

Returned value

Returns the approximate dot product of the two vectors. Always returns Float64. Float64

Examples

Basic usage

CREATE TABLE qbit (id UInt32, vec QBit(Int8, 2)) ENGINE = Memory;
INSERT INTO qbit VALUES (1, arrayMap(x -> quantizeBFloat16ToInt8(x), [0.1, -0.5]::Array(BFloat16)));
SELECT dotProductTransposedQuantized(vec, [0.1, -0.5]::Array(Float32), 8) FROM qbit;