Nova 向量检索引擎

Novad 容量参考

Novam 容量参考

halfvec（半精度向量）

halfvec 使用半精度浮点数存储，内存占用约为 vector 的一半，适合对内存敏感的高维向量场景。

-- 创建 halfvec 类型的表
CREATE TABLE chunks_half (
    id SERIAL PRIMARY KEY,
    feature halfvec(1536)
) DISTRIBUTED BY (id);

-- 创建索引
CREATE INDEX idx_half ON chunks_half
USING ann(feature)
WITH (
    dim = 1536,
    algorithm = novamr,
    distancemeasure = cosine
);

sq8vector（SQ8 压缩向量）

sq8vector 以 INT8 格式存储向量，进一步压缩内存。配合 Novam 或 Novad 索引使用。

-- 创建 sq8vector 类型的表
CREATE TABLE chunks_sq8 (
    id SERIAL PRIMARY KEY,
    feature sq8vector(1536)
) DISTRIBUTED BY (id);

-- 创建 Novam 内存型 SQ8 索引
CREATE INDEX idx_sq8 ON chunks_sq8
USING ann(feature)
WITH (
    dim = 1536,
    algorithm = novam,
    distancemeasure = cosine
);

-- 也可创建 Novad 磁盘型 SQ8 索引
-- sq8vector + novadflat 自动切换为 novadsq8
CREATE INDEX idx_sq8_disk ON chunks_sq8
USING ann(feature)
WITH (
    dim = 1536,
    algorithm = novadflat,
    distancemeasure = cosine
);

稀疏向量（svector）

Nova 使用 svector 存储稀疏向量。每个稀疏向量包含两组一一对应的数据：

• indices：非零维度的编号（从 0 开始）。

• values：对应维度的值。

例如，一个 8 维稀疏向量，索引 2、3、6 对应的值分别为 1.2、1.1、0.7，其余位置为 0：

SELECT '{"indices":[2,3,6],"values":[1.2,1.1,0.7]}'::svector(8);

示例返回

                       svector
------------------------------------------------------
 {"indices":[2,3,6],"values":[1.2,1.1,0.7]}
(1 row)

创建稀疏向量表示例并创建索引：

DROP TABLE IF EXISTS sparse_docs;

CREATE TABLE sparse_docs (
    id         BIGINT PRIMARY KEY,
    title      TEXT NOT NULL,
    category   TEXT NOT NULL,
    publish_at TIMESTAMP NOT NULL,
    embedding  svector(8) NOT NULL
) DISTRIBUTED BY (id);

INSERT INTO sparse_docs(id, title, category, publish_at, embedding) VALUES
    (1, 'PostgreSQL 全文检索', 'search',    '2024-01-01',
        '{"indices":[1,3,7],"values":[0.8,1.5,0.4]}'),
    (2, 'Nova 稀疏向量检索',  'search',    '2024-02-01',
        '{"indices":[2,3,6],"values":[1.2,1.1,0.7]}'),
    (3, '向量数据库实践',      'vector',    '2024-03-01',
        '{"indices":[1,4,7],"values":[0.9,1.3,1.0]}'),
    (4, '数据分析基础',        'analytics', '2024-04-01',
        '{"indices":[5,7],"values":[1.4,0.6]}'),
    (5, '混合检索方案',        'search',    '2024-05-01',
        '{"indices":[2,4,6,7],"values":[0.6,1.1,1.2,0.9]}');

-- 使用内积衡量相关性，创建稀疏向量索引
CREATE INDEX sparse_docs_embedding_idx
ON sparse_docs
USING ann (embedding)
WITH (
    algorithm = 'novam',
    distancemeasure = 'ip'
);

ANALYZE sparse_docs;

使用一个 8 维查询向量返回最相关的 3 条数据：

SELECT
    id,
    title,
    category,
    -(embedding <#>
        '{"indices":[2,3,6],"values":[1,1,0.5]}'::svector(8)
     ) AS score
