ByteHouse 中提供向量数据的管理与近似度查询功能，通过支持多种常见近似向量查询（Approximate Nearest Neighbor，ANN）算法来提升检索性能，提供对非结构化数据的处理能力。本文介绍了如何使用 SQL 语句在 ByteHouse 中使用 HNSW、HNSW_SQ 或 Faiss Indices 算法库进行向量检索。

ByteHouse 当前支持 HNSW（hnswlib）、Faiss 两个比较流行的检索算法库，支持 HNSW、FLAT、IVF_FLAT、IVF_PQ、IVF_PQ_FS 等多种常用索引。
HNSW 算法库为图类型索引，通过一种最小世界建立图的思路，为每个节点维护 M 个最近邻节点。同时，维护一个分层图结构，越向上越稀疏，查询时从最上层开始，找到最近点以后继续向下一层计算，直到最底层，得到查询向量的 k 个最近邻。
Faiss 是 Facebook 开源的 ANN 算法库，包含了倒排文件（Inverted File，IVF）、乘积量化（Product Quantization，PQ）、标量量化（Scalar Quantization，SQ）等多种类型的索引，同时多种索引还可以组合使用。ByteHouse 主要使用 Faiss 的 IVF 类索引，同时支持 PQ、PQ_FS（Fsat Scan，快速搜索）等向量压缩方法，以减少索引的内存使用。
更多 ByteHouse 高性能向量检索的介绍请参见概述。

• 请确保您使用的 ByteHouse 为 v2.6 及以上版本。您可登录 ByteHouse 控制台，进入集群列表，单击目标集群，在基础信息页面中查看您使用的引擎版本。
  
• 请确保您已开启向量检索服务。

ANN 算法库以索引（index）的方式接入，支持通过创建表（create table）或修改表（alter table）添加定义。定义索引后，支持插入数据和使用索引查询。本章节以 HNSW 索引类型为例，帮助您快速上手使用向量检索功能。对于不同索引的详细说明，请参见使用 HNSW 索引、使用 HNSW_SQ 索引、使用 Faiss Indices 索引章节。

构建索引

方式 1：新建表

CREATE TABLE test_ann
(
    `id` UInt64,
    `label` String,
    `vector` Array(Float32),
    INDEX v1 vector TYPE HNSW('DIM=960, METRIC=COSINE')
)
ENGINE = MergeTree
ORDER BY id
SETTINGS 
index_granularity = 1024, -- 缓解读放大问题
index_granularity_bytes = 0 -- 避免生成 adaptive mark

方式 2：修改已有表

ALTER TABLE test_ann ADD INDEX v1 vector TYPE HNSW('DIM=960, METRIC=COSINE')

参数说明

插入数据

支持 ByteHouse 自身的插入（insert）语句，以及 Kafka 等流式导入方式，详情请参见数据导入文档。示例如下：

• 通过 VALUES 字段导入数据

  INSERT INTO test_ann (id, vector) VALUES (1, [1.0, 1.0, 1.0]),(2, [2.0, 2.0, 2.0])
  

• 通过 CSV 文件导入数据

  INSERT INTO test_ann FORMAT CSV infile '/filename.csv'
  

使用索引查询

本节介绍了如何使用索引查询数据，包含了常规查询和添加 prewhere 条件的混合查询。此外，ByteHouse 也支持添加 where 条件过滤搜索结果，通过相似度阈值筛选符合条件的记录，详情请参见Distance 过滤。

常规查询

select 
    id， 
    label,
    dist 
from test_ann 
order by cosineDistance(vector, [query_vector]) as dist 
limit 100 
settings enable_new_ann=1

混合查询

ByteHouse 支持带有 prewhere 的混合查询使用方式，例如以下示例使用 prewhere id > 1000 添加预过滤条件，仅处理 id > 1000 的记录。

select 
    id,
    label,
    dist 
from test_ann 
prewhere id > 1000
order by cosineDistance(vector, [query_vector]) as dist 
limit 100 
settings enable_new_ann=1

索引构建语法

使用 HNSW 索引时，可以定义参数 M 和 EF_CONSTRUCTION，借助这两个参数权衡性能和准确度表现。一般来说 M 越大，EF_CONSTRUCTION 越大，索引构建时间越长，准确度越高，搜索延迟越高。示例如下：

CREATE TABLE test_ann
(
    `id` UInt64,
    `vector` Array(Float32),
    INDEX v1 vector TYPE HNSW('DIM=960, METRIC=COSINE, M=32, EF_CONSTRUCTION=512')
)
ENGINE = MergeTree
ORDER BY id
SETTINGS index_granularity = 1024

