距离函数 - ClickHouse Documentation

L1Distance

引入版本：v21.11.0 计算 L1 空间中两点之间的距离 (向量中的元素为坐标) ，即 1-范数 (出租车几何距离) 。语法

L1Distance(vector1, vector2)

别名: distanceL1 参数

vector1 — 第一个向量。Tuple(T) 或 Array(T)
vector2 — 第二个向量。Tuple(T) 或 Array(T)

返回值 返回 1-范数距离。对于 Array 输入，如果元素类型的最小共同超类型为 Float32 或 BFloat16，则返回 Float32，否则返回 Float64。对于 Tuple 输入，返回类型遵循逐元素运算的算术结果类型 (整数类型保持不变) 。(U)Int* 或 Float* 示例 基本用法

Query

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

Response

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

L1Norm

引入版本：v21.11.0 计算向量中各元素绝对值的总和。语法

L1Norm(vector)

别名: normL1 参数

vector — 数值的向量或 Tuple。Array(T) 或 Tuple(T)

返回值 返回 L1 范数或出租车几何中的距离。UInt* 或 Float* 或 Decimal 示例 基本用法

Query

SELECT L1Norm((1, 2))

Response

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

L1Normalize

引入版本：v21.11.0 计算给定向量在 L1 空间中的单位向量 (Tuple 的元素为坐标) (出租车几何) 。语法

L1Normalize(tuple)

别名: normalizeL1 参数

tuple — 数值类型的元组。Tuple(T)

返回值 返回单位向量。Tuple(Float64) 示例 基本用法

Query

SELECT L1Normalize((1, 2))

Response

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

L2Distance

引入于：v21.11.0 计算欧几里得空间中两点之间的距离，其中向量的元素表示坐标 (欧几里得距离) 。语法

L2Distance(vector1, vector2)

别名: distanceL2 参数

vector1 — 第一个向量。Tuple(T) 或 Array(T)
vector2 — 第二个向量。Tuple(T) 或 Array(T)

返回值 返回 2-范数距离。对于 Array 输入，如果元素类型的共同超类型是 Float32 或 BFloat16，则返回 Float32；否则返回 Float64。对于 Tuple 输入，始终返回 Float64。Float* 示例 基本用法

Query

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

Response

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

L2DistanceTransposed

引入版本：v25.10.0 计算欧几里得空间中两点之间的近似距离 (向量中的值即坐标) (欧几里得距离) 。语法

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

别名: distanceL2Transposed 参数

vectors — 向量。QBit(T, UInt64[, UInt64])
reference — 参考向量。Array(T)
p — 在距离计算中，每个向量元素使用的位数 (1 到元素位宽) 。量化级别控制精度与速度之间的权衡。使用较少的位可提升 I/O 和计算速度，但精度会降低；使用较多的位则可提高精度，但会牺牲性能。UInt
used_dims — 可选。要读取的前几个维度，用于在带步幅的 QBit 上执行降维 (Matryoshka) 搜索。必须是 QBit 步幅的倍数，且不能超过其维度；参考向量也必须至少包含这么多元素 (多出的尾部元素会被忽略) 。只会读取覆盖这些维度的步幅分组。UInt

返回值 返回近似的 2-范数距离。始终为 Float64。Float64 示例 基本用法

Query

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

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

L2DistanceTransposedQuantized

引入版本：v26.7.0 计算 quantizeBFloat16ToInt8 编码的 QBit(Int8) (在计算时即时反量化) 与参考向量之间的近似欧几里得距离。Float 参考 (查询) 向量会直接以 Float32 精度进行比较——这正是反量化后编码的重建精度，因此 Float64 查询会缩窄为 Float32，而 BFloat16 查询则会精确扩展到该精度 (非对称距离计算) ；Array(Int8) 参考向量本身会被视为 quantizeBFloat16ToInt8 编码，并反量化到其重建级别。请注意，p 只会截断已存储的 QBit 编码；Array(Int8) 参考向量本身是完整查询，并且始终以完整的 8 位精度重建，因此只有在 p = 8 时，这才是对称的“量化对量化”距离 (当 p < 8 时，只有存储侧会以较粗精度读取) 。它必须与量化前的值处于同一空间中 (即经过相同的随机旋转和缩放之后) ，这由调用方负责保证。余弦距离具有缩放不变性；点积和 L2 距离则不具有。语法

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

