vectorscale

pgvectorscale : Advanced indexing for vector data with DiskANN

Overview

Packages

Source

pig build pkg pgvectorscale;		# build rpm/deb

Install

Make sure PGDG and PIGSTY repo available:

pig repo add pgsql -u   # add both repo and update cache

Install this extension with pig:

pig install pgvectorscale;		# install via package name, for the active PG version
pig install vectorscale;		# install by extension name, for the current active PG version

pig install vectorscale -v 18;   # install for PG 18
pig install vectorscale -v 17;   # install for PG 17
pig install vectorscale -v 16;   # install for PG 16
pig install vectorscale -v 15;   # install for PG 15
pig install vectorscale -v 14;   # install for PG 14

Create this extension with:

CREATE EXTENSION vectorscale CASCADE; -- requires vector

Usage

Sources:

• 0.9.1 README
• Control and dependency
• 0.9.1 migration SQL
• 0.9.1 security and upgrade notes

vectorscale adds the StreamingDiskANN approximate vector index to pgvector. Its diskann access method supports L2, inner product, cosine distance, and label filtering. It requires vector; creating the extension requires superuser privileges. Version 0.9.1 validates vector types, dimensions, and stored datum layouts to address crashes, memory disclosure, and out-of-bounds writes.

Core Workflow

Declare a concrete vector dimension and select the operator class matching the query distance:

CREATE EXTENSION vectorscale CASCADE;
CREATE TABLE documents (
    id bigserial PRIMARY KEY,
    contents text,
    embedding vector(3),
    labels smallint[]
);
INSERT INTO documents(contents, embedding, labels)
VALUES ('PostgreSQL search', '[1,2,3]', ARRAY[1,3]::smallint[]);
CREATE INDEX documents_diskann ON documents
USING diskann (embedding vector_cosine_ops, labels);

SELECT id, contents FROM documents
WHERE labels && ARRAY[1]::smallint[]
ORDER BY embedding <=> '[1,2,3]'::vector
LIMIT 10;

Use vector_l2_ops with <->, vector_ip_ops with <#>, or vector_cosine_ops with <=>. Labels use smallint[], and && means any requested label overlaps. Ordinary WHERE conditions are also supported, but selective filters can reduce the returned result count and need workload-specific testing.

Tuning and Ordering

diskann.query_search_list_size controls extra graph-search candidates (default 100); diskann.query_rescore controls exact rescoring (default 50, 0 disables it):

SET diskann.query_search_list_size = 200;
SET diskann.query_rescore = 100;

Build options include storage_layout, num_neighbors, search_list_size, and num_dimensions. Compressed memory-optimized storage is the default. Increase maintenance memory only after considering concurrent builds and dataset size. Parallel builds require the supported compression layout and do not support label columns in this version.

DiskANN returns relaxed distance ordering. Sort a materialized result set when strict ordering is required; this reorders the retrieved candidates without making approximate search exhaustive. Null vectors are not indexed, null labels act as empty arrays, and null array elements are ignored. Index creation on UNLOGGED tables is unsupported.

Upgrade to 0.9.1

Install matching extension files and update each database:

ALTER EXTENSION vectorscale UPDATE TO '0.9.1';

The upgrade binds operator classes to pgvector’s actual installation schema and checks existing bindings. If an existing operator class references the wrong type or operators, the upgrade aborts; follow the release instructions to drop the affected operator class and recreate extension objects, accounting for dependent indexes.

DiskANN now requires a valid vector(N) column type. An unconstrained vector column cannot be indexed. Existing indexes with invalid persisted dimensions raise errors during scans, inserts, and vacuum. Correct the column type, then drop and recreate the affected indexes: REINDEX cannot repair this condition. Valid existing indexes do not need a blanket rebuild merely because 0.9.1 was installed. The SQL surface is not relocatable after extension creation.