距离函数

引入版本：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*

示例

基本用法

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

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

引入版本：v21.11.0

计算向量中各元素绝对值的总和。

语法

L1Norm(vector)

别名: normL1

参数

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

返回值

返回 L1 范数或 出租车几何中的距离。UInt* 或 Float* 或 Decimal

示例

基本用法

SELECT L1Norm((1, 2))

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

引入版本：v21.11.0

计算给定向量在 L1 空间中的单位向量 (Tuple 或数组的元素为坐标) (出租车几何) 。

语法

L1Normalize(vector)

别名: normalizeL1

参数

• vector — 数值类型的 Tuple 或数组。Tuple(T) 或 Array(T)

返回值

返回单位向量。对于 Array 输入，若元素类型的最小共同超类型为 Float32 或 BFloat16，则返回 Array(Float32)；否则返回 Array(Float64)。对于 Tuple 输入，始终返回 Tuple(Float64)。Tuple(Float64) 或 Array(Float32) 或 Array(Float64)

示例

基本用法

SELECT L1Normalize((1, 2))

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

引入于：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*

示例

基本用法

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

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

引入版本：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

示例

基本用法

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(vec, [1, 2], 16)─┐
│                    1.3922918381215914 │
└───────────────────────────────────────┘

引入版本：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) 。位数越少，会使用现有 Lloyd-Max 前缀区间的高斯条件均值质心重建出更粗糙的嵌入式量化器，从而实现更快的 I/O，但准确性会降低；8 位则为全精度重建。p 只会截断已存储的 QBit；Array(Int8) 参考向量始终按完整的 8 位精度重建。UInt
• used_dims — 可选。要读取的前几个维度，用于在带步幅的 QBit 上执行降维 (Matryoshka) 搜索。必须是 QBit 步幅的倍数，且不能超过其维度；参考向量也必须至少包含这么多元素 (任何额外的尾随元素都会被忽略) 。只会读取覆盖这些维度的步幅分组。UInt

返回值

返回近似的 2-范数距离。始终为 Float64。Float64

示例

基本用法

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;

┌─L2DistanceTransposedQuantized(vec, CAST('[0.1, -0.5]', 'Array(Float32)'), 8)─┐
│                                                         0.004942022755037076 │
└──────────────────────────────────────────────────────────────────────────────┘

引入版本：v21.11.0

计算向量各元素平方和的平方根。

语法

L2Norm(vector)

别名: normL2

参数

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

返回值

返回 L2 范数或 欧几里得距离。UInt* 或 Float*

示例

基本用法

SELECT L2Norm((1, 2))

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

引入版本：v21.11.0

计算给定向量在欧几里得空间中的单位向量 (Tuple 或数组中的元素为坐标) ，使用欧几里得距离。

语法

L2Normalize(vector)

别名：normalizeL2

参数

• vector — 数值组成的 Tuple 或数组。Tuple(T) 或 Array(T)

返回值

返回单位向量。对于 Array 输入，若元素类型的最小共同超类型为 Float32 或 BFloat16，则返回 Array(Float32)；否则返回 Array(Float64)。对于 Tuple 输入，始终返回 Tuple(Float64)。Tuple(Float64) 或 Array(Float32) 或 Array(Float64)

示例

基本用法

SELECT L2Normalize((3, 4))

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

引入版本：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*

示例

基本用法

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

┌─L2SquaredDistance([1, 2, 3], [0, 0, 0])─┐
│                                      14 │
└─────────────────────────────────────────┘

引入版本：v22.7.0

计算向量元素平方和的平方根 (L2Norm) 的平方。

语法

L2SquaredNorm(vector)

别名: normL2Squared

参数

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

返回值

返回 L2 范数的平方。UInt* 或 Float* 或 Decimal

示例

基本用法

SELECT L2SquaredNorm((1, 2))

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

引入版本：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*

示例

基本用法

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

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

引入版本：v21.11.0

计算向量中各元素绝对值的最大值。

语法

LinfNorm(vector)

别名: normLinf

参数

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

返回值

返回 Linf 范数，即最大绝对值。Float64

示例

基本用法

SELECT LinfNorm((1, -2))

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

引入版本：v21.11.0

计算给定向量在 L_{inf} 空间中的单位向量 (Tuple 或 Array 中的元素为各坐标) ，使用最大范数。

语法

LinfNormalize(vector)

别名: normalizeLinf

参数

• vector — 由数值组成的 Tuple 或数组。Tuple(T) 或 Array(T)

返回值

