版本：Nightly

向量函数

本页面列出了 GreptimeDB 中所有支持的向量相关函数。向量函数主要用于处理向量运算，比如基础运算、距离计算、转换函数等。

基础运算

`vec_scalar_add`

向量与标量的加法运算。将向量中的每个元素与标量相加，返回新的向量。

示例：

SELECT vec_to_string(vec_scalar_add(2.0, parse_vec('[1.0, 2.0, 3.0]')));

+------------------------------------------------------------------------------+
| vec_to_string(vec_scalar_add(Float64(2),parse_vec(Utf8("[1.0, 2.0, 3.0]")))) |
+------------------------------------------------------------------------------+
| [3,4,5]                                                                      |
+------------------------------------------------------------------------------+

SELECT vec_to_string(vec_scalar_add(2.0, '[1.0, 2.0, 3.0]')); -- 隐式转换字符串为向量

+-------------------------------------------------------------------+
| vec_to_string(vec_scalar_add(Float64(2),Utf8("[1.0, 2.0, 3.0]"))) |
+-------------------------------------------------------------------+
| [3,4,5]                                                           |
+-------------------------------------------------------------------+

SELECT vec_to_string(vec_scalar_add(-2.0, parse_vec('[1.0, 2.0, 3.0]'))); -- 减法运算

+-------------------------------------------------------------------------------+
| vec_to_string(vec_scalar_add(Float64(-2),parse_vec(Utf8("[1.0, 2.0, 3.0]")))) |
+-------------------------------------------------------------------------------+
| [-1,0,1]                                                                      |
+-------------------------------------------------------------------------------+

`vec_scalar_mul`

向量与标量的乘法运算。将向量中的每个元素与标量相乘，返回新的向量。

示例：

SELECT vec_to_string(vec_scalar_mul(2.0, parse_vec('[1.0, 2.0, 3.0]')));

+------------------------------------------------------------------------------+
| vec_to_string(vec_scalar_mul(Float64(2),parse_vec(Utf8("[1.0, 2.0, 3.0]")))) |
+------------------------------------------------------------------------------+
| [2,4,6]                                                                      |
+------------------------------------------------------------------------------+

SELECT vec_to_string(vec_scalar_mul(2.0, '[1.0, 2.0, 3.0]')); -- 隐式转换字符串为向量

+------------------------------------------------------------------------------+
| vec_to_string(vec_scalar_mul(Float64(2),parse_vec(Utf8("[1.0, 2.0, 3.0]")))) |
+------------------------------------------------------------------------------+
| [2,4,6]                                                                      |
+------------------------------------------------------------------------------+

SELECT vec_to_string(vec_scalar_mul(1.0/2.0, parse_vec('[1.0, 2.0, 3.0]'))); -- 除法运算

+-------------------------------------------------------------------------------------------+
| vec_to_string(vec_scalar_mul(Float64(1) / Float64(2),parse_vec(Utf8("[1.0, 2.0, 3.0]")))) |
+-------------------------------------------------------------------------------------------+
| [0.5,1,1.5]                                                                               |
+-------------------------------------------------------------------------------------------+

`vec_add`

向量之间的加法运算。将两个向量的对应元素相加，返回新的向量。

示例：

SELECT vec_to_string(vec_add(parse_vec('[1.0, 2.0, 3.0]'), parse_vec('[2.0, 1.0, 4.0]')));

+-----------------------------------------------------------------------------------------------+
| vec_to_string(vec_add(parse_vec(Utf8("[1.0, 2.0, 3.0]")),parse_vec(Utf8("[2.0, 1.0, 4.0]")))) |
+-----------------------------------------------------------------------------------------------+
| [3,3,7]                                                                                       |
+-----------------------------------------------------------------------------------------------+

SELECT vec_to_string(vec_add('[1.0, 2.0, 3.0]', '[2.0, 1.0, 4.0]')); -- 隐式转换字符串为向量

+-------------------------------------------------------------------------+
| vec_to_string(vec_add(Utf8("[1.0, 2.0, 3.0]"),Utf8("[2.0, 1.0, 4.0]"))) |
+-------------------------------------------------------------------------+
| [3,3,7]                                                                 |
+-------------------------------------------------------------------------+

`vec_sub`

向量之间的减法运算。将两个向量的对应元素相减，返回新的向量。

