向量(VECTOR)数据类型用于存储固定维度的单精度浮点数向量,适用于语义检索、相似内容检索、推荐和 RAG 等场景。本文介绍如何在 Lindorm 宽表中定义、写入和查询 VECTOR 类型数据,并说明相关函数的使用方法。
前提条件
注意事项
VECTOR 类型必须指定维度,语法为
VECTOR(n),其中n的取值范围为 1~65535。VECTOR 中的元素目前固定为 32 位浮点数(float32)。
写入值的元素数目必须与建表时声明的维度一致。
VECTOR 列允许为 NULL,但向量内部的单个元素不能为 NULL,也不支持空向量。
用于向量检索的向量元素必须是有限数值,不能包含 NaN、正无穷或负无穷。
VECTOR 类型不能作为主键列,也不能作为普通二级索引的索引键。
向量检索应使用向量索引或包含向量列的搜索索引。
执行向量检索时,查询向量的维度必须与被检索列的维度一致。
向量索引的其他限制请参见向量检索。
DDL
您可以在创建表或修改表时,将非主键列定义为 VECTOR 类型。
创建包含 VECTOR 列的表
以下示例创建表 vector_items。其中,id 为主键列,embedding 为 4 维 VECTOR 列。示例表启用强一致性,便于后续创建搜索索引。
CREATE TABLE vector_items (
id VARCHAR,
name VARCHAR,
embedding VECTOR(4),
PRIMARY KEY(id)
) WITH (CONSISTENCY='strong');您可以执行以下语句查看表结构:
DESCRIBE vector_items;返回结果示例如下:
COLUMN_NAME | TYPE | IS_PRIMARY_KEY |
id | VARCHAR | true |
name | VARCHAR | false |
embedding | VECTOR(4) | false |
添加 VECTOR 列
以下示例为已有表添加一个 4 维 VECTOR 列:
ALTER TABLE vector_items ADD COLUMN image_embedding VECTOR(4);DML
Lindorm 支持通过 UPSERT 语句向 VECTOR 列写入和更新向量数据。写入时,元素数目必须与列定义的维度一致。
写入向量数据
写入 VECTOR 数据时,推荐使用由方括号包围的字符串形式:'[v1, v2, ..., vn]'。每个元素必须是可转换为浮点数的数值,并且元素数目必须与列定义的维度一致。
以下示例写入两行数据:
UPSERT INTO vector_items (id, name, embedding)
VALUES
('item_001', '主动降噪蓝牙耳机', '[0.12, 0.35, 0.48, 0.91]'),
('item_002', '开放式运动耳机', '[0.09, 0.27, 0.62, 0.83]');更新向量数据
对于已存在的主键,可以通过 UPSERT 覆盖 VECTOR 列的值:
UPSERT INTO vector_items (id, embedding)
VALUES ('item_001', '[0.15, 0.33, 0.51, 0.88]');如果写入向量的维度与列定义不一致,语句将执行失败。例如,不能向 VECTOR(4) 列写入 3 维向量。
DQL
Lindorm 支持通过 SELECT 语句查询 VECTOR 列数据;结合向量索引,还可以使用 VECTOR_DISTANCE 函数执行向量相似度检索。
查询向量数据
以下示例查询指定数据的向量值:
SELECT id, name, embedding
FROM vector_items
WHERE id = 'item_001';返回结果示例如下:
id | name | embedding |
item_001 | 主动降噪蓝牙耳机 | [0.15, 0.33, 0.51, 0.88] |
查询向量维度和字符串表示
SELECT
id,
VECTOR_DIM(embedding) AS dimensions,
VECTOR_TO_STRING(embedding) AS embedding_text
FROM vector_items
WHERE id = 'item_001';返回结果示例如下:
id | dimensions | embedding_text |
item_001 | 4 | [0.15, 0.33, 0.51, 0.88] |
向量相似度检索功能,可参考VECTOR_DISTANCE函数使用。
函数介绍
为便于对 VECTOR 数据进行操作,Lindorm 提供了以下内置函数,支持格式转换、维度查询、文本向量化及相似度检索等能力。
STRING_TO_VECTOR
STRING_TO_VECTOR函数可以将字符串转换为 VECTOR 值,输入为 NULL 时返回 NULL。
代码示例:
SELECT STRING_TO_VECTOR('[0.1, 0.2, 0.3, 0.4]') AS embedding;返回结果:
[0.1, 0.2, 0.3, 0.4]
VECTOR_TO_STRING
VECTOR_TO_STRING函数可以将向量转换为 '[v1, v2, ..., vn]' 形式的字符串,输入为 NULL 时返回 NULL。
SELECT VECTOR_TO_STRING(embedding) AS embedding_text
FROM vector_items
WHERE id = 'item_001';VECTOR_DIM
VECTOR_DIM 函数返回 VECTOR 值的维度。
代码示例:
SELECT VECTOR_DIM(embedding) AS dimensions FROM vector_items WHERE id = 'item_001';返回结果:
4
VECTOR_DISTANCE
VECTOR_DISTANCE函数用于向量检索,需要由包含目标向量列的向量索引或搜索索引执行。
以下示例查询与目标向量最相近的 10 条数据:
SELECT id, name
FROM vector_items
ORDER BY VECTOR_DISTANCE(embedding, '[0.11, 0.34, 0.50, 0.89]')
LIMIT 10;您也可以同时使用标量过滤条件:
SELECT id, name
FROM vector_items
WHERE id >= 'item_001' AND id <= 'item_999'
ORDER BY VECTOR_DISTANCE(embedding,'[0.11, 0.34, 0.50, 0.89]')
LIMIT 10;VECTOR_DISTANCE 支持可选的第三个参数,用于指定距离算法。可选值包括 EUCLIDEAN、COSINE 和 DOT。省略该参数时,使用向量索引创建时默认配置的距离算法;显式指定时,必须与索引配置的距离算法一致。
SELECT id, name
FROM vector_items
ORDER BY VECTOR_DISTANCE(
embedding,'[0.11, 0.34, 0.50, 0.89]','COSINE'
)
LIMIT 10;以下示例返回向量距离小于或等于指定阈值的数据:
SELECT id, name
FROM vector_items
WHERE VECTOR_DISTANCE(
embedding,
'[0.11, 0.34, 0.50, 0.89]'
) <= 0.2
LIMIT 10;VECTOR_EMBEDDING
VECTOR_EMBEDDING 函数调用 Embedding 模型将文本转换为向量。该函数支持以下两种形式:
语法说明:
VECTOR_EMBEDDING(model_name, text) VECTOR_EMBEDDING(model_name, text, dimensions)参数说明:
参数
是否必填
说明
model_name是
Embedding 模型名称,例如
text-embedding-v4。不能为空。text是
需要转换为向量的文本。输入为 NULL 时,函数返回 NULL。
dimensions否
期望模型返回的向量维度,必须为正整数。省略时使用模型的默认输出维度。该参数是否可用以及支持的取值由具体模型决定。
代码示例:
以下示例使用
text-embedding-v4将文本转换为 1024 维向量:SELECT VECTOR_EMBEDDING('text-embedding-v4','无线降噪耳机,适合通勤和办公', 1024 ) AS query_vector;函数返回的向量可以直接写入 VECTOR 列。目标列的维度必须与函数实际返回的向量维度一致。
CREATE TABLE text_vectors ( id VARCHAR, content VARCHAR, embedding VECTOR(1024), PRIMARY KEY(id) ) WITH (CONSISTENCY='strong'); UPSERT INTO text_vectors (id, content, embedding) VALUES ( 'doc_001', 'Lindorm 是面向海量数据场景的云原生多模数据库', VECTOR_EMBEDDING( 'text-embedding-v4', 'Lindorm 是面向海量数据场景的云原生多模数据库', 1024 ) );您也可以在向量检索语句中使用
VECTOR_EMBEDDING生成查询向量:SELECT id, content FROM text_vectors ORDER BY VECTOR_DISTANCE( embedding, VECTOR_EMBEDDING( 'text-embedding-v4', '面向海量数据的云原生数据库', 1024 ) ) LIMIT 10;