参数

vectors — quantizeBFloat16ToInt8 编码的向量。QBit(Int8, UInt64[, UInt64])
reference — 参考 (查询) 向量：Float 数组 (即查询向量，以 Float32 精度进行比较——Float64 查询会收窄为 Float32) ，或由 quantizeBFloat16ToInt8 编码组成并在使用时即时反量化的 Array(Int8)。Array(Float32) 或 Array(Int8)
p — 每个已存储 QBit 编码要使用的高位数 (1 到 8) 。位数越少，重建出的嵌入式量化器越粗糙，I/O 越快，但准确性会降低；8 位则为全精度重建。p 只会截断已存储的 QBit；Array(Int8) 参考向量始终按完整的 8 位精度重建。UInt
used_dims — 可选。要读取的前几个维度，用于在带步幅的 QBit 上执行降维 (Matryoshka) 搜索。必须是 QBit 步幅的倍数，且不能超过其维度；参考向量也必须至少包含这么多元素 (任何额外的尾随元素都会被忽略) 。只会读取覆盖这些维度的步幅分组。UInt

返回值 返回近似的 2-范数距离。始终为 Float64。Float64 示例 基本用法

Query

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

引入版本：v21.11.0 计算向量各元素平方和的平方根。语法

L2Norm(vector)

别名: normL2 参数

vector — 由数值组成的向量或元组。Tuple(T) 或 Array(T)

返回值 返回 L2 范数或欧几里得距离。UInt* 或 Float* 示例 基本用法

Query

SELECT L2Norm((1, 2))

Response

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

L2Normalize

引入版本：v21.11.0 计算给定向量在欧几里得空间中的单位向量 (Tuple 中的元素为坐标) ，使用欧几里得距离。语法

L2Normalize(tuple)

别名: normalizeL2 参数

tuple — 由数值组成的元组。Tuple(T)

返回值 返回单位向量。Tuple(Float64) 示例 基本用法

Query

SELECT L2Normalize((3, 4))

Response

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

L2SquaredDistance

引入版本：v22.7.0 计算两个向量中对应元素之差的平方和。语法

L2SquaredDistance(vector1, vector2)

别名: distanceL2Squared 参数

vector1 — 第一个向量。Tuple(T) 或 Array(T)
vector2 — 第二个向量。Tuple(T) 或 Array(T)

返回值 返回两个向量对应元素之差的平方和。对于 Array 输入，如果元素类型的最小共同超类型为 Float32 或 BFloat16，则返回 Float32，否则返回 Float64。对于 Tuple 输入，返回类型遵循逐元素运算的算术结果类型 (保留整数类型) 。(U)Int* 或 Float* 示例 基本用法

Query

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

Response

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

L2SquaredNorm

引入版本：v22.7.0 计算向量元素平方和的平方根 (L2Norm) 的平方。语法

L2SquaredNorm(vector)

别名: normL2Squared 参数

vector — 由数值组成的向量或元组。Array(T) 或 Tuple(T)

返回值 返回 L2 范数的平方。UInt* 或 Float* 或 Decimal 示例 基本用法

Query

SELECT L2SquaredNorm((1, 2))

Response

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

LinfDistance

引入版本：v21.11.0 计算 L_{inf} 空间中两点之间的距离 (向量中的元素为坐标) (最大范数) 。语法

LinfDistance(vector1, vector2)

别名: distanceLinf 参数

