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(预排名模式)¶
在预排名模式下,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';
模式比较¶
模式 |
索引使用 |
排名策略 |
速度 |
准确性 |
适用场景 |
|---|---|---|---|---|---|
|
先使用 IVF 过滤 |
在 IVF 候选中排名 |
⚡ 最快 |
较低 |
高吞吐量、对延迟敏感 |
|
v4.2.5 中不使用 IVF |
全表扫描并按精确距离排序 |
大扫描时较慢 |
不受 IVF 候选裁剪限制 |
需要完整召回的过滤或多租户查询 |
|
使用 IVF 获取候选 |
用精确距离重新排名 |
🐢 较慢 |
⭐ 最高 |
高召回率需求 |
|
由规划器选择 IVF 或标量路径 |
取决于执行计划 |
取决于执行计划 |
取决于执行计划 |
让规划器选择,并检查 |
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';
最佳实践¶
选择合适的模式¶
实时应用(如边输边搜):使用
mode = pre批量处理且准确性重要:使用
mode = post过滤查询受 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度量模式选项必须指定为字符串字面量