稀疏向量索引使用指南

稀疏向量索引（SINDI）

稀疏向量仅存储非零元素及其索引位置，采用{索引:值}的形式表示。例如，一个100万维的向量若只有100个非零元素，稀疏表示仅需100个索引-值对，存储和计算效率远高于稠密表示。

稀疏向量索引适用于以下典型场景：

• 文本检索：SPLADE、BGE-M3等模型生成的文本嵌入向量通常为高维稀疏向量。

• 推荐系统：基于用户-物品交互特征构建的稀疏向量。

• 广告特征：基于用户画像和广告属性的稀疏特征向量。

HGraph索引

HGraph是Hologres的稠密向量索引方案，基于图索引算法，适用于低维稠密向量的近似最近邻检索。详细信息请参见HGraph索引使用指南（推荐）。

索引选择

选择建议：

• 如果您的数据来自SPLADE、BGE-M3等稀疏编码模型，或业务场景中向量维度极高但大部分元素为零（如文本嵌入、推荐特征），请选择稀疏向量索引。

• 如果您的数据为图像嵌入、语义向量等低维稠密向量，或需要使用Cosine、Euclidean距离、磁盘存储模式，请选择HGraph索引。

创建索引

您可以在建表时或建表后为稀疏向量列创建SINDI索引。

语法：

-- 建表时创建索引
CREATE TABLE <TABLE_NAME> (
    <COLUMN_NAME> SPARSEVECTOR,
    ...
) WITH (
    vectors = '{
    "<COLUMN_NAME>": {
        "algorithm": "Sindi",
        "distance_method": "InnerProduct",
        "builder_params": {
            "use_reorder": <TRUE|FALSE>,
            "term_id_limit": <INTEGER>,
            "doc_prune_ratio": <FLOAT>,
            "window_size": <INTEGER>
        }
    }}'
);

-- 建表后创建索引
ALTER TABLE <TABLE_NAME> SET (
    vectors = '{
    "<COLUMN_NAME>": {
        "algorithm": "Sindi",
        "distance_method": "InnerProduct",
        "builder_params": {
            "use_reorder": <TRUE|FALSE>,
            "term_id_limit": <INTEGER>,
            "doc_prune_ratio": <FLOAT>,
            "window_size": <INTEGER>
        }
    }}'
);

数据类型说明：

稀疏向量采用数据类型SPARSEVECTOR，包含无序的键值对，格式如下：'{索引:值, 索引:值, ...}'。其中，索引为不小于1的整数，且须小于term_id_limit参数值；值为浮点数。

示例：'{1:0.1, 50:0.8, 200:0.3}'

参数说明：

建表时创建索引示例：

CREATE TABLE sparse_test (
    id INT PRIMARY KEY,
    vec SPARSEVECTOR
) WITH (
    vectors = '{
    "vec": {
        "algorithm": "Sindi",
        "distance_method": "InnerProduct",
        "builder_params": {
            "use_reorder": true,
            "term_id_limit": 1000000,
            "doc_prune_ratio": 0.4,
            "window_size": 50000
        }
    }}'
);

修改索引

您可以通过ALTER TABLE修改稀疏向量索引的构建参数。

-- 修改文档剪枝比例
ALTER TABLE sparse_test SET (
    vectors = '{
    "vec": {
        "algorithm": "Sindi",
        "distance_method": "InnerProduct",
        "builder_params": {
            "use_reorder": true,
            "term_id_limit": 1000000,
            "doc_prune_ratio": 0.6,
            "window_size": 50000
        }
    }}'
);

修改参数后，新参数对后续构建的索引生效。您可以手动执行以下命令触发数据合并（Compaction）：

VACUUM <SCHEMA_NAME>.<TABLE_NAME>;

关于数据合并（Compaction）的更多信息，请参见Compaction。

删除索引

将vectors设置为空JSON对象即可删除稀疏向量索引。

ALTER TABLE sparse_test SET (vectors = '{}');

查看索引

通过查询hologres.hg_table_properties系统表查看稀疏向量索引的配置信息。

SELECT property_value
FROM hologres.hg_table_properties
WHERE table_name = 'sparse_test'
  AND property_key = 'vectors';

近似检索

使用approx_inner_product_distance函数配合ORDER BY ... DESC LIMIT k进行TopK近似检索。查询将自动命中SINDI索引。

SELECT id, approx_inner_product_distance(vec, '{1:0.1, 2:0.2, 3:0.3}') AS dist
FROM sparse_test
ORDER BY dist DESC
LIMIT 5;

精确检索

使用inner_product_distance函数进行精确检索（暴力计算），不走索引，适用于小数据量或需要精确结果的场景。

SELECT id, inner_product_distance(vec, '{1:0.1, 2:0.2, 3:0.3}') AS dist
FROM sparse_test
ORDER BY dist DESC
LIMIT 5;

验证索引是否命中

通过EXPLAIN ANALYZE查看执行计划，确认查询是否命中稀疏向量索引。

EXPLAIN ANALYZE
SELECT product_id,
       approx_inner_product_distance(feature, '{1:0.1, 50:0.7}') AS dist
FROM product_features
ORDER BY dist DESC
LIMIT 5;

执行计划中，稀疏向量列出现Vector Filter，则表示已命中稀疏向量索引。

Vector Filter: VectorCond => KNN: '5'::bigint distance_method: approx_inner_product_distance

构建参数调优

doc_prune_ratio是影响查询性能最关键的构建参数。增大该值可显著提升查询速度，但会牺牲一定的召回率。

开启use_reorder（设为true）可在保持高召回率的同时提升查询性能，推荐在高精度场景中开启。

查询参数调优

通过设置GUC参数调整查询时的性能与召回率平衡。

使用示例：

-- 设置查询参数
SET hg_vector_sindi_n_candidate = 500;
SET hg_vector_sindi_query_prune_ratio = 0.8;

-- 执行查询
SELECT id, approx_inner_product_distance(vec, '{1:0.1, 2:0.2}') AS dist
FROM sparse_test
ORDER BY dist DESC
LIMIT 10;

-- 重置为默认值
RESET hg_vector_sindi_n_candidate;
RESET hg_vector_sindi_query_prune_ratio;

场景推荐配置

以sparse-full数据集（884万向量，30109维，99.6%稀疏度）为例，推荐场景配置如下：