BY RANK WITH OPTION

BY RANK WITH OPTION 用于选择向量排名路径。在已验证的 v4.2.5 版本中,force 使用标量扫描,而非 IVF 索引扫描。

语法说明

BY RANK WITH OPTION 子句用于选择向量排名路径。不同模式可能使用 IVF(倒排文件)索引,也可能使用标量全表扫描;应通过 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

string

选择排名路径。可用值包括 pre、post、auto 和 force。

模式值

模式

描述

pre

预排名模式。在排名前使用 IVF 索引过滤候选项。速度最快但召回率可能较低。

force

在已验证的 v4.2.5 版本中,使用标量全表扫描和精确距离排序,不经过 IVF 索引扫描。

post

后排名模式。检索更多候选项后用精确距离重新排名。准确性更高但速度较慢。

auto

由优化器选择排名路径;通过 EXPLAIN 判断是否使用 IVF 索引。

在已验证的 v4.2.5 版本中,走索引的 pre 和 post 查询会排除向量为 NULL 的行;走标量扫描的 force 查询会包含这些行,升序时 NULL 距离排在前面。如需排除空向量,请添加 WHERE vector_column IS NOT NULL。auto 的行为取决于执行计划,详见 IVF 向量查询排名选项。

示例

基本用法

-- 预排名模式实现最快查询
SELECT id, name, l2_distance(embedding, '[1.0, 2.0, 3.0, 4.0]') AS distance
FROM products
ORDER BY l2_distance(embedding, '[1.0, 2.0, 3.0, 4.0]') ASC
LIMIT 10
BY RANK WITH OPTION 'mode = pre';

-- 强制模式:已验证的 v4.2.5 版本使用标量扫描和精确距离排序
SELECT id, name, l2_distance(embedding, '[1.0, 2.0, 3.0, 4.0]') AS distance
FROM products
ORDER BY l2_distance(embedding, '[1.0, 2.0, 3.0, 4.0]') ASC
LIMIT 10
BY RANK WITH OPTION 'mode = force';

-- 后排名模式实现最高准确性
SELECT id, name, l2_distance(embedding, '[1.0, 2.0, 3.0, 4.0]') AS distance
FROM products
ORDER BY l2_distance(embedding, '[1.0, 2.0, 3.0, 4.0]') ASC
LIMIT 10
BY RANK WITH OPTION 'mode = post';

完整示例

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

-- 插入示例数据
INSERT INTO documents VALUES (1, 'Document A', '[0.1, 0.2, 0.3, 0.4]');
INSERT INTO documents VALUES (2, 'Document B', '[0.5, 0.6, 0.7, 0.8]');
INSERT INTO documents VALUES (3, 'Document C', '[0.2, 0.3, 0.4, 0.5]');

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

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

-- 使用排名选项查询
SELECT id, title, l2_distance(embedding, '[0.1, 0.2, 0.3, 0.4]') AS distance
FROM documents
ORDER BY l2_distance(embedding, '[0.1, 0.2, 0.3, 0.4]') ASC
LIMIT 3
BY RANK WITH OPTION 'mode = post';

限制

  • 仅适用于 IVF 索引的向量列

  • 目前仅支持 l2_distance 度量

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

相关语句

有关详细使用示例和最佳实践,请参阅 IVF 向量查询排名选项。