IVF 向量查询排名选项

概述

MatrixOne 提供 BY RANK WITH OPTION 子句来选择向量排名查询的执行路径。不同模式的索引使用情况不同,应通过 EXPLAIN 确认实际计划。

语法

SELECT column_list
FROM table_name
ORDER BY distance_function(vector_column, query_vector) ASC
LIMIT k
BY RANK WITH OPTION 'mode = <mode>';

参数

参数

描述

mode

选择排名路径,可使用 pre、post、auto 和 force。

模式选项

mode = pre(预排名模式)

在预排名模式下,IVF 索引用于在应用排名函数之前过滤候选向量。此模式:

  • 行为:首先使用 IVF 索引选择候选质心,然后在这些候选中应用排名

  • 性能:执行速度最快,因为排名仅应用于数据子集

  • 准确性:如果相关结果位于未被探测限制选中的质心中,可能会遗漏

使用场景:高吞吐量场景,查询速度优先于完美召回率。

-- 示例:预排名模式
SELECT id, content, l2_distance(embedding, '[1.0, 2.0, 3.0, 4.0]') AS distance
FROM documents
ORDER BY l2_distance(embedding, '[1.0, 2.0, 3.0, 4.0]') ASC
LIMIT 10
BY RANK WITH OPTION 'mode = pre';

mode = force(强制模式)

在已验证的 v4.2.5 行为中,force 使用标量全表扫描和距离排序,不会强制使用 IVF 索引。EXPLAIN 显示 Table Scan + Sort(l2_distance)。此模式:

  • 行为:对满足 WHERE 条件的行计算精确距离并排序

  • 性能:需要扫描并排序候选行,大数据量时可能比索引检索慢

  • 召回:不受 IVF 候选集裁剪限制,适用于需要较高召回的过滤或多租户查询

使用场景:查询结果不能受 IVF 候选集限制时;应结合实际计划和延迟评估。

-- 示例:强制模式
SELECT id, content, l2_distance(embedding, '[1.0, 2.0, 3.0, 4.0]') AS distance
FROM documents
ORDER BY l2_distance(embedding, '[1.0, 2.0, 3.0, 4.0]') ASC
LIMIT 10
BY RANK WITH OPTION 'mode = force';

mode = post(后排名模式)

在后排名模式下,排名函数在 IVF 索引检索出扩展的候选集之后应用。此模式:

  • 行为:从 IVF 索引检索更多候选项,然后使用精确距离计算对它们重新排名

  • 性能:比预排名慢,但比全表扫描快

  • 准确性:更高的准确性,因为最终排名基于精确距离计算

使用场景:需要高召回率且精确排名很重要的场景。

-- 示例:后排名模式
SELECT id, content, l2_distance(embedding, '[1.0, 2.0, 3.0, 4.0]') AS distance
FROM documents
ORDER BY l2_distance(embedding, '[1.0, 2.0, 3.0, 4.0]') ASC
LIMIT 10
BY RANK WITH OPTION 'mode = post';

模式比较

模式

索引使用

排名策略

速度

准确性

适用场景

pre

先使用 IVF 过滤

在 IVF 候选中排名

⚡ 最快

较低

高吞吐量、对延迟敏感

force

v4.2.5 中不使用 IVF

全表扫描并按精确距离排序

大扫描时较慢

不受 IVF 候选裁剪限制

需要完整召回的过滤或多租户查询

post

使用 IVF 获取候选

用精确距离重新排名

🐢 较慢

⭐ 最高

高召回率需求

auto

由规划器选择 IVF 或标量路径

取决于执行计划

取决于执行计划

取决于执行计划

让规划器选择,并检查 EXPLAIN

NULL 向量值

对于可空向量列,标量查询 ORDER BY l2_distance(vector_column, query) ASC LIMIT k 会包含向量为 NULL 的行;其距离为 NULL,升序排序时排在前面。在已验证的 v4.2.5 IVF 路径中,裸索引化 ORDER BY 及 pre、post 会排除 NULL 向量;issue 中测试的 auto 查询也选择了该路径。force 使用标量扫描,因此仍可能先返回 NULL 行。auto 在小数据集或高选择性过滤下也可能选择标量扫描,此时 NULL 行为取决于所选计划。要排除它们,请添加 WHERE vector_column IS NOT NULL;也可以将列声明为 NOT NULL,在写入时拒绝空值。请用 EXPLAIN 确认查询路径。