vector1 — 第一个向量。Tuple(T) 或 Array(T)
vector2 — 第二个向量。Tuple(T) 或 Array(T)

返回值 返回无穷范数距离。对于 Array 输入，如果元素类型的最小共同超类型为 Float32 或 BFloat16，则返回 Float32；否则返回 Float64。对于 Tuple 输入，始终返回 Float64。Float* 示例 基本用法

Query

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

Response

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

LinfNorm

引入版本：v21.11.0 计算向量中各元素绝对值的最大值。语法

LinfNorm(vector)

别名: normLinf 参数

vector — 由数值组成的向量或元组。Array(T) 或 Tuple(T)

返回值 返回 Linf 范数，即最大绝对值。Float64 示例 基本用法

Query

SELECT LinfNorm((1, -2))

Response

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

LinfNormalize

引入版本：v21.11.0 计算给定向量在 L_{inf} 空间中的单位向量 (Tuple 中的元素为各坐标) ，使用最大范数。语法

LinfNormalize(tuple)

别名: normalizeLinf 参数

tuple — 由数值组成的元组。Tuple(T)

返回值 返回单位向量。Tuple(Float64) 示例 基本用法

Query

SELECT LinfNormalize((3, 4))

Response

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

LpDistance

引入版本：v21.11.0 计算 Lp 空间中两点之间的距离 (向量中的元素为坐标) (p-范数距离) 。语法

LpDistance(vector1, vector2, p)

别名: distanceLp 参数

vector1 — 第一个向量。Tuple(T) 或 Array(T)
vector2 — 第二个向量。Tuple(T) 或 Array(T)
p — 幂次。可能的值：[1; inf) 范围内的实数。UInt* 或 Float*

返回值 返回 p-范数距离。对于 Array 输入，如果元素类型的最小共同超类型为 Float32 或 BFloat16，则返回 Float32，否则返回 Float64。对于 Tuple 输入，始终返回 Float64。Float* 示例 基本用法

Query

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

Response

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

LpNorm

引入版本：v21.11.0 计算向量的 p-范数，即该向量各元素绝对值的 p 次幂之和的 p 次方根。特殊情况：

当 p=1 时，它等价于 L1Norm (曼哈顿距离) 。
当 p=2 时，它等价于 L2Norm (欧几里得距离) 。
当 p=∞ 时，它等价于 LinfNorm (最大范数) 。

语法

LpNorm(vector, p)

别名: normLp 参数

vector — 由数值组成的向量或元组。Tuple(T) 或 Array(T)
p — 幂指数。可能的值为范围 [1; inf) 内的实数。UInt* 或 Float*

返回值 返回 Lp 范数。Float64 示例 基本用法

Query

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

Response

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

LpNormalize

在以下版本中引入：v21.11.0 计算给定向量在 Lp 空间中的单位向量 (Tuple 中的元素为坐标) ，使用 p-norm。语法

LpNormalize(tuple, p)

别名: normalizeLp 参数

tuple — 由数值组成的元组。Tuple(T)
p — 幂。可能的值为 [1; inf) 范围内的任意数字。UInt* 或 Float*

返回值 返回单位向量。Tuple(Float64) 示例 使用示例

Query

SELECT LpNormalize((3, 4), 5)

Response

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

cosineDistance

引入版本：v21.11.0 计算两个向量之间的余弦距离 (元组中的元素为坐标) 。返回值越小，两个向量就越相似。语法

cosineDistance(vector1, vector2)

别名: distanceCosine 参数

vector1 — 第一个向量。Tuple(T) 或 Array(T)
vector2 — 第二个向量。Tuple(T) 或 Array(T)

返回值 返回余弦距离 (即 1 减去余弦相似度) 。对于 Array 输入，如果元素类型的共同超类型为 Float32 或 BFloat16，则返回 Float32，否则返回 Float64。对于 Tuple 输入，始终返回 Float64。Float* 示例 基本用法