HNSW 索引支持配置的索引参数说明如下。全量索引参数表及使用建议请参见索引参数。

查询语法

您可使用查询语句检索数据。
此外，ByteHouse 还支持支持添加 prewhere 语句添加预过滤条件，详情请参见混合查询；也支持添加 where 语句用于过滤搜索结果，通过相似度阈值筛选符合条件的记录，详情请参见Distance 过滤。

select 
    id， 
    dist 
from test_ann 
order by cosineDistance(vector, [query_vector]) as dist 
limit 100 
settings enable_new_ann=1, hnsw_ef_s=200

参数说明

HNSW SQ 索引支持向量进行 SQ 压缩（默认压缩为 Int8）可以显著减少索引大小，性能也会比 HNSW 原始算法有少量提升。

索引构建语法

CREATE TABLE test_ann
(
    `id` UInt64,
    `vector` Array(Float32),
    INDEX v1 vector TYPE HNSW_SQ('DIM=960', 'METRIC=COSINE', 'M=32', 'EF_CONSTRUCTION=512', 'SQ=8bit')
)
ENGINE = MergeTree
ORDER BY id
SETTINGS index_granularity = 1024

HNSW_SQ 索引支持配置的索引参数说明如下。全量索引参数表及使用建议请参见索引参数。

查询语法

HNSW_SQ 算法库的查询语法与 HNSW 一致，请参考 HNSW 的查询语法。

注意事项

Faiss 不同于 HNSW，构建索引时会进行训练，对 CPU 消耗比较大。使用时，请注意设置以下参数：

• 根据内存大小设置索引缓存（cache）大小，可使用 vector_index_cache_size 参数配置，默认 200GB。该参数基于最近最少使用策略（Least Recently Used，LRU）实现。
• 如果对冷度敏感，内存足够，可以打开 enable_vector_index_preload 参数，在写入时，将构建的索引加载到内存中。
• 测试时，可以关注 CPU 的使用率，如果 CPU 使用过高，可以采取以下措施：
  • 限制 merge 并发，设置 max_replicated_merges_in_queue 的参数值。
  • 限制 train index 的并发，设置 vector_index_build_threads 的参数值，默认值为 8。

索引构建语法

Faiss 提供了四种常用的索引类型，并提供了对应的微调参数，用于微调准确度。

FLAT 索引

FLAT 是 Faiss 中最简单的索引类型，基于暴力搜索实现。它将所有向量存储在内存中，查询时计算查询向量与所有向量的距离，返回最近邻。FLAT 实现简单，无需训练，精确性高，但时间复杂度为 O(n)，不适合超大规模数据库。建议在数据量较小、向量维度低、对查询速度要求不高但需要精确结果的情况下使用。

CREATE TABLE tab_flat
(
    id Int32, 
    vector Array(Float32), 
    INDEX faiss_index vector TYPE FLAT('dim=4') GRANULARITY 1
) 
ENGINE = MergeTree 
ORDER BY id 
SETTINGS index_granularity = 128

FLAT 索引支持配置的索引参数说明如下。全量索引参数表及使用建议请参见索引参数。

IVF_FLAT 索引

IVF_FLAT 索引结合了 IVF 和 FLAT 索引的优点，能够在保持较高检索精度的同时显著提升查询效率，适合中等规模到大规模的低维度向量检索任务（如 4-128 维）。

CREATE TABLE tab_ivf_flat
(
    id Int32, 
    vector Array(Float32), 
    INDEX faiss_index vector TYPE IVF_FLAT('dim=4') GRANULARITY 1
) 
ENGINE = MergeTree 
ORDER BY id 
SETTINGS index_granularity = 128

IVF_FLAT 索引支持配置的索引参数说明如下。全量索引参数表及使用建议请参见索引参数。

static size_t decideIndexNlist(size_t n)
{
    if (n < ONE_MILLION)
        return std::min(int(n), int(4 * std::floor(std::sqrt(n))));
    else if (n >= ONE_MILLION && n < ONE_MILLION * 2)
        return 1024;
    else if (n >= ONE_MILLION * 2 && n < TEN_MILLION)
        return 4096;
    else if (n > TEN_MILLION)
        return 65536;
}

IVF_PQ 索引

IVF_PQ 索引是一种高效的向量压缩和索引方法，结合了倒排文件（IVF）和乘积量化（PQ）的技术，能够在大幅降低内存占用的同时保持较高的检索精度，适用于超大规模数据集（亿级以上向量）。

CREATE TABLE tab_ivf_pq
(
    id Int32, 
    vector Array(Float32), 
    INDEX faiss_index vector TYPE IVF_PQ('dim=4','m=4','nbit=4') GRANULARITY 1
) 
ENGINE = MergeTree 
ORDER BY id 
SETTINGS index_granularity = 128