FROM sparse_docs
ORDER BY embedding <#>
    '{"indices":[2,3,6],"values":[1,1,0.5]}'::svector(8)
LIMIT 3;

示例返回

在上述查询中：

• <#> 计算负内积。负内积越小，内积越大，相关性越高。

• ORDER BY embedding <#> 查询向量 按相关性从高到低排序，并允许优化器使用 Nova 索引。

二值向量（bit）

bit 类型用于存储二值向量，适用于哈希指纹等场景。支持汉明距离和杰卡德距离。

-- 创建 bit 类型的表
CREATE TABLE chunks_bit (
    id SERIAL PRIMARY KEY,
    feature bit(256)
) DISTRIBUTED BY (id);

-- 使用汉明距离创建索引
CREATE INDEX idx_bit ON chunks_bit
USING ann(feature)
WITH (
    dim = 256,
    algorithm = novam,
    distancemeasure = hamming
);

使用示例

-- 将 id 和 url 列包含在索引中，支持 Index Only Scan 和 Index Scan 不回表
CREATE INDEX idx_feature_include ON chunks
USING ann(feature) INCLUDE (id, url)
WITH (
    dim = 1536,
    algorithm = novad,
    distancemeasure = cosine
);

Novam 查询参数

Novad 查询参数

通用查询参数

配置示例

使用索引 reloptions 固定单个索引的搜索参数：

-- 固定 Novam 索引参数
ALTER INDEX idx_feature_novam_l2 SET (
    nova_ef_search = 200,
    nova_max_scan_points = 5000
);

-- 固定 Novad 索引参数
ALTER INDEX idx_feature_novad_cosine SET (
    nova_nprobe = 20
);

reloption 为 -1 或已 RESET 时，查询改用当前会话 GUC：

ALTER INDEX idx_feature_novam_l2
RESET (nova_ef_search, nova_max_scan_points);

SET fastann.hnsw_ef_search = 200;
SET fastann.hnsw_max_scan_points = 5000;

启动调优

以下示例同时调优 topK = 10 和 100，目标召回率为 0.99。传入测试查询表 docs_eval_queries，可保证在该查询集上达到目标召回率。每个 topK 和 target_recall 组合分别保存一套配置；任务完成后，索引自动应用最大组合，即 topK = 100、target_recall = 0.99。

SELECT *
FROM fastann.nova_autotune(
    index_relation => 'public.docs_embedding_novam_idx'::regclass, -- 必填；无默认值；作用：指定待调优索引
    topk           => ARRAY[10, 100],                                        -- 必填；无默认值；作用：指定需要调优的 topK
    target_recall  => 0.99,                                        -- 可选；默认值：0.99；作用：指定目标召回率
    n_samples      => 100,                                              -- 可选；默认值：300；作用：指定采样查询数
    n_trials       => 100,                                               -- 可选；默认值：500；作用：指定候选配置试验数
    query_table    => 'public.docs_eval_queries'::regclass,           -- 可选；默认值：NULL；作用：指定测试查询表
    query_column   => 'embedding'                                   -- 可选；默认值：NULL；作用：指定查询向量列
) AS result(handle);

没有测试查询表时，省略 query_table 和 query_column。系统会根据索引内部数据生成查询并拟合参数：

SELECT *
FROM fastann.nova_autotune(
    index_relation => 'public.docs_embedding_novam_idx'::regclass, -- 必填；无默认值；作用：指定待调优索引
    topk           => ARRAY[10, 100],                                        -- 必填；无默认值；作用：指定需要调优的 topK
    target_recall  => 0.99,                                        -- 可选；默认值：0.99；作用：指定目标召回率
    n_samples      => 100,                                              -- 可选；默认值：300；作用：指定采样查询数
    n_trials       => 100                                                -- 可选；默认值：500；作用：指定候选配置试验数
) AS result(handle);

示例返回

  handle
-----------
 123456790
(1 row)

查看调优进度

使用 nova_autotune 返回的 handle 查看任务进度：

SELECT
    stage,
    query_count,
    work_done,
    work_total,
    updated_at
