> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-fix-nav-issues.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> 距离函数文档

# 距离函数

{/*AUTOGENERATED_START*/}

<div id="L1Distance">
  ## L1Distance
</div>

引入版本：v21.11.0

计算 `L1` 空间中两点之间的距离 (向量中的元素为坐标) ，即 1-范数 ([出租车几何距离](https://en.wikipedia.org/wiki/Taxicab_geometry)) 。

**语法**

```sql theme={null}
L1Distance(vector1, vector2)
```

**别名**: `distanceL1`

**参数**

* `vector1` — 第一个向量。[`Tuple(T)`](/zh/reference/data-types/tuple) 或 [`Array(T)`](/zh/reference/data-types/array)
* `vector2` — 第二个向量。[`Tuple(T)`](/zh/reference/data-types/tuple) 或 [`Array(T)`](/zh/reference/data-types/array)

**返回值**

返回 1-范数距离。对于 `Array` 输入，如果元素类型的最小共同超类型为 `Float32` 或 `BFloat16`，则返回 `Float32`，否则返回 `Float64`。对于 `Tuple` 输入，返回类型遵循逐元素运算的算术结果类型 (整数类型保持不变) 。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)

**示例**

**基本用法**

```sql title=Query theme={null}
SELECT L1Distance((1, 2), (2, 3))
```

```response title=Response theme={null}
┌─L1Distance((1, 2), (2, 3))─┐
│                          2 │
└────────────────────────────┘
```

<div id="L1Norm">
  ## L1Norm
</div>

引入版本：v21.11.0

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

**语法**

```sql theme={null}
L1Norm(vector)
```

**别名**: `normL1`

**参数**

* `vector` — 数值的向量或 Tuple。[`Array(T)`](/zh/reference/data-types/array) 或 [`Tuple(T)`](/zh/reference/data-types/tuple)

**返回值**

返回 L1 范数或 [出租车几何中的距离](https://en.wikipedia.org/wiki/Taxicab_geometry)。[`UInt*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`Decimal`](/zh/reference/data-types/decimal)

**示例**

**基本用法**

```sql title=Query theme={null}
SELECT L1Norm((1, 2))
```

```response title=Response theme={null}
┌─L1Norm((1, 2))─┐
│              3 │
└────────────────┘
```

<div id="L1Normalize">
  ## L1Normalize
</div>

引入版本：v21.11.0

计算给定向量在 `L1` 空间中的单位向量 (Tuple 的元素为坐标)  ([出租车几何](https://en.wikipedia.org/wiki/Taxicab_geometry)) 。

**语法**

```sql theme={null}
L1Normalize(tuple)
```

**别名**: `normalizeL1`

**参数**

* `tuple` — 数值类型的元组。[`Tuple(T)`](/zh/reference/data-types/tuple)

**返回值**

返回单位向量。[`Tuple(Float64)`](/zh/reference/data-types/tuple)

**示例**

**基本用法**

```sql title=Query theme={null}
SELECT L1Normalize((1, 2))
```

```response title=Response theme={null}
┌─L1Normalize((1, 2))─────────────────────┐
│ (0.3333333333333333,0.6666666666666666) │
└─────────────────────────────────────────┘
```

<div id="L2Distance">
  ## L2Distance
</div>

引入于：v21.11.0

计算欧几里得空间中两点之间的距离，其中向量的元素表示坐标 ([欧几里得距离](https://en.wikipedia.org/wiki/Euclidean_distance)) 。

**语法**

```sql theme={null}
L2Distance(vector1, vector2)
```

**别名**: `distanceL2`

**参数**

* `vector1` — 第一个向量。[`Tuple(T)`](/zh/reference/data-types/tuple) 或 [`Array(T)`](/zh/reference/data-types/array)
* `vector2` — 第二个向量。[`Tuple(T)`](/zh/reference/data-types/tuple) 或 [`Array(T)`](/zh/reference/data-types/array)

**返回值**

返回 2-范数距离。对于 `Array` 输入，如果元素类型的共同超类型是 `Float32` 或 `BFloat16`，则返回 `Float32`；否则返回 `Float64`。对于 `Tuple` 输入，始终返回 `Float64`。[`Float*`](/zh/reference/data-types/float)

**示例**

**基本用法**

```sql title=Query theme={null}
SELECT L2Distance((1, 2), (2, 3))
```

```response title=Response theme={null}
┌─L2Distance((1, 2), (2, 3))─┐
│         1.4142135623730951 │
└────────────────────────────┘
```

<div id="L2DistanceTransposed">
  ## L2DistanceTransposed
</div>

引入版本：v25.10.0

计算欧几里得空间中两点之间的近似距离 (向量中的值即坐标)  ([欧几里得距离](https://en.wikipedia.org/wiki/Euclidean_distance)) 。

**语法**

```sql theme={null}
L2DistanceTransposed(vector1, vector2, p)
```

**别名**: `distanceL2Transposed`

**参数**

* `vectors` — 向量。[`QBit(T, UInt64)`](/zh/reference/data-types/qbit)
* `reference` — 参考向量。[`Array(T)`](/zh/reference/data-types/array)
* `p` — 在距离计算中，每个向量元素使用的位数 (1 到元素位宽) 。量化级别控制精度与速度之间的权衡。使用较少的位可提升 I/O 和计算速度，但精度会降低；使用较多的位则可提高精度，但会牺牲性能。[`UInt`](/zh/reference/data-types/int-uint)

**返回值**

返回近似的 2-范数距离。始终为 `Float64`。[`Float64`](/zh/reference/data-types/float)

**示例**

**基本用法**

```sql title=Query theme={null}
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 title=Response theme={null}
┌─L2DistanceTransposed([0, 1], [1, 2], 16)─┐
│                       1.4142135623730951 │
└──────────────────────────────────────────┘
```

<div id="L2Norm">
  ## L2Norm
</div>

引入版本：v21.11.0

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

**语法**

```sql theme={null}
L2Norm(vector)
```

**别名**: `normL2`

**参数**

* `vector` — 由数值组成的向量或元组。[`Tuple(T)`](/zh/reference/data-types/tuple) 或 [`Array(T)`](/zh/reference/data-types/array)

**返回值**

返回 L2 范数或 [欧几里得距离](https://en.wikipedia.org/wiki/Euclidean_distance)。[`UInt*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)

**示例**

**基本用法**

```sql title=Query theme={null}
SELECT L2Norm((1, 2))
```

```response title=Response theme={null}
┌───L2Norm((1, 2))─┐
│ 2.23606797749979 │
└──────────────────┘
```

<div id="L2Normalize">
  ## L2Normalize
</div>

引入版本：v21.11.0

计算给定向量在欧几里得空间中的单位向量 (Tuple 中的元素为坐标) ，使用[欧几里得距离](https://en.wikipedia.org/wiki/Euclidean_distance)。

**语法**

```sql theme={null}
L2Normalize(tuple)
```

**别名**: `normalizeL2`

**参数**

* `tuple` — 由数值组成的元组。[`Tuple(T)`](/zh/reference/data-types/tuple)

**返回值**

返回单位向量。[`Tuple(Float64)`](/zh/reference/data-types/tuple)

**示例**

**基本用法**

```sql title=Query theme={null}
SELECT L2Normalize((3, 4))
```

```response title=Response theme={null}
┌─L2Normalize((3, 4))─┐
│ (0.6,0.8)           │
└─────────────────────┘
```

<div id="L2SquaredDistance">
  ## L2SquaredDistance
</div>

引入版本：v22.7.0

计算两个向量中对应元素之差的平方和。

**语法**

```sql theme={null}
L2SquaredDistance(vector1, vector2)
```

**别名**: `distanceL2Squared`

**参数**

* `vector1` — 第一个向量。[`Tuple(T)`](/zh/reference/data-types/tuple) 或 [`Array(T)`](/zh/reference/data-types/array)
* `vector2` — 第二个向量。[`Tuple(T)`](/zh/reference/data-types/tuple) 或 [`Array(T)`](/zh/reference/data-types/array)

**返回值**

返回两个向量对应元素之差的平方和。对于 `Array` 输入，如果元素类型的最小共同超类型为 `Float32` 或 `BFloat16`，则返回 `Float32`，否则返回 `Float64`。对于 `Tuple` 输入，返回类型遵循逐元素运算的算术结果类型 (保留整数类型) 。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)

**示例**

**基本用法**

```sql title=Query theme={null}
SELECT L2SquaredDistance([1, 2, 3], [0, 0, 0])
```

```response title=Response theme={null}
┌─L2SquaredDis⋯ [0, 0, 0])─┐
│                       14 │
└──────────────────────────┘
```

<div id="L2SquaredNorm">
  ## L2SquaredNorm
</div>

引入版本：v22.7.0

计算向量元素平方和的平方根 ([`L2Norm`](#L2Norm)) 的平方。

**语法**

```sql theme={null}
L2SquaredNorm(vector)
```

**别名**: `normL2Squared`

**参数**

* `vector` — 由数值组成的向量或元组。[`Array(T)`](/zh/reference/data-types/array) 或 [`Tuple(T)`](/zh/reference/data-types/tuple)

**返回值**

返回 L2 范数的平方。[`UInt*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`Decimal`](/zh/reference/data-types/decimal)

**示例**

**基本用法**

```sql title=Query theme={null}
SELECT L2SquaredNorm((1, 2))
```

```response title=Response theme={null}
┌─L2SquaredNorm((1, 2))─┐
│                     5 │
└───────────────────────┘
```

<div id="LinfDistance">
  ## LinfDistance
</div>

引入版本：v21.11.0

计算 `L_{inf}` 空间中两点之间的距离 (向量中的元素为坐标)  ([最大范数](https://en.wikipedia.org/wiki/Norm_\(mathematics\)#Maximum_norm_\(special_case_of:_infinity_norm,_uniform_norm,_or_supremum_norm\))) 。

**语法**

```sql theme={null}
LinfDistance(vector1, vector2)
```

**别名**: `distanceLinf`

**参数**

* `vector1` — 第一个向量。[`Tuple(T)`](/zh/reference/data-types/tuple) 或 [`Array(T)`](/zh/reference/data-types/array)
* `vector2` — 第二个向量。[`Tuple(T)`](/zh/reference/data-types/tuple) 或 [`Array(T)`](/zh/reference/data-types/array)

**返回值**

返回无穷范数距离。对于 `Array` 输入，如果元素类型的最小共同超类型为 `Float32` 或 `BFloat16`，则返回 `Float32`；否则返回 `Float64`。对于 `Tuple` 输入，始终返回 `Float64`。[`Float*`](/zh/reference/data-types/float)

**示例**

**基本用法**

```sql title=Query theme={null}
SELECT LinfDistance((1, 2), (2, 3))
```

```response title=Response theme={null}
┌─LinfDistance((1, 2), (2, 3))─┐
│                            1 │
└──────────────────────────────┘
```

<div id="LinfNorm">
  ## LinfNorm
</div>

引入版本：v21.11.0

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

**语法**

```sql theme={null}
LinfNorm(vector)
```

**别名**: `normLinf`

**参数**

* `vector` — 由数值组成的向量或元组。[`Array(T)`](/zh/reference/data-types/array) 或 [`Tuple(T)`](/zh/reference/data-types/tuple)

**返回值**

返回 Linf 范数，即最大绝对值。[`Float64`](/zh/reference/data-types/float)

**示例**

**基本用法**

```sql title=Query theme={null}
SELECT LinfNorm((1, -2))
```

```response title=Response theme={null}
┌─LinfNorm((1, -2))─┐
│                 2 │
└───────────────────┘
```

<div id="LinfNormalize">
  ## LinfNormalize
</div>

引入版本：v21.11.0

计算给定向量在 `L_{inf}` 空间中的单位向量 (Tuple 中的元素为各坐标) ，使用[最大范数](https://en.wikipedia.org/wiki/Norm_\(mathematics\)#Maximum_norm_\(special_case_of:_infinity_norm,_uniform_norm,_or_supremum_norm\))。

**语法**

```sql theme={null}
LinfNormalize(tuple)
```

**别名**: `normalizeLinf`

**参数**

* `tuple` — 由数值组成的元组。[`Tuple(T)`](/zh/reference/data-types/tuple)

**返回值**

返回单位向量。[`Tuple(Float64)`](/zh/reference/data-types/tuple)

**示例**

**基本用法**

```sql title=Query theme={null}
SELECT LinfNormalize((3, 4))
```

```response title=Response theme={null}
┌─LinfNormalize((3, 4))─┐
│ (0.75,1)              │
└───────────────────────┘
```

<div id="LpDistance">
  ## LpDistance
</div>

引入版本：v21.11.0

计算 `Lp` 空间中两点之间的距离 (向量中的元素为坐标)  ([p-范数距离](https://en.wikipedia.org/wiki/Norm_\(mathematics\)#p-norm)) 。

**语法**

```sql theme={null}
LpDistance(vector1, vector2, p)
```

**别名**: `distanceLp`

**参数**

* `vector1` — 第一个向量。[`Tuple(T)`](/zh/reference/data-types/tuple) 或 [`Array(T)`](/zh/reference/data-types/array)
* `vector2` — 第二个向量。[`Tuple(T)`](/zh/reference/data-types/tuple) 或 [`Array(T)`](/zh/reference/data-types/array)
* `p` — 幂次。可能的值：`[1; inf)` 范围内的实数。[`UInt*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)

**返回值**

返回 p-范数距离。对于 `Array` 输入，如果元素类型的最小共同超类型为 `Float32` 或 `BFloat16`，则返回 `Float32`，否则返回 `Float64`。对于 `Tuple` 输入，始终返回 `Float64`。[`Float*`](/zh/reference/data-types/float)

**示例**

**基本用法**

```sql title=Query theme={null}
SELECT LpDistance((1, 2), (2, 3), 3)
```

```response title=Response theme={null}
┌─LpDistance((1, 2), (2, 3), 3)─┐
│            1.2599210498948732 │
└───────────────────────────────┘
```

<div id="LpNorm">
  ## LpNorm
</div>

引入版本：v21.11.0

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

特殊情况：

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

**语法**

```sql theme={null}
LpNorm(vector, p)
```

**别名**: `normLp`

**参数**

* `vector` — 由数值组成的向量或元组。[`Tuple(T)`](/zh/reference/data-types/tuple) 或 [`Array(T)`](/zh/reference/data-types/array)
* `p` — 幂指数。可能的值为范围 `[1; inf)` 内的实数。[`UInt*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)

**返回值**

返回 [Lp 范数](https://en.wikipedia.org/wiki/Norm_\(mathematics\)#p-norm)。[`Float64`](/zh/reference/data-types/float)

**示例**

**基本用法**

```sql title=Query theme={null}
SELECT LpNorm((1, -2), 2)
```

```response title=Response theme={null}
┌─LpNorm((1, -2), 2)─┐
│   2.23606797749979 │
└────────────────────┘
```

<div id="LpNormalize">
  ## LpNormalize
</div>

在以下版本中引入：v21.11.0

计算给定向量在 `Lp` 空间中的单位向量 (Tuple 中的元素为坐标) ，使用 [p-norm](https://en.wikipedia.org/wiki/Norm_\(mathematics\)#p-norm)。

**语法**

```sql theme={null}
LpNormalize(tuple, p)
```

**别名**: `normalizeLp`

**参数**

* `tuple` — 由数值组成的元组。[`Tuple(T)`](/zh/reference/data-types/tuple)
* `p` — 幂。可能的值为 `[1; inf)` 范围内的任意数字。[`UInt*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)

**返回值**

返回单位向量。[`Tuple(Float64)`](/zh/reference/data-types/tuple)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT LpNormalize((3, 4), 5)
```

```response title=Response theme={null}
┌─LpNormalize((3, 4), 5)──────────────────┐
│ (0.7187302630182624,0.9583070173576831) │
└─────────────────────────────────────────┘
```

<div id="cosineDistance">
  ## cosineDistance
</div>

引入版本：v21.11.0

计算两个向量之间的[余弦距离](https://en.wikipedia.org/wiki/Cosine_similarity#Cosine_distance) (元组中的元素为坐标) 。返回值越小，两个向量就越相似。

**语法**

```sql theme={null}
cosineDistance(vector1, vector2)
```

**别名**: `distanceCosine`

**参数**

* `vector1` — 第一个向量。[`Tuple(T)`](/zh/reference/data-types/tuple) 或 [`Array(T)`](/zh/reference/data-types/array)
* `vector2` — 第二个向量。[`Tuple(T)`](/zh/reference/data-types/tuple) 或 [`Array(T)`](/zh/reference/data-types/array)

**返回值**

返回余弦距离 (即 1 减去余弦相似度) 。对于 `Array` 输入，如果元素类型的共同超类型为 `Float32` 或 `BFloat16`，则返回 `Float32`，否则返回 `Float64`。对于 `Tuple` 输入，始终返回 `Float64`。[`Float*`](/zh/reference/data-types/float)

**示例**

**基本用法**

```sql title=Query theme={null}
SELECT cosineDistance((1, 2), (2, 3));
```

```response title=Response theme={null}
┌─cosineDistance((1, 2), (2, 3))─┐
│           0.007722123286332261 │
└────────────────────────────────┘
```

<div id="cosineDistanceTransposed">
  ## cosineDistanceTransposed
</div>

Introduced in：v26.1.0

计算两个点之间的近似[余弦距离](https://en.wikipedia.org/wiki/Cosine_similarity#Cosine_distance) (向量的值即为坐标) 。返回值越小，向量越相似。

**Syntax**

```sql theme={null}
cosineDistanceTransposed(vector1, vector2, p)
```

**别名**: `distanceCosineTransposed`

**参数**

* `vectors` — 向量。[`QBit(T, UInt64)`](/zh/reference/data-types/qbit)
* `reference` — 参考向量。[`Array(T)`](/zh/reference/data-types/array)
* `p` — 在距离计算中，每个向量元素使用的位数 (从 1 到元素位宽) 。量化级别控制精度与速度之间的权衡。使用较少的位可加快 I/O 和计算速度，但会降低准确性；使用较多的位可提高准确性，但会牺牲性能。[`UInt`](/zh/reference/data-types/int-uint)

**返回值**

返回近似余弦距离 (即 1 减去余弦相似度) 。始终返回 Float64。[`Float64`](/zh/reference/data-types/float)

**示例**

**基本用法**

```sql title=Query theme={null}
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 title=Response theme={null}
┌─cosineDistanceTransposed([0, 1], [1, 2], 16)─┐
│                          0.10557281085638826 │
└──────────────────────────────────────────────┘
```