experimental_ivf_index¶

The experimental_ivf_index system variable controls whether the IVF-FLAT (Inverted File with Flat encoding) vector index plugin is enabled. When set to 0 (default), CREATE INDEX ... USING ivfflat statements are rejected. Set it to 1 before creating or rebuilding an IVF-FLAT index to perform approximate nearest neighbor (ANN) search on vector columns. This is an experimental feature gated by a session-level flag.

The experimental_ivf_index system variable gates access to the IVF-FLAT vector index algorithm in MatrixOne. IVF-FLAT partitions the vector space into clusters using k-means and searches only the nearest clusters during query time, offering a memory-efficient alternative to HNSW. Because this is an experimental feature, the variable defaults to 0 and must be explicitly enabled before use.

Syntax¶

SET GLOBAL experimental_ivf_index = 0; SET SESSION experimental_ivf_index = 1;

Query the current value:

SHOW VARIABLES LIKE ‘experimental_ivf_index’; SELECT @@experimental_ivf_index;

Arguments¶

Property	Value
Variable Type	`bool`
Scope	`Both`
Dynamic	`Yes`
Default Value	`0`
Optional Value	`0`, `1`

Examples¶

DROP DATABASE IF EXISTS ivf_demo;
CREATE DATABASE ivf_demo;
USE ivf_demo;

SET experimental_ivf_index = 1;

CREATE TABLE f(a BIGINT PRIMARY KEY, v VECF32(3));
INSERT INTO f VALUES (1, '[1,1,1]'), (2, '[2,2,2]'), (3, '[3,3,3]'), (4, '[8,8,8]');

CREATE INDEX ix USING ivfflat ON f(v) LISTS = 2 OP_TYPE 'vector_l2_ops' KMEANS_TRAIN_PERCENT 5 KMEANS_MAX_ITERATION 20;

SELECT a FROM f ORDER BY L2_DISTANCE(v, '[1,1,1]') ASC LIMIT 2;

SET experimental_ivf_index = 0;

DROP TABLE f;
DROP DATABASE ivf_demo;

Constraints¶

experimental_ivf_index defaults to 0. Attempting CREATE INDEX ... USING ivfflat while the variable is 0 causes the operation to fail.
IVF-FLAT is a CPU-only algorithm. It does not require GPU hardware.
IVF-FLAT supports the following build-option parameters: lists, kmeans_train_percent, and kmeans_max_iteration. These can be specified in the CREATE INDEX or ALTER TABLE ... ALTER REINDEX statement.
This is an experimental feature. Its behavior, performance characteristics, and API may change in future releases.