REFRESH VECTOR INDEX

Introduced or updated: v1.2.957

Builds missing vector index files for existing data using the current index definition and format.

Syntax

REFRESH VECTOR INDEX <index_name> ON [<database>.]<table_name>

When to Use REFRESH

Run REFRESH VECTOR INDEX in these cases:

• You create a vector index on a table that already contains data.
• You replace an index definition, for example to enable refine = true, and need to index existing blocks with the new definition.
• You need to build current-format index bundles for blocks that have only legacy index files. This behavior was introduced in v1.2.957.

New data writes automatically build indexes with the current definition. Refresh skips blocks that already have a matching current-version bundle. Older index files remain readable. Refresh removes a legacy file reference from the current block metadata only when no other active index needs it. VACUUM TABLE reclaims the file after retained snapshots no longer reference it.

Examples

Example: Index Existing Data

-- Step 1: Create a table without an index
CREATE TABLE products (
    id INT,
    name VARCHAR,
    embedding VECTOR(4)
) ENGINE = FUSE;

-- Step 2: Insert data (without index)
INSERT INTO products VALUES
    (1, 'Product A', [0.1, 0.2, 0.3, 0.4]),
    (2, 'Product B', [0.5, 0.6, 0.7, 0.8]),
    (3, 'Product C', [0.9, 1.0, 1.1, 1.2]);

-- Step 3: Create vector index on existing data
CREATE VECTOR INDEX idx_embedding ON products(embedding) distance='cosine';

-- Step 4: Refresh to build index for the 3 existing rows
REFRESH VECTOR INDEX idx_embedding ON products;

-- Step 5: New insertions are automatically indexed (no refresh needed)
INSERT INTO products VALUES (4, 'Product D', [1.3, 1.4, 1.5, 1.6]);