返回单位向量。对于 Array 输入，如果元素类型的最小共同超类型为 Float32 或 BFloat16，则返回 Array(Float32)；否则返回 Array(Float64)。对于 Tuple 输入，始终返回 Tuple(Float64)。Tuple(Float64) 或 Array(Float32) 或 Array(Float64)

示例

基本用法

SELECT LinfNormalize((3, 4))

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

引入版本：v21.11.0

计算 Lp 空间中两点之间的距离 (向量中的元素为坐标) (p-范数距离) 。

语法

LpDistance(vector1, vector2, p)

别名: distanceLp

参数

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

返回值

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

示例

基本用法

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

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

引入版本：v21.11.0

计算向量的 p-范数，即该向量各元素绝对值的 p 次幂之和的 p 次方根。

特殊情况：

• 当 p=1 时，它等价于 L1Norm (曼哈顿距离) 。
• 当 p=2 时，它等价于 L2Norm (欧几里得距离) 。
• p 的值必须是大于等于 1 的有限值；对于最大范数 (p→∞ 时的极限) ，请改用 LinfNorm。

语法

LpNorm(vector, p)

别名: normLp

参数

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

返回值

返回 Lp 范数。Float64

示例

基本用法

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

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

引入版本：v21.11.0

计算给定向量在 Lp 空间中的单位向量 (Tuple 或数组中的元素为坐标) ，使用 p-范数。

语法

LpNormalize(vector, p)

别名：normalizeLp

参数

• vector — 数值 Tuple 或数组。Tuple(T) 或 Array(T)
• p — 幂。可选值为范围 [1; inf) 内的实数。UInt* 或 Int* 或 Float*

返回值

返回单位向量。对于 Array 输入，若元素类型的最小共同超类型为 Float32 或 BFloat16，则返回 Array(Float32)；否则返回 Array(Float64)。对于 Tuple 输入，始终返回 Tuple(Float64)。Tuple(Float64) 或 Array(Float32) 或 Array(Float64)

示例

使用示例

SELECT LpNormalize((3, 4), 5)

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

引入版本：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*

示例

基本用法

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

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

引入版本：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

示例

基本用法

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(vec, [1, 2], 16)─┐
│                       0.10557280905788935 │
└───────────────────────────────────────────┘

引入版本：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) 。位数越少，使用现有 Lloyd-Max 前缀区间的高斯条件均值质心重建出的嵌入式量化器越粗略，从而以准确性降低为代价获得更快的 I/O；8 位表示全精度重建。p 只会截断已存储的 QBit；Array(Int8) 参考始终按完整 8 位精度重建。UInt
• used_dims — 可选。要读取的前几个维度，用于在带步幅的 QBit 上执行降维 (Matryoshka) 搜索。该值必须是 QBit 步幅的倍数，且不能超过其维度；同时参考向量必须至少包含这么多个元素 (任何额外的尾随元素都会被忽略) 。只会读取覆盖这些维度的 步幅分组。UInt

返回值

返回近似余弦距离 (即一减去余弦相似度) 。始终返回 Float64。Float64

示例

基本用法

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;

┌─cosineDistanceTransposedQuantized(vec, CAST('[0.1, -0.5]', 'Array(Float32)'), 8)─┐
│                                                          0.000027192636379513857 │
└──────────────────────────────────────────────────────────────────────────────────┘

引入版本：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

示例

基本用法

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(vec, [1, 2], 16)─┐
│                                2.0625 │
└───────────────────────────────────────┘

引入版本：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)。位数越少，会使用现有 Lloyd-Max 前缀区间的高斯条件均值质心重建出更粗糙的嵌入式量化器，可获得更快的 I/O，但准确性会降低；8 位则为全精度重建。p 只会截断已存储的 QBit；Array(Int8) 参考向量始终以完整的 8 位精度重建。UInt
• used_dims — 可选。要读取的前几个维度，用于在带步幅的 QBit 上执行降维 (Matryoshka) 搜索。必须是 QBit 步幅 的倍数，且不能超过其维度；参考向量也必须至少包含这么多个元素 (任何额外的尾随元素都会被忽略)。只会读取覆盖这些维度的 步幅分组。UInt

返回值

返回两个向量的近似点积。始终返回 Float64。Float64

示例

基本用法

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;

┌─dotProductTransposedQuantized(vec, CAST('[0.1, -0.5]', 'Array(Float32)'), 8)─┐
│                                                          0.25834959745407104 │
└──────────────────────────────────────────────────────────────────────────────┘