向量类型(公测中)

更新时间:
复制 MD 格式

向量(VECTOR)数据类型用于存储固定维度的单精度浮点数向量,适用于语义检索、相似内容检索、推荐和 RAG 等场景。本文介绍如何在 Lindorm 宽表中定义、写入和查询 VECTOR 类型数据,并说明相关函数的使用方法。

前提条件

  • 宽表引擎版本需为 2.9.2.1 及以上。如何查看或升级当前版本,请参见SQL版本说明和升级小版本。

  • 如需使用向量检索功能,还需开通以下服务:

    • 向量引擎

    • 搜索引擎

    • 搜索索引服务

    相关版本及开通要求,请参见向量检索。

  • 如需使用 VECTOR_EMBEDDING 函数,还需额外开通 Lindorm AI 引擎。

注意事项

  • 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;
说明
  • 关于使用字符串形式表示数组的方式,详细可以查看手册文档数组类型(公测中)。

  • 关于向量索引的创建、离线构建、过滤策略、检索参数和混合检索等详细说明,请参见向量检索。

  • 调用 VECTOR_EMBEDDING 会产生模型推理和网络通信开销。

  • 目前该函数仅支持对文本数据进行向量化,可供选择模型请参考 文本向量。