示例：

SELECT vec_to_string(vec_sub(parse_vec('[1.0, 2.0, 3.0]'), parse_vec('[2.0, 1.0, 4.0]')));

+-----------------------------------------------------------------------------------------------+
| vec_to_string(vec_sub(parse_vec(Utf8("[1.0, 2.0, 3.0]")),parse_vec(Utf8("[2.0, 1.0, 4.0]")))) |
+-----------------------------------------------------------------------------------------------+
| [-1,1,-1]                                                                                     |
+-----------------------------------------------------------------------------------------------+

SELECT vec_to_string(vec_sub('[1.0, 2.0, 3.0]', '[2.0, 1.0, 4.0]')); -- 隐式转换字符串为向量

+-------------------------------------------------------------------------+
| vec_to_string(vec_sub(Utf8("[1.0, 2.0, 3.0]"),Utf8("[2.0, 1.0, 4.0]"))) |
+-------------------------------------------------------------------------+
| [-1,1,-1]                                                               |
+-------------------------------------------------------------------------+

`vec_mul`

向量之间的乘法运算。将两个向量的对应元素相乘，返回新的向量。

示例：

SELECT vec_to_string(vec_mul(parse_vec('[1.0, 2.0, 3.0]'), parse_vec('[2.0, 1.0, 4.0]')));

+-----------------------------------------------------------------------------------------------+
| vec_to_string(vec_mul(parse_vec(Utf8("[1.0, 2.0, 3.0]")),parse_vec(Utf8("[2.0, 1.0, 4.0]")))) |
+-----------------------------------------------------------------------------------------------+
| [2,2,12]                                                                                      |
+-----------------------------------------------------------------------------------------------+

SELECT vec_to_string(vec_mul('[1.0, 2.0, 3.0]', '[2.0, 1.0, 4.0]')); -- 隐式转换字符串为向量

+-------------------------------------------------------------------------+
| vec_to_string(vec_mul(Utf8("[1.0, 2.0, 3.0]"),Utf8("[2.0, 1.0, 4.0]"))) |
+-------------------------------------------------------------------------+
| [2,2,12]                                                                |
+-------------------------------------------------------------------------+

`vec_div`

向量之间的除法运算。将两个向量的对应元素相除，返回新的向量。

示例：

SELECT vec_to_string(vec_div(parse_vec('[1.0, 2.0, 3.0]'), parse_vec('[2.0, 1.0, 4.0]')));

+-----------------------------------------------------------------------------------------------+
| vec_to_string(vec_div(parse_vec(Utf8("[1.0, 2.0, 3.0]")),parse_vec(Utf8("[2.0, 1.0, 4.0]")))) |
+-----------------------------------------------------------------------------------------------+
| [0.5,2,0.75]                                                                                  |
+-----------------------------------------------------------------------------------------------+

SELECT vec_to_string(vec_div('[1.0, 2.0, 3.0]', '[2.0, 1.0, 4.0]')); -- 隐式转换字符串为向量

+-------------------------------------------------------------------------+
| vec_to_string(vec_div(Utf8("[1.0, 2.0, 3.0]"),Utf8("[2.0, 1.0, 4.0]"))) |
+-------------------------------------------------------------------------+
| [0.5,2,0.75]                                                            |
+-------------------------------------------------------------------------+

`vec_elem_sum`

向量中所有元素求和，返回一个标量。

示例：

SELECT vec_elem_sum(parse_vec('[1.0, 2.0, 3.0]'));

+--------------------------------------------------+
| vec_elem_sum(parse_vec(Utf8("[1.0, 2.0, 3.0]"))) |
+--------------------------------------------------+
|                                                6 |
+--------------------------------------------------+

SELECT vec_elem_sum('[1.0, 2.0, 3.0]'); -- 隐式转换字符串为向量

+---------------------------------------+
| vec_elem_sum(Utf8("[1.0, 2.0, 3.0]")) |
+---------------------------------------+
|                                     6 |
+---------------------------------------+

`vec_elem_product`

向量中所有元素求积，返回一个标量。

示例：

SELECT vec_elem_product(parse_vec('[1.0, 2.0, 3.0]'));

+------------------------------------------------------+
| vec_elem_product(parse_vec(Utf8("[1.0, 2.0, 3.0]"))) |
+------------------------------------------------------+
|                                                    6 |
+------------------------------------------------------+

