本文介绍如何在 doris 中创建向量列和 ANN 索引、写入向量数据并执行 Top-K 检索，帮助您完成一次完整的向量检索。三种索引算法的专属属性和调参方法，请查看对应的专项文档。

概述

一条向量检索通常包含以下部分：

1. 向量列：保存 embedding，当前 ANN 索引要求列类型为 ARRAY<FLOAT>。
2. 向量维度：每个向量的元素个数，必须与索引属性 dimension 一致。
3. 距离函数：定义向量之间的相似度，例如 L2、内积或余弦距离。
4. ANN 索引：在建表或后建索引时创建，用于避免逐行计算全部向量。
5. 查询向量和 Top-K：使用 ann_distance() 指定查询向量，并通过 LIMIT 指定返回数量。

ANN 索引是近似检索，通常以较低的查询延迟换取少量召回率损失。实际使用时，应使用离线精确检索结果校验召回率，再按专项文档调整对应算法的索引和查询参数。

支持的索引算法

选择算法时主要权衡内存占用、查询延迟和召回率。当前 doris 支持：

algorithm、dimension、distance 是三种算法共用的基础属性。

创建表和 ANN 索引

建表时创建索引

下面的示例创建一个 4 维向量列 embedding，并在该列上创建 ANN 索引。algorithm 可替换为 hnsw、diskann 或 hnswpq。

1CREATE TABLE vector_documents (
2    `id` BIGINT NOT NULL,
3    `title` STRING,
4    `content` STRING,
5    `embedding` ARRAY<FLOAT> NOT NULL,
6    INDEX idx_embedding(embedding) USING ANN PROPERTIES(
7        'algorithm' = 'hnsw',
8        'dimension' = '4',
9        'distance' = 'cosine'
10    )
11)
12DUPLICATE KEY(`id`)
13DISTRIBUTED BY HASH(`id`) BUCKETS 4;

插入数据时，向量元素数量必须与索引属性 dimension 一致：

1INSERT INTO vector_documents VALUES
2    (1, '向量索引', '介绍 ANN 索引', [0.10, 0.20, 0.30, 0.40]),
3    (2, 'HNSW', '介绍 HNSW 图索引', [0.11, 0.19, 0.31, 0.39]),
4    (3, 'DISKANN', '介绍磁盘友好的向量检索', [0.80, 0.10, 0.10, 0.00]);

为已有表后建索引

也可以先创建表，再使用 CREATE INDEX 补建索引：

1CREATE INDEX idx_embedding
2ON vector_documents (embedding)
3USING ANN
4PROPERTIES(
5    'algorithm' = 'hnsw',
6    'dimension' = '4',
7    'distance' = 'cosine'
8);

后建索引会启动一个异步构建索引任务，请按以下顺序操作：

1. 执行前确认历史数据中的向量都满足列类型和维度要求。
2. 执行 SHOW ALTER TABLE COLUMN; 查看索引构建进度。
3. 等索引构建完成后再进行检索。

DDL 约束

• ANN 索引只能作用于一个列。
• 向量列必须是 ARRAY<FLOAT>。
• dimension 的取值范围为 1 到 FE 配置 max_ann_dimension，当前默认上限为 4096。
• distance 支持 l2、ip、cosine。
• 索引名称不能为空，长度最多为 64 个字符。

查询语法

Top-K 查询

最常见的查询形式是按距离升序返回最近的 K 条记录：ann_distance() 指定查询向量，LIMIT 指定返回数量。

1SELECT
2    id,
3    title,
4    content,
5    __DISTANCE
6FROM vector_documents
7ORDER BY ann_distance(embedding, '[0.10, 0.20, 0.30, 0.40]')
8LIMIT 3;

__DISTANCE 是检索产生的距离结果列。最近邻查询应使用升序排序，距离越小表示越相似。

先过滤再向量检索

查询中可以加入普通过滤条件，语义是先按条件过滤、再在过滤结果上做向量检索：

1SELECT id, title, __DISTANCE
2FROM vector_documents
3WHERE title IS NOT NULL
4ORDER BY ann_distance(embedding, '[0.10, 0.20, 0.30, 0.40]')
5LIMIT 3;

距离类型

索引创建时通过 distance 指定距离类型，查询返回的 __DISTANCE 就是下表中的距离值。

使用距离类型时请注意：

• l2 计算的是平方距离，不是 $\sqrt{\sum_i (x_i - y_i)^2}$。
• ip 返回的是 $1 - \langle x, y \rangle$，而不是原始内积。
• cosine 会对查询向量和索引中的向量做 L2 归一化，再按内积距离计算，等价于 $1 - \cos\theta$。
• 距离数值的具体含义取决于 distance 配置，不能跨不同距离类型直接比较。例如不能使用 l2 建索引后，再把查询结果当作 cosine 相似度解释。