| title | 向量函数与运算符 | |||
|---|---|---|---|---|
| summary | 了解可用于向量数据类型的函数与运算符。 | |||
| aliases |
|
本文档列出了可用于向量数据类型的函数与运算符。
注意：
- 向量函数与运算符目前为 Beta 版本，可能会在未提前通知的情况下发生变更。如果你发现了 bug，可以在 GitHub 上提交 issue。
- 向量数据类型及这些向量函数适用于 TiDB 自托管、TiDB Cloud Starter、TiDB Cloud Essential 和 TiDB Cloud Dedicated。对于 TiDB 自托管和 TiDB Cloud Dedicated，TiDB 版本需为 v8.4.0 或更高（推荐 v8.5.0 或更高）。
以下函数专为 向量数据类型 设计。
向量距离函数：
| 函数名 | 描述 | 向量索引支持 |
|---|---|---|
VEC_L2_DISTANCE |
计算两个向量之间的 L2 距离（欧氏距离） | 是 |
VEC_COSINE_DISTANCE |
计算两个向量之间的余弦距离 | 是 |
VEC_NEGATIVE_INNER_PRODUCT |
计算两个向量内积的相反数 | 否 |
VEC_L1_DISTANCE |
计算两个向量之间的 L1 距离（曼哈顿距离） | 否 |
其他向量函数：
| 函数名 | 描述 |
|---|---|
VEC_DIMS |
返回向量的维度 |
VEC_L2_NORM |
计算向量的 L2 范数（欧氏范数） |
VEC_FROM_TEXT |
将字符串转换为向量 |
VEC_AS_TEXT |
将向量转换为字符串 |
以下内置函数与运算符已扩展以支持对 向量数据类型 的操作。
算术运算符：
| 名称 | 描述 |
|---|---|
+ |
向量按元素加法运算符 |
- |
向量按元素减法运算符 |
关于向量算术运算的更多信息，参见 向量数据类型 | 算术运算。
聚合（GROUP BY）函数：
| 名称 | 描述 |
|---|---|
COUNT() |
返回结果行数 |
COUNT(DISTINCT) |
返回不同值的数量 |
MAX() |
返回最大值 |
MIN() |
返回最小值 |
比较函数与运算符：
| 名称 | 描述 |
|---|---|
BETWEEN ... AND ... |
检查值是否在某个范围内 |
COALESCE() |
返回第一个非空值参数 |
= |
等于运算符 |
<=> |
NULL 安全等于运算符 |
> |
大于运算符 |
>= |
大于等于运算符 |
GREATEST() |
返回最大参数 |
IN() |
检查值是否在某个集合中 |
IS NULL |
测试值是否为 NULL |
ISNULL() |
测试参数是否为 NULL |
LEAST() |
返回最小参数 |
< |
小于运算符 |
<= |
小于等于运算符 |
NOT BETWEEN ... AND ... |
检查值是否不在某个范围内 |
!=, <> |
不等于运算符 |
NOT IN() |
检查值是否不在某个集合中 |
关于向量比较的更多信息，参见 向量数据类型 | 比较。
流程控制函数：
| 名称 | 描述 |
|---|---|
CASE |
CASE 运算符 |
IF() |
if/else 结构 |
IFNULL() |
null if/else 结构 |
NULLIF() |
如果 expr1 = expr2 则返回 NULL |
类型转换函数：
| 名称 | 描述 |
|---|---|
CAST() |
将值转换为字符串或向量 |
CONVERT() |
将值转换为字符串 |
关于如何使用 CAST() 的更多信息，参见 向量数据类型 | 类型转换。
VEC_L2_DISTANCE(vector1, vector2)使用以下公式计算两个向量之间的 L2 距离（欧氏距离）：
$DISTANCE(p,q)=\sqrt {\sum \limits {i=1}^{n}{(p{i}-q_{i})^{2}}}$
两个向量必须具有相同的维度，否则会返回错误。
示例：
SELECT VEC_L2_DISTANCE('[0, 3]', '[4, 0]');+-------------------------------------+
| VEC_L2_DISTANCE('[0, 3]', '[4, 0]') |
+-------------------------------------+
| 5 |
+-------------------------------------+
VEC_COSINE_DISTANCE(vector1, vector2)使用以下公式计算两个向量之间的 余弦距离：
$DISTANCE(p,q)=1.0 - {\frac {\sum \limits {i=1}^{n}{p{i}q_{i}}}{{\sqrt {\sum \limits {i=1}^{n}{p{i}^{2}}}}\cdot {\sqrt {\sum \limits {i=1}^{n}{q{i}^{2}}}}}}$
两个向量必须具有相同的维度，否则会返回错误。
对于来自 OpenAI 的 embedding，推荐使用此函数。
示例：
SELECT VEC_COSINE_DISTANCE('[1, 1]', '[-1, -1]');+-------------------------------------------+
| VEC_COSINE_DISTANCE('[1, 1]', '[-1, -1]') |
+-------------------------------------------+
| 2 |
+-------------------------------------------+
VEC_NEGATIVE_INNER_PRODUCT(vector1, vector2)使用以下公式，通过计算两个向量 内积 的相反数来计算距离：
$DISTANCE(p,q)=- INNER_PROD(p,q)=-\sum \limits {i=1}^{n}{p{i}q_{i}}$
两个向量必须具有相同的维度，否则会返回错误。
示例：
SELECT VEC_NEGATIVE_INNER_PRODUCT('[1, 2]', '[3, 4]');+------------------------------------------------+
| VEC_NEGATIVE_INNER_PRODUCT('[1, 2]', '[3, 4]') |
+------------------------------------------------+
| -11 |
+------------------------------------------------+
VEC_L1_DISTANCE(vector1, vector2)使用以下公式计算两个向量之间的 L1 距离（曼哈顿距离）：
$DISTANCE(p,q)=\sum \limits {i=1}^{n}{|p{i}-q_{i}|}$
两个向量必须具有相同的维度，否则会返回错误。
示例：
SELECT VEC_L1_DISTANCE('[0, 0]', '[3, 4]');+-------------------------------------+
| VEC_L1_DISTANCE('[0, 0]', '[3, 4]') |
+-------------------------------------+
| 7 |
+-------------------------------------+
VEC_DIMS(vector)返回向量的维度。
示例：
SELECT VEC_DIMS('[1, 2, 3]');+-----------------------+
| VEC_DIMS('[1, 2, 3]') |
+-----------------------+
| 3 |
+-----------------------+
SELECT VEC_DIMS('[]');+----------------+
| VEC_DIMS('[]') |
+----------------+
| 0 |
+----------------+
VEC_L2_NORM(vector)使用以下公式计算向量的 L2 范数（欧氏范数）：
$NORM(p)=\sqrt {\sum \limits {i=1}^{n}{p{i}^{2}}}$
示例：
SELECT VEC_L2_NORM('[3, 4]');+-----------------------+
| VEC_L2_NORM('[3, 4]') |
+-----------------------+
| 5 |
+-----------------------+
VEC_FROM_TEXT(string)将字符串转换为向量。在许多场景下，此转换会被隐式执行，例如向 VECTOR 数据类型的列插入数据时。然而，在某些不支持隐式转换的表达式中（如向量的算术运算），你需要显式调用此函数。
示例：
SELECT VEC_FROM_TEXT('[1, 2]') + VEC_FROM_TEXT('[3, 4]');+-------------------------------------------------+
| VEC_FROM_TEXT('[1,2]') + VEC_FROM_TEXT('[3,4]') |
+-------------------------------------------------+
| [4,6] |
+-------------------------------------------------+
VEC_AS_TEXT(vector)将向量转换为字符串。
示例：
SELECT VEC_AS_TEXT('[1.000, 2.5]');+-----------------------------+
| VEC_AS_TEXT('[1.000, 2.5]') |
+-----------------------------+
| [1,2.5] |
+-----------------------------+
向量函数以及内置函数和运算符在向量数据类型上的扩展用法为 TiDB 特有，MySQL 不支持。