SELECT vec_elem_product('[1.0, 2.0, 3.0]'); -- 隐式转换字符串为向量

+-------------------------------------------+
| vec_elem_product(Utf8("[1.0, 2.0, 3.0]")) |
+-------------------------------------------+
|                                         6 |
+-------------------------------------------+

`vec_elem_avg`

返回一个向量中所有元素的算术平均值。

SELECT vec_elem_avg('[1.0, 2.0, 3.0]');
-- 2.0

`vec_dim`

以无符号整数返回向量的元素个数。

SELECT vec_dim('[7.0, 8.0, 9.0, 10.0]');
-- 4

`vec_kth_elem`

返回从零开始的整数索引所对应的元素。索引为负数或超出范围时返回错误。

SELECT vec_kth_elem('[2.0, 4.0, 6.0]', 1);
-- 4.0

`vec_subvector`

返回从零开始的半开区间 [start, end) 中的元素。参数必须满足 0 <= start <= end <= vec_dim(vector)，否则返回错误。

SELECT vec_to_string(vec_subvector('[1.0, 2.0, 3.0, 4.0]', 1, 3));
-- [2,3]

`vec_norm`

归一化向量。将向量中的每个元素除以向量的 L2 范数，返回新的向量。

等价于 vec_scalar_mul(1.0 / sqrt(vec_elem_sum(vec_mul(vec, vec))), vec)。

示例：

SELECT vec_to_string(vec_norm(parse_vec('[1.0, 2.0, 3.0]')));

+-------------------------------------------------------------+
| vec_to_string(vec_norm(parse_vec(Utf8("[1.0, 2.0, 3.0]")))) |
+-------------------------------------------------------------+
| [0.26726124,0.5345225,0.8017837]                            |
+-------------------------------------------------------------+

-- 等价于
-- SELECT vec_to_string(vec_scalar_mul(1.0 / sqrt(vec_elem_sum(vec_mul(vec, vec))), vec))
-- FROM (SELECT '[1.0, 2.0, 3.0]' AS vec);
-- +--------------------------------------------------------------------------------------+
-- | vec_to_string(vec_scalar_mul(Float64(1) / sqrt(vec_elem_sum(vec_mul(vec,vec))),vec)) |
-- +--------------------------------------------------------------------------------------+
-- | [0.26726124,0.5345225,0.8017837]                                                     |
-- +--------------------------------------------------------------------------------------+

SELECT vec_to_string(vec_norm('[1.0, 2.0, 3.0]')); -- 隐式转换字符串为向量

+--------------------------------------------------+
| vec_to_string(vec_norm(Utf8("[1.0, 2.0, 3.0]"))) |
+--------------------------------------------------+
| [0.26726124,0.5345225,0.8017837]                 |
+--------------------------------------------------+

聚合函数

`vec_sum`

将向量列中的所有向量按元素相加，返回一个新的向量。

示例：

CREATE TABLE vectors (
    ts TIMESTAMP TIME INDEX,
    vec_col VECTOR(3),
);

INSERT INTO vectors (ts, vec_col) VALUES ('2024-11-18 00:00:01', '[1.0, 2.0, 3.0]');
INSERT INTO vectors (ts, vec_col) VALUES ('2024-11-18 00:00:02', '[2.0, 1.0, 4.0]');
INSERT INTO vectors (ts, vec_col) VALUES ('2024-11-18 00:00:03', '[3.0, 3.0, 3.0]');

SELECT vec_to_string(vec_sum(vec_col)) FROM vectors;

+-----------------------------------------+
| vec_to_string(vec_sum(vectors.vec_col)) |
+-----------------------------------------+
| [6,6,10]                                |
+-----------------------------------------+

`vec_avg`

对所有非 NULL 向量按元素求平均值。输入向量的维度必须相同。

SELECT vec_to_string(vec_avg(vec_col)) FROM vectors;

+-----------------------------------------+
| vec_to_string(vec_avg(vectors.vec_col)) |
+-----------------------------------------+
| [2,2,3.3333333]                         |
+-----------------------------------------+

`vec_product`

将向量列中的所有向量按元素相乘，返回一个新的向量。

示例：

CREATE TABLE vectors (
    ts TIMESTAMP TIME INDEX,
    vec_col VECTOR(3),
);

