ANN 算法：DISKANN

更新时间：2026-09-11

DISKANN 面向大规模向量集合，使用磁盘索引降低内存压力，可以在数据集大小超过可用 RAM 时保持较高的搜索精度和速度。

使用条件

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

建立 DISKANN 索引

建表时创建

除三个基础属性外，可同时指定 DISKANN 专属属性 diskann_nsq、diskann_r 和 diskann_l，参数含义见“构建参数”。

SQL

1CREATE TABLE diskann_documents (
2    `id` BIGINT NOT NULL,
3    `content` STRING,
4    `embedding` ARRAY<FLOAT> NOT NULL,
5    INDEX idx_diskann(embedding) USING ANN PROPERTIES(
6        'algorithm' = 'diskann',
7        'dimension' = '4',
8        'distance' = 'cosine',
9        'diskann_nsq' = '4',
10        'diskann_r' = '64',
11        'diskann_l' = '100'
12    )
13)
14DUPLICATE KEY(`id`)
15DISTRIBUTED BY HASH(`id`) BUCKETS 4;

为已有表后建

SQL

1CREATE INDEX idx_diskann
2ON diskann_documents (embedding)
3USING ANN
4PROPERTIES(
5    'algorithm' = 'diskann',
6    'dimension' = '4',
7    'distance' = 'cosine',
8    'diskann_nsq' = '4',
9    'diskann_r' = '64',
10    'diskann_l' = '100'
11);

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

执行前确认历史数据中的向量类型和维度正确。
执行 SHOW ALTER TABLE COLUMN; 查看索引构建进度。
等索引构建完成后再进行检索和性能测试。

检索示例

设置查询参数

diskann_search_l 必须大于等于查询的 LIMIT，diskann_w 决定一轮并发发起的读取数，建议在检索前先确认两者取值。会话级设置：

SQL

1SET diskann_w = 1;
2SET diskann_search_l = 100;

也可以使用语句级 Hint，只对当前查询生效：

SQL

1SELECT /*+ SET_VAR(diskann_search_l=100, diskann_w=1) */
2       id, content, __DISTANCE
3FROM diskann_documents
4ORDER BY ann_distance(embedding, '[0.10, 0.20, 0.30, 0.40]')
5LIMIT 10;

Top-K 查询

SQL

1SELECT id, content, __DISTANCE
2FROM diskann_documents
3ORDER BY ann_distance(embedding, '[0.10, 0.20, 0.30, 0.40]')
4LIMIT 10;

过滤条件

SQL

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

索引参数

构建参数

在建表或后建索引的 PROPERTIES 中指定。

参数	说明	默认值	取值范围	调整建议
`algorithm`	索引算法	无	固定为 `diskann`	不调整
`dimension`	向量维度	无	`1` 至 `max_ann_dimension`（默认最大 `4096`）	必须与实际向量维度一致
`distance`	距离类型	无	`l2`、`ip`、`cosine`	按 embedding 模型和业务度量选择
`diskann_nsq`	量化子空间数，即每条向量的 PQ 码字节数	`min(512, dimension)`	`1` 至 `512`	先使用默认值；召回率不足时结合索引大小评估
`diskann_r`	图最大邻接度（出度）	`64`	`1` 至 `128`	召回率不足时增大；会增大索引
`diskann_l`	构建候选数，即建图候选队列长度	`100`	`1` 至 `1024`	召回率不足时增大；会延长构建时间，但不影响索引容量

检索参数

通过会话变量或语句级 Hint 指定。

参数	说明	默认值	取值范围	调整建议
`diskann_search_l`	查询候选数，即检索候选队列长度	`10`	正整数，且 `>= LIMIT`	召回率不足时增大；会增加查询开销
`diskann_w`	查询 beam 宽度，即一轮并发发起的读取数	`1`	正整数	结合磁盘 IO 和查询延迟逐步调大

规格估算

以下公式仅估算向量索引的体积，不考虑原始数据体积。符号定义如下图：

image - 2026-09-11T145822.293.png

各参数的默认值和取值范围见“索引参数”。

内存占用

详细公式：

image - 2026-09-11T145852.573.png

简略公式：

image - 2026-09-11T145916.188.png

磁盘占用

详细公式：

image - 2026-09-11T145941.006.png