Query

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

Response

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

cosineDistanceTransposed

引入版本：v26.1.0 计算两个点之间的近似余弦距离 (向量的值即为坐标) 。返回值越小，向量越相似。语法

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

别名: distanceCosineTransposed 参数

vectors — 向量。QBit(T, UInt64[, UInt64])
reference — 参考向量。Array(T)
p — 在距离计算中，每个向量元素使用的位数 (从 1 到元素位宽) 。量化级别控制精度与速度之间的权衡。使用较少的位可加快 I/O 和计算速度，但会降低准确性；使用较多的位可提高准确性，但会牺牲性能。UInt
used_dims — 可选。要读取的起始维度数量，用于在带步幅的 QBit 上进行降维 (Matryoshka) 搜索。必须是 QBit 步幅的倍数，且不超过其维度；参考向量也必须至少包含这么多个元素 (任何额外的尾随元素都会被忽略) 。仅读取覆盖这些维度的步幅分组。UInt

返回值 返回近似余弦距离 (即 1 减去余弦相似度) 。始终返回 Float64。Float64 示例 基本用法

Query

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

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

cosineDistanceTransposedQuantized

引入版本：v26.7.0 计算由 quantizeBFloat16ToInt8 编码构成的 QBit(Int8) (在计算过程中即时反量化) 与参考向量之间的近似余弦距离。返回值越小，向量越相似。Float 参考 (查询) 向量会直接以 Float32 精度进行比较——这也是反量化编码的重建精度，因此 Float64 查询会被降为 Float32，而 BFloat16 查询则会被精确提升到该精度 (非对称距离计算) ；Array(Int8) 参考本身会被视为 quantizeBFloat16ToInt8 编码，并反量化到其重建级别。请注意，p 只会截断已存储的 QBit 编码；Array(Int8) 参考本身是完整查询，始终以完整 8 位精度重建，因此只有在 p = 8 时，这才是对称的量化对量化距离 (对于 p < 8，只有存储侧会以较低精度读取) 。它必须与量化前的值所在的空间一致 (即经过相同的随机旋转和缩放之后) ，这由调用方负责。余弦距离具有缩放不变性；点积和 L2 距离则不具备。语法

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

参数

vectors — quantizeBFloat16ToInt8 编码的向量。QBit(Int8, UInt64[, UInt64])
reference — 参考 (查询) 向量：可以是 Float 数组 (查询会以 Float32 精度进行比较——Float64 查询会被收窄为 Float32) ，也可以是会在使用时即时反量化的 quantizeBFloat16ToInt8 编码 Array(Int8)。Array(Float32) 或 Array(Int8)
p — 每个已存储 QBit 编码使用的高位数 (1 到 8) 。位数越少，重建出的量化器越粗略，从而以精度降低为代价获得更快的 I/O；8 位表示全精度重建。p 只会截断已存储的 QBit；Array(Int8) 参考始终按完整 8 位精度重建。UInt
used_dims — 可选。要读取的前导维度数，用于在带步幅的 QBit 上执行降维 (Matryoshka) 搜索。该值必须是 QBit 步幅的倍数，且不能超过其维度；同时参考向量必须至少包含这么多个元素 (任何额外的尾随元素都会被忽略) 。只会读取覆盖这些维度的步幅分组。UInt

返回值 返回近似余弦距离 (即一减去余弦相似度) 。始终返回 Float64。Float64 示例 基本用法

Query

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

引入版本：v26.7.0 计算两个向量的近似点积 (内积) (向量的值即为坐标) 。与距离函数不同，这是一个相似度度量：返回值越大，向量越相似。语法

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

别名: scalarProductTransposed 参数