IVF_PQ 索引支持配置的索引参数说明如下。全量索引参数表及使用建议请参见索引参数。

IVF_PQ_FS 索引

IVF_PQ_FS 索引是 IVF_PQ 的增强版，增加了快速搜索（Fast Scan）和 Refine 功能，能够在保持压缩优势的同时提升检索精度，适合需要高精度检索的大规模向量数据。

CREATE TABLE tab_ivf_pq_fs
(
    id Int32, 
    vector Array(Float32), 
    INDEX faiss_index vector TYPE IVF_PQ_FS('dim=4','m=4') GRANULARITY 1
) 
ENGINE = MergeTree 
ORDER BY id 
SETTINGS index_granularity = 128

IVF_PQ_FS 索引支持配置的索引参数说明如下。全量索引参数表及使用建议请参见索引参数。

CREATE TABLE tab_ivf_pq_fs_sq8
(
    id Int32,
    vector Array(Float32),
    INDEX faiss_index vector TYPE IVF_PQ_FS('dim=4','m=2', 'refine=SQ8') GRANULARITY 1
)
ENGINE = MergeTree
ORDER BY id
SETTINGS index_granularity = 128

查询语法

您可使用基础查询语句检索数据，也可通过设置 settings 参数，提升准确率。
此外，ByteHouse 还支持支持添加 prewhere 语句添加预过滤条件，详情请参见混合查询；也支持添加 where 语句用于过滤搜索结果，通过相似度阈值筛选符合条件的记录，详情请参见Distance 过滤。

基本查询

SELECT *, d
FROM xxx.yyy
ORDER BY L2Distance(vector, [...]) as d limit 3 
settings 
enable_new_ann=1;

使用 settings 参数调优查询

您可以使用 nprobe 和 k_factor_rf 参数为 IVF_FLAT、IVF_PQ 和 IVF_PQ_FS 索引调优查询，以提升查询准确率。ByteHouse 支持配置的全量 settings 参数列表请参见Settings 参数。

IVF_FLAT 和 IVF_PQ 索引调优

IVF_FLAT 和 IVF_PQ 索引支持设置 nprobe 参数。nprobe 参数指定检索时要访问的 IVF 聚类中心数量。默认是 1，值越大，准确率越好，但性能越差，查询速度越低。取值为 2 的 n 次方，例如 32、64，范围介于 [1, std::min(nlist/2, 查询里的 top n)]。

SELECT *, d
FROM xxx.yyy
ORDER BY L2Distance(vector, [...]) as d limit 3 
settings 
enable_new_ann=1, nprobe=256;

IVF_PQ_FS 索引调优

IVF_PQ_FS 索引支持设置 nprobe 和 k_factor_rf 参数。k_factor_rf 参数可用于控制精排时的候选集扩展倍数，初步检索返回 k 个结果后，将候选集扩大 k_factor_rf 倍（即 k×32），对扩展后的候选集重新计算精确距离，选出最终的 k 个结果。

SELECT *, d
FROM xxx.yyy
ORDER BY L2Distance(vector, [...]) as d limit 3 
settings 
enable_new_ann=1, nprobe=256, k_factor_rf=32;

Distance 过滤

ByteHouse 优化了 where dist < max_score 以及 where dist > min_score 这类单一过滤条件查询，用于过滤搜索结果，通过相似度阈值筛选符合条件的记录。语法示例如下：

select id, dist 
from test_ann 
where dist < 0.9 
order by cosineDistance(embedding_column, [query_vector]) as dist
limit 100

Settings 参数

您可以使用以下 settings 参数优化向量检索查询语句。通过 SQL 语句中配置的 settings 参数仅对当前语句生效。

索引参数

static size_t decideIndexNlist(size_t n)
{
    if (n < ONE_MILLION)
        return std::min(int(n), int(4 * std::floor(std::sqrt(n))));
    else if (n >= ONE_MILLION && n < ONE_MILLION * 2)
        return 1024;
    else if (n >= ONE_MILLION * 2 && n < TEN_MILLION)
        return 4096;
    else if (n > TEN_MILLION)
        return 65536;
}

系统表参数

ByteHouse 提供一个专门用于 vector_indices 信息的系统表，命名为 system.vector_indices，您可使用该系统表查询已构建的向量相关的元数据信息。

字段

示例

SELECT *
FROM system.vector_indices 
WHERE 
    database = 'xxx'    
    AND table = 'yyy';  

您可参考向量检索最佳实践，了解使用 SQL 语句建表时配置向量检索的最佳实践。