首批通过分布式安全可靠测评，为关键业务系统打造
使用 SQL 函数
更新时间：2026-07-04 14:05:58
编辑
分享
本文介绍了 OceanBase 支持的向量函数及使用注意事项。
使用注意事项
- 维度不同的向量数据不允许做下述运算，会报错
different vector dimensions %d and %d。 - 当结果超出浮点数值域时，会报错
value out of range: overflow / underflow。 - 稠密向量索引支持 L2、内积（Inner Product）、余弦距离作为索引距离算法。具体请参见HNSW 系列索引和IVF 系列索引；稀疏向量索引支持内积和负内积（Negative Inner Product）作为索引距离算法。
- 向量索引搜索支持调用本文档中的
L2_distance、Cosine_distance、Inner_product、Negative_inner_product距离函数，以及inner_product_similarity、cosine_similarity、l2_similarity相似度函数。
距离函数
距离函数用于计算两个向量之间的距离，具体计算方式依据不同的距离算法而不同。
L2_distance
欧几里得距离反映的是被比较的向量坐标之间的距离--基本上是两个向量之间的直线距离。使用勾股定理应用于向量坐标来计算：
函数语法如下：
l2_distance(vector v1, vector v2)
参数说明如下：
除了向量类型外，参数可接受任意可强转为向量类型的其他类型，如字符串类型（如
'[1,2,3]'）。两个参数的维度必须相同。
当存在单级数组类型参数时，该参数元素不允许出现
NULL。
返回值说明如下：
返回值为
distance(double)距离值。当任意参数为
NULL时，返回NULL。
示例如下：
CREATE TABLE t1(c1 vector(3));
INSERT INTO t1 VALUES('[1,2,3]');
SELECT l2_distance(c1, [1,2,3]), l2_distance([1,2,3],[1,1,1]), l2_distance('[1,1,1]','[1,2,3]') FROM t1;
返回结果如下：
+--------------------------+------------------------------+----------------------------------+
| l2_distance(c1, [1,2,3]) | l2_distance([1,2,3],[1,1,1]) | l2_distance('[1,1,1]','[1,2,3]') |
+--------------------------+------------------------------+----------------------------------+
| 0 | 2.23606797749979 | 2.23606797749979 |
+--------------------------+------------------------------+----------------------------------+
1 row in set
L2_squared
L2 Squared 距离是欧几里得距离（L2 Distance）的平方。它省略了欧几里得距离公式中的平方根运算，从而在保持距离相对顺序不变的前提下，降低了计算成本。计算方式为：
语法如下：
l2_squared(vector v1, vector v2)
参数说明如下：
除了向量类型外，参数可接受任意可强转为向量类型的其他类型，如字符串类型（如
'[1,2,3]'）。两个参数的维度必须相同。
当存在单级数组类型参数时，该参数元素不允许出现
NULL。
返回值说明如下：
返回值为
distance(double)距离值。当任意参数为
NULL时，返回NULL。
示例如下：
CREATE TABLE t1(c1 vector(3));
INSERT INTO t1 VALUES('[1,2,3]');
SELECT l2_squared(c1, [1,2,3]), l2_squared([1,2,3],[1,1,1]), l2_squared('[1,1,1]','[1,2,3]') FROM t1;
返回结果如下：
+-------------------------+-----------------------------+---------------------------------+
| l2_squared(c1, [1,2,3]) | l2_squared([1,2,3],[1,1,1]) | l2_squared('[1,1,1]','[1,2,3]') |
+-------------------------+-----------------------------+---------------------------------+
| 0 | 5 | 5 |
+-------------------------+-----------------------------+---------------------------------+
1 row in set
L1_distance
曼哈顿距离用于计算两个点在标准的坐标系中的绝对轴距总和。计算公式为：
函数语法如下：
l1_distance(vector v1, vector v2)
参数说明如下：
除了向量类型外，参数可接受任意可强转为向量类型的其他类型，如字符串类型（如
'[1,2,3]'）。两个参数的维度必须相同。
当存在单级数组类型参数时，该参数元素不允许出现
NULL。
返回值说明如下：
返回值为
distance(double)距离值。当任意参数为
NULL时，返回NULL。
示例如下：
CREATE TABLE t2(c1 vector(3));
INSERT INTO t2 VALUES('[1,2,3]');
INSERT INTO t2 VALUES('[1,1,1]');
SELECT l1_distance(c1, [1,2,3]) FROM t2;
返回结果如下：
+--------------------------+
| l1_distance(c1, [1,2,3]) |
+--------------------------+
| 0 |
| 3 |
+--------------------------+
2 rows in set
Cosine_distance
余弦相似度（cosine similarity）是衡量两个向量的角度差异，它反映了两个向量在方向上的相似度，与向量的长度（大小）无关。余弦相似度的取值范围为 [-1, 1]，其中 1 表示向量完全相同的方向，0 表示正交，-1 表示完全相反的方向。
余弦相似度的计算方式为：
由于余弦相似度度量越接近于 1 表示越相似，因此有时也使用余弦距离（或余弦不相似度）作为向量间距离的一种衡量方式，余弦距离可以通过 1 减去余弦相似度来计算：
余弦距离的取值范围是 [0, 2]，其中 0 表示完全相同的方向（无距离），而 2 表示完全相反的方向。
函数语法如下：
cosine_distance(vector v1, vector v2)
参数说明如下：
除了向量类型外，参数可接受任意可强转为向量类型的其他类型，如字符串类型（如
'[1,2,3]'）。两个参数的维度必须相同。
当存在单级数组类型参数时，该参数元素不允许出现
NULL。
返回值说明如下：
返回值为
distance(double)距离值。当任意参数为
NULL时，返回NULL。
示例如下：
CREATE TABLE t3(c1 vector(3));
INSERT INTO t3 VALUES('[1,2,3]');
INSERT INTO t3 VALUES('[1,2,1]');
SELECT cosine_distance(c1, [1,2,3]) FROM t3;
+------------------------------+
| cosine_distance(c1, [1,2,3]) |
+------------------------------+
| 0 |
| 0.12712843905603044 |
+------------------------------+
2 rows in set
Inner_product
内积又称为点积或数量积，表示两个向量之间的一种乘积。在几何意义上，内积表示两个向量的方向关系和大小关系。内积的计算方式为：
语法如下：
inner_product(vector v1, vector v2)
参数说明如下：
除了向量类型外，参数可接受任意可强转为向量类型的其他类型，如字符串类型（如
'[1,2,3]'）。两个参数的维度必须相同。
当存在单级数组类型参数时，该参数元素不允许出现
NULL。稀疏向量使用此函数时，支持其中一个参数为稀疏向量格式的字符串，如
c2,'{1:2.4}'；不支持两个参数均为字符串。
返回值说明如下：
返回值为
distance(double)距离值。当任意参数为
NULL时，返回NULL。
稠密向量示例如下：
CREATE TABLE t4(c1 vector(3));
INSERT INTO t4 VALUES('[1,2,3]');
INSERT INTO t4 VALUES('[1,2,1]');
SELECT inner_product(c1, [1,2,3]) FROM t4;
返回结果如下：
+----------------------------+
| inner_product(c1, [1,2,3]) |
+----------------------------+
| 14 |
| 8 |
+----------------------------+
2 rows in set
稀疏向量示例如下：
CREATE TABLE t4(c1 INT, c2 SPARSEVECTOR, c3 SPARSEVECTOR);
INSERT INTO t4 VALUES(1, '{1:1.1, 2:2.2}', '{1:2.4}');
INSERT INTO t4 VALUES(2, '{1:1.5, 3:3.6}', '{4:4.5}'));
SELECT inner_product(c2,c3) FROM t4;
返回结果如下：
```shell
+----------------------+
| inner_product(c2,c3) |
+----------------------+
| 2.640000104904175 |
| 0 |
+----------------------+
2 rows in set
Negative_inner_product
Negative_inner_product 用于计算两个向量之间的负内积，计算方式为：
语法如下：
negative_inner_product(vector v1, vector v2)
参数说明如下：
除了向量类型外，参数可接受任意可强转为向量类型的其他类型，如字符串类型（如
'[1,2,3]'）。两个参数的维度必须相同。
当存在单级数组类型参数时，该参数元素不允许出现
NULL。稀疏向量使用此函数时，支持其中一个参数为稀疏向量格式的字符串，如
c2,'{1:2.4}'；不支持两个参数均为字符串。
返回值说明如下：
返回值为
distance(double)距离值。当任意参数为
NULL时，返回NULL。
稠密向量示例如下：
CREATE TABLE t5(c1 vector(3));
INSERT INTO t5 VALUES('[1,2,3]');
INSERT INTO t5 VALUES('[1,2,1]');
SELECT negative_inner_product(c1, [1,2,3]) FROM t5;
返回结果如下：
+-------------------------------------+
| negative_inner_product(c1, [1,2,3]) |
+-------------------------------------+
| -14 |
| -8 |
| -14 |
| -8 |
+-------------------------------------+
4 rows in set
稀疏向量示例如下：
CREATE TABLE t5(c1 INT, c2 SPARSEVECTOR, c3 SPARSEVECTOR);
INSERT INTO t5 VALUES(1, '{1:1.1, 2:2.2}', '{1:2.4}');
INSERT INTO t5 VALUES(2, '{1:1.5, 3:3.6}', '{4:4.5}'));
SELECT negative_inner_product(c2,c3) FROM t5;
返回结果如下：
+-------------------------------+
| negative_inner_product(c2,c3) |
+-------------------------------+
| -2.640000104904175 |
| 0 |
+-------------------------------+
2 rows in set
Vector_distance
vector_distance 用于计算两个向量之间的距离，通过指定参数来选择不同的距离算法。
语法如下：
vector_distance(vector v1, vector v2 [, string metric])
vector v1/v2 参数说明如下：
除了向量类型外，参数可接受任意可强转为向量类型的其他类型，如字符串类型（如
'[1,2,3]'）。两个参数的维度必须相同。
当存在单级数组类型参数时，该参数元素不允许出现
NULL。
metric 参数用于指定距离算法，可选：
如果不指定，默认算法为
euclidean。如果指定，可选择的值有且只有
euclidean。表示欧式距离，和 L2_distance 含义相同。manhattan。表示曼哈顿距离，和 L1_distance 含义相同。cosine。表示余弦距离，和 Cosine_distance 含义相同。dot。表示内积，和 Inner_product 含义相同。
返回值说明如下：
返回值为
distance(double)距离值。当任意参数为
NULL时，返回NULL。
示例如下：
CREATE TABLE t5(c1 vector(3));
INSERT INTO t5 VALUES('[1,2,3]');
INSERT INTO t5 VALUES('[1,2,1]');
SELECT vector_distance(c1, [1,2,3], euclidean) FROM t5;
返回结果如下：
+-----------------------------------------+
| vector_distance(c1, [1,2,3], euclidean) |
+-----------------------------------------+
| 0 |
| 2 |
+-----------------------------------------+
2 rows in set
相似度函数
相似度函数用于衡量两个向量的相似程度，其值越大表示向量越相似。它与距离函数互为反向概念：相似度越高，距离越小。在向量搜索中，可以通过设置相似度阈值来筛选出满足条件的结果。
inner_product_similarity
inner_product_similarity 用于计算两个向量之间的内积相似度。函数返回值计算方式与内积距离函数 inner_product 相同，但返回值表示相似度而非距离。与 inner_product 之间的的换算方式为：inner_product_similarity(v1, v2) = (1 + inner_product(v1, v2) / (vector_norm(v1) * vector_norm(v2))) / 2。vector_norm 函数用于计算向量的欧几里得范数（模），表示向量和原点之间的欧几里得距离。对于向量 v = [v1, v2, v3, ..., vn]，其范数计算公式为：vector_norm(v) = √(v1² + v2² + v3² + ... + vn²)。
语法如下：
inner_product_similarity(vector v1, vector v2)
参数说明如下：
- 除了向量类型外，参数可接受任意可强转为向量类型的其他类型，如字符串类型（如
'[1,2,3]'）。 - 两个参数的维度必须相同。
- 当存在单级数组类型参数时，该参数元素不允许出现
NULL。
返回值说明如下：
- 返回值类型为 double，返回结果为两个向量的相似度值，值越大表示越相似。
- 当任意参数为
NULL时，返回NULL。
示例如下：
CREATE TABLE t12(c1 vector(3));
INSERT INTO t12 VALUES('[1,2,3]');
INSERT INTO t12 VALUES('[1,2,1]');
SELECT inner_product_similarity(c1, [1,2,3]) FROM t12;
返回结果如下：
+---------------------------------------+
| inner_product_similarity(c1, [1,2,3]) |
+---------------------------------------+
| 0.9999999552965164 |
| 0.9364357516169548 |
+---------------------------------------+
2 rows in set
或者更简单的：
SELECT inner_product_similarity([1,0,0], [0,1,0]);
返回结果如下：
+--------------------------------------------+
| inner_product_similarity([1,0,0], [0,1,0]) |
+--------------------------------------------+
| 0.5 |
+--------------------------------------------+
1 row in set
cosine_similarity
cosine_similarity 用于计算两个向量之间的余弦相似度，反映两个向量在方向上的相似度，与向量的长度（大小）无关。计算方式为：cosine_similarity(v1, v2) = 1 - (cosine_distance(v1, v2) / 2)。
语法如下：
cosine_similarity(vector v1, vector v2)
参数说明如下：
- 除了向量类型外，参数可接受任意可强转为向量类型的其他类型，如字符串类型（如
'[1,2,3]'）。 - 两个参数的维度必须相同。
- 当存在单级数组类型参数时，该参数元素不允许出现
NULL。
返回值说明如下：
- 返回值类型为 double，结果范围为
[0, 1]，其中1表示两个向量方向完全一致，0表示两个向量正交。数值越大代表方向越相似。 - 当任意参数为
NULL时，返回NULL。
示例如下：
CREATE TABLE t13(c1 vector(3));
INSERT INTO t13 VALUES('[1,2,3]');
INSERT INTO t13 VALUES('[1,2,1]');
SELECT cosine_similarity(c1, [1,2,3]) FROM t13;
返回结果如下：
+--------------------------------+
| cosine_similarity(c1, [1,2,3]) |
+--------------------------------+
| 0.9999999552965164 |
| 0.9364357516169548 |
+--------------------------------+
2 rows in set
或者更简单的：
SELECT cosine_similarity([1,0,0], [0,1,0]);
返回结果如下：
+-------------------------------------+
| cosine_similarity([1,0,0], [0,1,0]) |
+-------------------------------------+
| 0.5 |
+-------------------------------------+
1 row in set
l2_similarity
l2_similarity 用于计算两个向量之间的 L2 相似度。L2 相似度基于欧几里得距离，但返回值表示相似度而非距离。相似度值越大表示两个向量越相似。与 l2_squared 的换算为：l2_similarity(v1, v2) = 1 / (1 + l2_squared(v1, v2))。
语法如下：
l2_similarity(vector v1, vector v2)
参数说明如下：
- 除了向量类型外，参数可接受任意可强转为向量类型的其他类型，如字符串类型（如
'[1,2,3]'）。 - 两个参数的维度必须相同。
- 当存在单级数组类型参数时，该参数元素不允许出现
NULL。
返回值说明如下：
- 返回值类型为 double，返回结果为两个向量的相似度值，值越大表示越相似。
- 当任意参数为
NULL时，返回NULL。
示例如下：
CREATE TABLE t14(c1 vector(3));
INSERT INTO t14 VALUES('[1,2,3]');
INSERT INTO t14 VALUES('[1,2,1]');
SELECT l2_similarity(c1, [1,2,3]) FROM t14;
返回结果如下：
+----------------------------+
| l2_similarity(c1, [1,2,3]) |
+----------------------------+
| 1 |
| 0.2 |
+----------------------------+
2 rows in set
或者更简单的：
SELECT l2_similarity([1,0,0], [0,1,0]);
返回结果如下：
+---------------------------------+
| l2_similarity([1,0,0], [0,1,0]) |
+---------------------------------+
| 0.3333333333333333 |
+---------------------------------+
1 row in set
算术函数
算术函数提供向量类型与向量类型、单级数组类型、特殊字符串类型，以及单级数组类型与单级数组类型、特殊字符串类型的加（+）、减（-）和乘（*）法算术计算。计算方式为逐元素计算，如加法计算为：
语法如下：
v1 + v2
v1 - v2
v1 * v2
参数说明如下：
除了向量类型外，参数可接受任意可强转为向量类型的其他类型，如字符串类型（如
'[1,2,3]'）。**注意：**两个参数不可以同时为字符串类型，必须有一个参数为向量类型。两个参数的维度必须相同。
当存在单级数组类型参数时，该参数元素不允许出现
NULL。
返回值说明如下：
当两个参数中至少有一个参数为向量类型时，返回值为和向量参数相同的向量类型。
当两个参数中只有单级数组类型时，返回值为
array(float)类型。当任意参数为
NULL时，返回NULL。
示例如下：
CREATE TABLE t6(c1 vector(3));
INSERT INTO t6 VALUES('[1,2,3]');
SELECT [1,2,3] + '[1.12,1000.0001, -1.2222]', c1 - [1,2,3] FROM t6;
返回结果如下：
+---------------------------------------+--------------+
| [1,2,3] + '[1.12,1000.0001, -1.2222]' | c1 - [1,2,3] |
+---------------------------------------+--------------+
| [2.12,1002,1.7778] | [0,0,0] |
+---------------------------------------+--------------+
1 row in set
比较函数
比较函数提供向量类型与向量类型、单级数组类型、特殊字符串类型的比较计算，包括 =、!=、>、<、>=、<= 几种比较符号。计算方式为逐元素的字典序比较。
语法如下：
v1 = v2
v1 != v2
v1 > v2
v1 < v2
v1 >= v2
v1 <= v2
参数说明如下：
除了向量类型外，参数可接受任意可强转为向量类型的其他类型，如字符串类型（如
'[1,2,3]'）。注意
两个参数必须有一个参数为向量类型。
两个参数的维度必须相同。
当存在单级数组类型参数时，该参数元素不允许出现
NULL。
返回值说明如下：
返回值为 bool 类型。
当任意参数为
NULL时，返回NULL。
示例如下：
CREATE TABLE t7(c1 vector(3));
INSERT INTO t7 VALUES('[1,2,3]');
SELECT c1 = '[1,2,3]' FROM t7;
返回结果如下：
+----------------+
| c1 = '[1,2,3]' |
+----------------+
| 1 |
+----------------+
1 row in set
聚合函数
注意
不支持使用向量列作为 GROUP BY 条件，不支持 DISTINCT。
Sum
Sum 函数用于计算表中向量列的和，采用逐元素累加的方式进行计算，以得到和向量。
语法如下：
sum(vector v1)
参数说明如下：
- 仅支持向量类型。
返回值说明如下：
- 返回
sum (vector)值。
示例如下：
CREATE TABLE t8(c1 vector(3));
INSERT INTO t8 VALUES('[1,2,3]'),('[2,3,4]'),('[3,4,5]');
SELECT sum(c1) FROM t8;
返回结果如下：
+---------+
| sum(c1) |
+---------+
| [6,9,12] |
+---------+
1 row in set
多行向量逐元素相加：第 1 维 1+2+3=6，第 2 维 2+3+4=9，第 3 维 3+4+5=12，因此和为 [6,9,12]。
Avg
Avg 函数用于计算表中向量列的平均值。
语法如下：
avg(vector v1)
参数说明如下：
- 仅支持向量类型。
返回值说明如下：
返回
avg (vector)值。不计入该向量列中的
NULL行。输入参数为空时，输出
NULL。
示例如下：
CREATE TABLE t9(c1 vector(3));
INSERT INTO t9 VALUES('[2,4,6]'),('[4,6,8]'),('[6,8,10]');
SELECT avg(c1) FROM t9;
返回结果如下：
+---------+
| avg(c1) |
+---------+
| [4,6,8] |
+---------+
1 row in set
多行向量逐元素求平均：第 1 维 (2+4+6)/3=4，第 2 维 (4+6+8)/3=6，第 3 维 (6+8+10)/3=8，因此平均值为 [4,6,8]。
其他常见向量函数
Vector_norm
Vector_norm 函数用于计算向量的欧几里得范数（模），表示向量和原点之间的欧几里得距离。计算方式为：
语法如下：
vector_norm(vector v1)
参数说明如下：
除了向量类型外，参数可接受任意可强转为向量类型的其他类型，如字符串类型（如
'[1,2,3]'）。当存在单级数组类型参数时，该参数元素不允许出现
NULL。
返回值说明如下：
返回
norm(double)模值。当参数为
NULL时，返回NULL。
示例如下：
CREATE TABLE t10(c1 vector(3));
INSERT INTO t10 VALUES('[1,2,3]');
SELECT vector_norm(c1),vector_norm([1,2,3]) FROM t10;
返回结果如下：
+--------------------+----------------------+
| vector_norm(c1) | vector_norm([1,2,3]) |
+--------------------+----------------------+
| 3.7416573867739413 | 3.7416573867739413 |
+--------------------+----------------------+
1 row in set
向量归一化
向量归一化（Normalization）是指将向量的长度（模）标准化为 1 的过程。vector_norm 函数常用于实现向量归一化。
对于使用 l2_distance 距离类型的向量索引，建议对向量进行归一化处理，以提高相似度搜索的准确性。归一化后的向量模为 1，L2 距离的范围会被限制在 [0, 2] 之间，从而避免相似度值过小导致的精度问题。
例如，对于向量 [3, 4]：
- 向量的模：
vector_norm([3, 4]) = √(3² + 4²) = 5 - 归一化后：
[3, 4] / 5 = [0.6, 0.8]
归一化后的向量模为 1，验证方式：
SELECT vector_norm([0.6, 0.8]);
返回结果如下：
+-------------------------+
| vector_norm([0.6, 0.8]) |
+-------------------------+
| 1.000000029802322 |
+-------------------------+
1 row in set
Vector_dims
Vector_dims 函数用于返回向量维度。
语法如下：
vector_dims(vector v1)
参数说明如下：
- 除了向量类型外，参数可接受任意可强转为向量类型的其他类型，如字符串类型（如
'[1,2,3]'）。
返回值说明如下：
返回
dims(int64)维度值。当参数为
NULL时会报错。
示例如下：
CREATE TABLE t11(c1 vector(3));
INSERT INTO t11 VALUES('[1,2,3]');
INSERT INTO t11 VALUES('[1,1,1]');
SELECT vector_dims(c1), vector_dims('[1,2,3]') FROM t11;
返回结果如下：
+-----------------+------------------------+
| vector_dims(c1) | vector_dims('[1,2,3]') |
+-----------------+------------------------+
| 3 | 3 |
| 3 | 3 |
+-----------------+------------------------+
2 rows in set
语义索引相关函数
除了上述通用向量函数外，OceanBase 还提供了专门用于语义索引（在文本列上创建的向量索引）的向量搜索函数：
semantic_distance(column_name, 'query_text')：使用原始文本进行向量搜索，系统会自动调用嵌入模型将文本转换为向量。semantic_vector_distance(column_name, query_vector)：使用向量进行搜索，支持索引搜索（带APPROXIMATE/APPROX子句）和全表扫描（不带APPROXIMATE/APPROX子句）两种方式。
这两个函数专门用于语义索引场景，详细说明和示例请参见语义索引。