vectors — 向量。QBit(T, UInt64[, UInt64])
reference — 参考向量。Array(T)
p — 在计算中，每个向量元素使用的位数 (从 1 到元素位宽) 。量化级别控制精度与速度之间的权衡。使用较少的位可加快 I/O 和计算速度，但会降低准确性；使用较多的位可提高准确性，但会牺牲性能。UInt
used_dims — 可选。要读取的前几个维度的数量，用于在带步幅的 QBit 上执行降维 (Matryoshka) 搜索。必须是 QBit 步幅的倍数，且不能超过其维度；参考向量必须至少包含这么多个元素 (任何额外的尾部元素都会被忽略) 。只会读取覆盖这些维度的步幅分组。UInt

返回值 返回两个向量的近似点积。始终返回 Float64。Float64 示例 基本用法

Query

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;

Response

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

dotProductTransposedQuantized

引入版本：v26.7.0 计算 quantizeBFloat16ToInt8 编码的 QBit(Int8) (即时反量化) 与参考向量之间的近似点积 (内积) 。这是一个相似度度量：返回值越大，向量越相似。Float 参考 (查询) 向量会直接以 Float32 精度进行比较——这也是反量化编码的重建精度，因此 Float64 查询会缩窄为 Float32，而 BFloat16 查询则会精确扩展到该精度 (非对称距离计算) ；Array(Int8) 参考向量本身会被视为 quantizeBFloat16ToInt8 编码，并反量化到其重建级别。请注意，p 只会截断已存储的 QBit 编码；Array(Int8) 参考向量是完整查询，始终会以完整的 8 位精度重建，因此只有在 p = 8 时，这才是对称的量化对量化距离 (当 p < 8 时，只有存储侧会以较粗的精度读取) 。它必须与量化前的值处于同一空间中 (即经过相同的随机旋转和缩放之后) ，这一点由调用方负责。余弦距离具有缩放不变性；点积和 L2 距离则不具备这一性质。语法

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

参数

vectors — quantizeBFloat16ToInt8 编码的向量。QBit(Int8, UInt64[, UInt64])
reference — 参考 (查询) 向量：Float 数组 (查询会以 Float32 精度进行比较——Float64 查询会被收窄为 Float32)，或 quantizeBFloat16ToInt8 编码的 Array(Int8)，并在运行时即时反量化。Array(Float32) 或 Array(Int8)
p — 每个已存储 QBit 编码中要使用的高位位数 (1 到 8)。位数越少，重建出的嵌入式量化器越粗糙，可获得更快的 I/O，但准确性会降低；8 位则为全精度重建。p 只会截断已存储的 QBit；Array(Int8) 参考向量始终以完整的 8 位精度重建。UInt
used_dims — 可选。要读取的前几个维度的数量，用于在带步幅的 QBit 上执行降维 (Matryoshka) 搜索。必须是 QBit 步幅的倍数，且不能超过其维度；参考向量也必须至少包含这么多个元素 (任何额外的尾部元素都会被忽略)。只会读取覆盖这些维度的步幅分组。UInt

返回值 返回两个向量的近似点积。始终返回 Float64。Float64 示例 基本用法

Query

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;

​L1Distance

​L1Norm

​L1Normalize

​L2Distance

​L2DistanceTransposed

​L2DistanceTransposedQuantized

​L2Norm

​L2Normalize

​L2SquaredDistance

​L2SquaredNorm

​LinfDistance

​LinfNorm

​LinfNormalize

​LpDistance

​LpNorm

​LpNormalize

​cosineDistance

​cosineDistanceTransposed

​cosineDistanceTransposedQuantized

​dotProductTransposed

​dotProductTransposedQuantized

L1Distance

L1Norm

L1Normalize

L2Distance

L2DistanceTransposed

L2DistanceTransposedQuantized

L2Norm

L2Normalize

L2SquaredDistance

L2SquaredNorm

LinfDistance

LinfNorm

LinfNormalize

LpDistance

LpNorm

LpNormalize

cosineDistance

cosineDistanceTransposed

cosineDistanceTransposedQuantized

dotProductTransposed

dotProductTransposedQuantized