FROM fastann.nova_autotune_progress(
    handle => 123456789
);

示例返回

   stage    | query_count | work_done | work_total |       updated_at
------------+-------------+-----------+------------+------------------------
 evaluating |         300 |       126 |        500 | 2026-07-28 14:20:42+08
(1 row)

work_done / work_total 表示任务进度百分比。进度函数返回 0 行时，表示任务已结束或 handle 已不在活动状态，不代表调优失败；此时可通过 nova_autotune_status 查看已筛选的配置，并回读索引 Reloption。

手动切换参数配置

Autotune 会保存每组 topK 和 target_recall 对应的参数。查看索引已有的全部调优结果：

SELECT
    topk, target_recall, achieved, autotune_recall,
    ef_search, max_scan_points, nprobe, rescore_amp, applied
FROM fastann.nova_autotune_status(
    index_relation => 'public.docs_embedding_novam_idx'::regclass
)
ORDER BY topk, target_recall;

示例返回

 topk | target_recall | achieved | autotune_recall | ef_search | max_scan_points | nprobe | rescore_amp | applied
------+---------------+----------+-----------------+-----------+-----------------+--------+-------------+---------
   10 |          0.99 | t        |           0.992 |        80 |            3000 |      0 |         1.2 | f
  100 |          0.99 | t        |           0.991 |       240 |           12000 |      0 |         1.5 | t
(2 rows)

每组 topK 和 target_recall 对应一套参数配置，切换时必须同时指定两者：

-- 使用 topK=10 时达到 99% 召回率的配置
ALTER INDEX public.docs_embedding_novam_idx SET (
    nova_autotune_topk = 10,
    nova_autotune_recall = 0.99
);

-- 切换到 topK=100 时达到 99% 召回率的配置
ALTER INDEX public.docs_embedding_novam_idx SET (
    nova_autotune_topk = 100,
    nova_autotune_recall = 0.99
);

启用兼容模式

当前版本使用 pgvector 兼容模式前，请提交工单申请开通。开通完成后，普通用户即可创建和使用 pgvector 兼容索引。

如需使 <-> 返回与 pgvector 一致的欧氏距离，请在会话中设置 fastann.pgvector_compatibility = on；仅用于 TopK 排序且不读取距离值或按距离过滤时，无需设置。

索引语法与 Nova 后端

可直接使用 pgvector 索引语法，距离度量由运算符类确定：

CREATE INDEX docs_embedding_hnsw_idx
ON docs USING hnsw (embedding vector_cosine_ops)
WITH (m = 16, ef_construction = 64);

CREATE INDEX docs_embedding_ivfflat_idx
ON docs USING ivfflat (embedding vector_cosine_ops)
WITH (lists = 1024);

hnsw 和 ivfflat 的算法及距离度量分别由访问方法和运算符类决定。即使同时指定 algorithm 或 distancemeasure，也不会改变上述映射。

支持的运算符类

参数映射

兼容 IVFFlat 查询通过 nova_nprobe 调整搜索范围；未设置时继承 fastann.nova_nprobe，默认值为 5。ivfflat.probes 和 fastann.ivfflat_probes 对该兼容索引不生效。

限制

• 不支持在 Nova 索引上使用 L1 运算符类。创建 vector_l1_ops 或 halfvec_l1_ops 索引会报错。

• sparsevec 的余弦运算符类暂不支持 Nova 索引。余弦检索需要将索引向量和查询向量归一化后按内积搜索，当前 Nova 构建链路尚未接通稀疏向量的归一化处理。请使用 L2 或内积替代。

• ivfflat 仅支持 vector 和 halfvec 的 L2、内积和余弦距离。

• pgvector 语法映射到 Nova 后端，索引结构、量化方式、存储占用、召回率和性能特征与原生 pgvector 不完全相同。

• svector 最多支持 10 亿维，最多包含 4,000 个非零值。indices 和 values 必须包含相同数量的元素。values 必须是有限数值，不能包含 NaN、Infinity 或 -Infinity。