完整示例

设置

-- 创建带向量列的表
CREATE TABLE products (
    id BIGINT PRIMARY KEY,
    name VARCHAR(200),
    embedding VECF32(4)
);

-- 插入示例数据
INSERT INTO products VALUES (1, 'Product A', '[0.1, 0.2, 0.3, 0.4]');
INSERT INTO products VALUES (2, 'Product B', '[0.5, 0.6, 0.7, 0.8]');
INSERT INTO products VALUES (3, 'Product C', '[0.2, 0.3, 0.4, 0.5]');
INSERT INTO products VALUES (4, 'Product D', '[0.9, 0.8, 0.7, 0.6]');
INSERT INTO products VALUES (5, 'Product E', '[0.3, 0.4, 0.5, 0.6]');

-- 创建 IVF 索引
CREATE INDEX idx_products_embedding
USING IVFFLAT ON products(embedding)
LISTS=2 OP_TYPE "vector_l2_ops";

-- 设置查询的探测限制
SET @PROBE_LIMIT = 1;

查询示例

-- 快速近似搜索(预排名)
SELECT id, name, l2_distance(embedding, '[0.1, 0.2, 0.3, 0.4]') AS distance
FROM products
ORDER BY l2_distance(embedding, '[0.1, 0.2, 0.3, 0.4]') ASC
LIMIT 3
BY RANK WITH OPTION 'mode = pre';

-- 全表扫描和精确排序(v4.2.5 的 force 模式)
SELECT id, name, l2_distance(embedding, '[0.1, 0.2, 0.3, 0.4]') AS distance
FROM products
ORDER BY l2_distance(embedding, '[0.1, 0.2, 0.3, 0.4]') ASC
LIMIT 3
BY RANK WITH OPTION 'mode = force';

-- 高准确度搜索(后排名)
SELECT id, name, l2_distance(embedding, '[0.1, 0.2, 0.3, 0.4]') AS distance
FROM products
ORDER BY l2_distance(embedding, '[0.1, 0.2, 0.3, 0.4]') ASC
LIMIT 3
BY RANK WITH OPTION 'mode = post';

最佳实践

选择合适的模式

  1. 实时应用(如边输边搜):使用 mode = pre

  2. 批量处理且准确性重要:使用 mode = post

  3. 过滤查询受 IVF 候选裁剪影响召回时:对比 mode = force 与索引模式,并查看 EXPLAIN

结合探测限制使用

@PROBE_LIMIT 控制索引路径扫描的 IVF 质心数量;在已验证的 v4.2.5 行为中,它不会使 force 使用 IVF 索引:

-- 高准确度配置
SET @PROBE_LIMIT = 10;

SELECT id, name, l2_distance(embedding, '[0.1, 0.2, 0.3, 0.4]') AS distance
FROM products
ORDER BY l2_distance(embedding, '[0.1, 0.2, 0.3, 0.4]') ASC
LIMIT 5
BY RANK WITH OPTION 'mode = post';
-- 高速度配置
SET @PROBE_LIMIT = 1;

SELECT id, name, l2_distance(embedding, '[0.1, 0.2, 0.3, 0.4]') AS distance
FROM products
ORDER BY l2_distance(embedding, '[0.1, 0.2, 0.3, 0.4]') ASC
LIMIT 5
BY RANK WITH OPTION 'mode = pre';

性能调优

  • 大多数用例从 mode = pre 开始

  • 监控召回率,如果准确性不足则切换到 mode = post

  • 使用 mode = force 前,评估全表扫描代价,并检查可空向量是否需要显式 IS NOT NULL 过滤

限制

  • 索引模式需要可用的 IVF 索引;在已验证的 v4.2.5 行为中,force 走标量扫描路径

  • 目前仅支持 l2_distance 度量

  • 模式选项必须指定为字符串字面量

相关文档