向量函数

版本说明

• 向量函数为 AI 核心特性，支持 SelectDB 5.0.0（26.0.0）及以上版本。其中 cosine_similarity 函数需 SelectDB 26.1.0 及以上版本。

• 向量以数组（ARRAY）形式表示，数组元素支持 TINYINT、SMALLINT、INT、BIGINT、LARGEINT、FLOAT、DOUBLE 等数值类型。参与运算的两个向量必须长度相同。

• embed 函数支持多模态 Embedding（图像、视频等），需 SelectDB 26.1.5（Apache Doris 4.1.5）及以上版本。

函数列表

通用说明

除 embed 外，各向量距离函数在输入边界上的行为一致：

• 两个向量长度必须相同，否则报错。例如 l2_distance([1,2,3],[1,2]) 报错：have different input element sizes of array: 3 and 2。

• 参数为 NULL 时报错，例如 l2_distance(NULL,[1,2]) 报错 First argument for function l2_distance cannot be null。

• 向量中含有 NULL 元素时报错，例如 l2_distance([1,NULL],[1,2]) 报错 First argument for function l2_distance cannot have null。

• 两个空数组作为输入时返回 0，例如 l2_distance([],[]) 返回 0。

embed

调用大模型服务，根据输入文本或多模态内容生成表示其语义信息的向量（embedding），返回一个 FLOAT 类型的数组。常用于将文本或图像等内容写入向量列或构造查询向量，配合上述距离函数实现相似度计算、语义检索等场景。

语法

embed([<resource_name>], <input>)

参数

多模态内容 JSON 对象字段说明

当 <input> 为多模态内容时，需传入 JSON 对象，包含以下字段：

返回值

返回类型为 ARRAY，表示生成的向量。若输入值为 NULL 则返回 NULL。结果由大模型生成，因此返回内容并不固定。

说明

• 使用 embed 前，需先创建连接大模型服务（如百炼）的 AI 资源，并在参数中指定 <resource_name>，或通过 SET default_ai_resource 设置默认资源。

• 若未指定资源且未设置默认资源，调用时会报错：Please specify the AI Resource in argument or session variable.

示例

示例一：调用 embed 函数

-- 设置默认 AI 资源后调用
SET default_ai_resource = 'your_resource_name';
SELECT embed('hello world');

-- 或在参数中直接指定资源
SELECT embed('your_resource_name', 'hello world');

示例二：将文本向量写入表中

-- 1. 创建包含向量列的表
CREATE TABLE articles (
    id INT,
    content TEXT,
    embedding ARRAY<FLOAT>
)
DUPLICATE KEY(id)
DISTRIBUTED BY HASH(id) BUCKETS 1;

-- 2. 使用 embed 将文本转换为向量并写入
INSERT INTO articles VALUES (
    1,
    '云数据库 SelectDB 版是一款高性能分析型数据库',
    embed('云数据库 SelectDB 版是一款高性能分析型数据库')
);

-- 3. 查询写入的向量
SELECT id, content, embedding FROM articles WHERE id = 1;

-- 4. 结合距离函数进行语义检索
SELECT id, content,
       cosine_distance(embedding, embed('分析型数据库')) AS distance
FROM articles
ORDER BY distance
LIMIT 10;

示例三：多模态 Embedding（图像/视频）

SelectDB 26.1.5（Apache Doris 4.1.5）及以上版本支持多模态 Embedding，可对图像、视频等内容生成向量表示。

通过 HTTPS URL 生成图像嵌入

SELECT ARRAY_SIZE(
    embed(
        'multimodal_embed_resource',
        CAST('{
            "uri": "https://example.com/images/product.png",
            "content_type": "image/png"
        }' AS JSON)
    )) AS image_embedding_dimension;

通过 S3（AK/SK）生成视频嵌入

SELECT ARRAY_SIZE(
    embed(
        'multimodal_embed_resource',
        CAST('{
            "uri": "s3://example-bucket/videos/demo.mp4",
            "content_type": "video/mp4",
            "endpoint": "s3.us-east-1.amazonaws.com",
            "region": "us-east-1",
            "ak": "<access_key>",
            "sk": "<secret_key>"
        }' AS JSON)
    )) AS video_embedding_dimension;

通过 S3（IAM Role）生成图像嵌入

