ANN 算法：HNSW
更新时间：2026-09-11
HNSW是一种基于图的索引算法，可以提高搜索高维浮点向量时的性能。它具有出色的搜索精度和低延迟，但需要较高的内存开销来维护其分层图结构。
概览
分层导航小世界（HNSW）算法构建了一个多层图，有点像不同缩放级别的地图。底层包含所有数据点，而上层则由从底层采样的数据点子集组成。
在这种层次结构中，每一层都包含代表数据点的节点，节点之间由表示其接近程度的边连接。上层提供远距离跳转，以快速接近目标，而下层则进行细粒度搜索，以获得最准确的结果。
使用条件
- 向量列必须是
ARRAY<FLOAT>。 - ANN 索引只能作用于一个列。
dimension必须等于每个向量实际包含的元素数量，范围为1到 FE 配置的max_ann_dimension，当前默认上限为4096。distance支持l2、ip、cosine。- 索引名称不能为空，长度最多为 64 个字符。
建立 HNSW 索引
建表时创建
除三个基础属性外，可同时指定 HNSW 专属属性 hnsw_m 和 hnsw_efConstruction，参数含义见“构建参数”。
SQL
1CREATE TABLE hnsw_documents (
2 `id` BIGINT NOT NULL,
3 `content` STRING,
4 `embedding` ARRAY<FLOAT> NOT NULL,
5 INDEX idx_hnsw(embedding) USING ANN PROPERTIES(
6 'algorithm' = 'hnsw',
7 'dimension' = '4',
8 'distance' = 'cosine',
9 'hnsw_m' = '16',
10 'hnsw_efConstruction' = '200'
11 )
12)
13DUPLICATE KEY(`id`)
14DISTRIBUTED BY HASH(`id`) BUCKETS 4;为已有表后建
SQL
1CREATE INDEX idx_hnsw
2ON hnsw_documents (embedding)
3USING ANN
4PROPERTIES(
5 'algorithm' = 'hnsw',
6 'dimension' = '4',
7 'distance' = 'cosine'
8);后建索引会启动一个异步构建索引任务，请按以下顺序操作：
- 执行前确认历史数据中的向量类型和维度正确。
- 执行
SHOW ALTER TABLE COLUMN;查看索引构建进度。 - 等索引构建完成后再进行检索和性能测试。
检索示例
设置查询候选数
hnsw_ef_search 控制检索时的候选数，必须大于等于查询的 LIMIT，因此建议在检索前先确认该值。会话级设置：
SQL
1SET hnsw_ef_search = 100;也可以使用语句级 Hint，只对当前查询生效：
SQL
1SELECT /*+ SET_VAR(hnsw_ef_search=100) */
2 id, content, __DISTANCE
3FROM hnsw_documents
4ORDER BY ann_distance(embedding, '[0.10, 0.20, 0.30, 0.40]')
5LIMIT 10;hnsw_ef_search 越大，搜索候选通常越多，召回率可能更高，但查询延迟和资源消耗也会增加。
Top-K 查询
SQL
1SELECT id, content, __DISTANCE
2FROM hnsw_documents
3ORDER BY ann_distance(embedding, [0.10, 0.20, 0.30, 0.40])
4LIMIT 10;__DISTANCE 是检索产生的距离结果列。最近邻查询通常使用升序排序，距离数值的含义取决于索引的 distance 设置。
距离范围查询
HNSW 支持距离范围查询，范围条件需要同时给出上下界：
SQL
1SELECT id, content, __DISTANCE
2FROM hnsw_documents
3WHERE ann_distance(embedding, '[0.10, 0.20, 0.30, 0.40]')
4 BETWEEN 0.0 AND 0.5
5ORDER BY __DISTANCE
6LIMIT 100;过滤条件
SQL
1SELECT id, content, __DISTANCE
2FROM hnsw_documents
3WHERE content IS NOT NULL
4ORDER BY ann_distance(embedding, '[0.10, 0.20, 0.30, 0.40]')
5LIMIT 10;索引参数
构建参数
在建表或后建索引的 PROPERTIES 中指定。
| 参数 | 说明 | 默认值 | 取值范围 | 调整建议 |
|---|---|---|---|---|
algorithm |
索引算法 | 无 | 固定为 hnsw |
不调整 |
dimension |
向量维度 | 无 | 1 至 max_ann_dimension（默认最大 4096） |
必须与实际向量维度一致 |
distance |
距离类型 | 无 | l2、ip、cosine |
按 embedding 模型和业务度量选择 |
hnsw_m |
图连接数 | 16 |
1 至 max_hnsw_m（默认最大 1000） |
增大可提高召回率，但会增大索引和构建开销 |
hnsw_efConstruction |
构建候选数 | 200 |
1 至 max_hnsw_ef_construction（默认最大 2000） |
召回率不足时增大；会延长构建时间 |
检索参数
通过会话变量或语句级 Hint 指定。
| 参数 | 说明 | 默认值 | 取值范围 | 调整建议 |
|---|---|---|---|---|
hnsw_ef_search |
查询候选数 | 待确认 | 正整数，且 >= LIMIT |
召回率不足时增大；会增加查询延迟 |
使用限制
hnsw_ef_search < LIMIT时查询会被拒绝。- 范围查询必须同时提供上下界。
- 查询向量必须与索引维度一致。
评价此篇文章