INSERT INTO vectors (ts, vec_col) VALUES ('2024-11-18 00:00:01', '[1.0, 2.0, 3.0]');
INSERT INTO vectors (ts, vec_col) VALUES ('2024-11-18 00:00:02', '[2.0, 1.0, 4.0]');
INSERT INTO vectors (ts, vec_col) VALUES ('2024-11-18 00:00:03', '[3.0, 3.0, 3.0]');

SELECT vec_to_string(vec_product(vec_col)) FROM vectors;

+---------------------------------------------+
| vec_to_string(vec_product(vectors.vec_col)) |
+---------------------------------------------+
| [6,6,36]                                    |
+---------------------------------------------+

距离计算

GreptimeDB 提供了以下常用的距离计算函数：

vec_l2sq_distance(vec1, vec2)：计算两个向量之间的 L2 距离的平方。
vec_cos_distance(vec1, vec2)：计算两个向量之间的余弦距离。
vec_dot_product(vec1, vec2)：计算两个向量之间的点积。

这些函数接受向量值作为参数。你可以通过 parse_vec 函数将字符串转变为向量值，例如 parse_vec('[1.0, 2.0, 3.0]')。同时，字符串格式的向量（例如 [1.0, 2.0, 3.0]）也可以直接使用，它们会被自动转换。无论采用哪种方式，向量的维度必须保持一致。

`vec_l2sq_distance`

计算两个向量之间的平方欧几里得距离（L2 距离的平方）。L2 距离是几何空间中两个点之间的直线距离，此函数返回其平方值以提高计算效率。

示例：

SELECT vec_l2sq_distance(parse_vec('[1.0, 2.0, 3.0]'), parse_vec('[2.0, 1.0, 4.0]'));

或者

SELECT vec_l2sq_distance('[1.0, 2.0, 3.0]', '[2.0, 1.0, 4.0]');

说明：

参数为两个维度一致的向量。
返回值类型为 Float32 标量。

`vec_cos_distance`

计算两个向量之间的余弦距离。余弦距离是两个向量之间的夹角余弦值，用于衡量向量之间的相似度。

示例：

SELECT vec_cos_distance(parse_vec('[1.0, 2.0, 3.0]'), parse_vec('[2.0, 1.0, 4.0]'));

或者

SELECT vec_cos_distance('[1.0, 2.0, 3.0]', '[2.0, 1.0, 4.0]');

说明：

参数为两个维度一致的向量。
返回值类型为 Float32 标量。

`vec_dot_product`

计算两个向量之间的点积。点积是两个向量对应元素的乘积之和，常用于度量两个向量的相似性或用于机器学习的线性变换中。

示例：

SELECT vec_dot_product(parse_vec('[1.0, 2.0, 3.0]'), parse_vec('[2.0, 1.0, 4.0]'));

或者

SELECT vec_dot_product('[1.0, 2.0, 3.0]', '[2.0, 1.0, 4.0]');

说明：

参数为两个维度一致的向量。
返回值类型为 Float32 标量。

转换函数

在处理数据库中的向量数据时，GreptimeDB 提供了方便的函数，用于在字符串和向量值之间进行转换。

`parse_vec`

将字符串转换为向量值。字符串必须以方括号 [] 包围，并且包含 Float32 类型的元素，元素之间用逗号分隔。

示例：

CREATE TABLE vectors (
    ts TIMESTAMP,
    vec_col VECTOR(3)
);

INSERT INTO vectors (ts, vec_col) VALUES ('2024-11-18 00:00:01', parse_vec('[1.0, 2.0, 3.0]'));

`vec_to_string`

将向量值转换为字符串。转换后的字符串格式为 [<float32>, <float32>, ...]。

示例：

SELECT vec_to_string(vec_col) FROM vectors;

向量函数

基础运算​

vec_scalar_add​

vec_scalar_mul​

vec_add​

vec_sub​

vec_mul​

vec_div​

vec_elem_sum​

vec_elem_product​

vec_elem_avg​

vec_dim​

vec_kth_elem​

vec_subvector​

vec_norm​

聚合函数​

vec_sum​

vec_avg​

vec_product​

距离计算​

vec_l2sq_distance​

vec_cos_distance​

vec_dot_product​

转换函数​

parse_vec​

vec_to_string​