SELECT ARRAY_SIZE(
    embed(
        'multimodal_embed_resource',
        CAST('{
            "uri": "s3://example-bucket/images/product.png",
            "content_type": "image/png",
            "endpoint": "s3.us-east-1.amazonaws.com",
            "region": "us-east-1",
            "role_arn": "arn:aws:iam::<account_id>:role/<role_name>",
            "external_id": "<external_id>"
        }' AS JSON)
    )) AS image_embedding_dimension;

l1_distance

计算两个等长向量之间的 L1 距离（曼哈顿距离），即各维度差值绝对值之和。

语法

l1_distance(<array1>, <array2>)

参数

返回值

返回两个向量在 L1 空间中的距离，返回类型为 FLOAT。若任一输入向量为 NULL 或含有 NULL 元素，则报错。

示例

SELECT l1_distance([4,5],[6,8]);
-- 返回 5

l2_distance

计算两个等长向量之间的 L2 距离（欧氏距离），即各维度差值平方和的平方根。

语法

l2_distance(<array1>, <array2>)

参数

返回值

返回两个向量在欧氏空间中的距离，返回类型为 FLOAT。若任一输入向量为 NULL 或含有 NULL 元素，则报错。

示例

SELECT l2_distance([4,5],[6,8]);
-- 返回 3.605551

SELECT l2_distance([1,2,3],[4,5,6]);
-- 返回 5.196152

l2_distance_approximate

l2_distance 的近似版本，计算两个等长向量之间的近似 L2 距离。若相关数组列上已建立 ANN 索引，则可直接从索引中获取结果，在大规模向量检索等性能优先的场景中，以少量精度换取更高的计算效率。

语法

l2_distance_approximate(<array1>, <array2>)

参数

返回值

返回两个向量在欧氏空间中的近似距离，返回类型为 FLOAT。若任一输入向量为 NULL 或含有 NULL 元素，则报错。

示例

SELECT l2_distance_approximate([4,5],[6,8]);
-- 返回 3.605551

cosine_distance

计算两个等长向量之间的余弦距离，取值范围为 [0, 2]，值越小表示两个向量方向越接近。余弦距离 = 1 − 余弦相似度。

语法

cosine_distance(<array1>, <array2>)

参数

返回值

返回两个向量之间的余弦距离，返回类型为 FLOAT。若任一输入向量为 NULL 或含有 NULL 元素，则报错。相同方向的向量余弦距离为 0，正交向量为 1，方向相反的向量为 2；当其中一个向量为零向量时返回 2（余弦距离上界）。

示例

SELECT cosine_distance([1,2,3],[1,2,3]);
-- 返回 0

SELECT cosine_distance([1,0],[0,1]);
-- 返回 1

SELECT cosine_distance([1,2],[2,3]);
-- 返回 0.007722139

SELECT cosine_distance([0,0],[1,2]);
-- 返回 2

cosine_similarity

计算两个等长向量之间的余弦相似度，取值范围为 [−1, 1]，值越大表示两个向量方向越接近。余弦相似度 = 1 − 余弦距离。

语法

cosine_similarity(<array1>, <array2>)

参数

返回值

返回两个向量之间的余弦相似度，返回类型为 FLOAT。若输入向量为 NULL 或含有 NULL 元素，则报错；若两个数组元素数量不一致，则报错；若数组为空或其中一个向量为零向量，则返回 0.0。

示例

SELECT cosine_similarity([1,2,3],[1,2,3]);
-- 返回 1

inner_product

计算两个等长向量的内积（点积），即各维度对应元素乘积之和。

语法

inner_product(<array1>, <array2>)

参数

返回值

返回两个等长向量的内积，返回类型为 FLOAT。若任一输入向量为 NULL 或含有 NULL 元素，则报错。

示例

SELECT inner_product([1,2],[2,3]);
-- 返回 8

inner_product_approximate

inner_product 的近似版本，计算两个等长向量的近似内积。若相关数组列上已建立 ANN 索引，则可直接从索引中获取结果，在大规模向量检索等性能优先的场景中，以少量精度换取更高的计算效率。

语法

inner_product_approximate(<array1>, <array2>)

参数

返回值

返回两个等长向量的近似内积，返回类型为 FLOAT。若任一输入向量为 NULL 或含有 NULL 元素，则报错。

示例

SELECT inner_product_approximate([1,2],[2,3]);
-- 返回 8