Query-level IVF probe count

Use nprobe in BY RANK WITH OPTION to set the base IVF probe count for one query while leaving the session’s probe_limit unchanged.

Syntax

SELECT ... ORDER BY l2_distance(vector_column, query_vector)
LIMIT k BY RANK WITH OPTION 'nprobe=N';

SELECT ... ORDER BY l2_distance(vector_column, query_vector)
LIMIT k BY RANK WITH OPTION 'mode=post', 'nprobe=N';

Arguments

  • N is an integer from 1 through 80000. Zero, nonnumeric values, and values outside this range are rejected.

  • If the query supplies nprobe, it takes precedence over the session variable probe_limit for that query. Otherwise the session value is used; if it is unavailable, the planner falls back to 5.

  • The option does not change @@probe_limit. SET SESSION probe_limit affects later queries that omit nprobe.

  • In auto mode, the planner may widen this base probe count. Use EXPLAIN VERBOSE to inspect the chosen path.

Examples

DROP DATABASE IF EXISTS docs_ivf_nprobe;
CREATE DATABASE docs_ivf_nprobe;
USE docs_ivf_nprobe;
SET experimental_ivf_index = 1;
CREATE TABLE t (id BIGINT PRIMARY KEY, v VECF32(2));
INSERT INTO t VALUES (1, '[0,0]'), (2, '[1,1]'), (3, '[2,2]');
CREATE INDEX ix USING IVFFLAT ON t(v) LISTS=1 OP_TYPE 'vector_l2_ops';
SET SESSION probe_limit = 4;
SELECT id FROM t ORDER BY l2_distance(v, '[0,0]') LIMIT 2 BY RANK WITH OPTION 'nprobe=1';
SELECT id FROM t ORDER BY l2_distance(v, '[0,0]') LIMIT 2 BY RANK WITH OPTION 'mode=post', 'nprobe=9';
SELECT @@probe_limit;
DROP DATABASE docs_ivf_nprobe;

The two queries override the probe count independently. The final SELECT still returns the session value, 4. See IVF Rank Options for ranking modes.