vchord

Overview

Version

Build

You can build the RPM / DEB packages for vchord using pig build:

pig build pkg vchord         # build RPM / DEB packages

Install

You can install vchord directly. First, make sure the PGDG and PIGSTY repositories are added and enabled:

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

Install the extension using pig or apt/yum/dnf:

pig install vchord;          # Install for current active PG version

pig ext install -y vchord -v 18  # PG 18
pig ext install -y vchord -v 17  # PG 17
pig ext install -y vchord -v 16  # PG 16
pig ext install -y vchord -v 15  # PG 15
pig ext install -y vchord -v 14  # PG 14

dnf install -y vchord_18       # PG 18
dnf install -y vchord_17       # PG 17
dnf install -y vchord_16       # PG 16
dnf install -y vchord_15       # PG 15
dnf install -y vchord_14       # PG 14

apt install -y postgresql-18-vchord   # PG 18
apt install -y postgresql-17-vchord   # PG 17
apt install -y postgresql-16-vchord   # PG 16
apt install -y postgresql-15-vchord   # PG 15
apt install -y postgresql-14-vchord   # PG 14

Preload:

shared_preload_libraries = 'vchord';

Create Extension:

CREATE EXTENSION vchord CASCADE;  -- requires: vector

Usage

Sources:

• 1.1.1 README
• Control and dependency
• Preload requirement
• 1.1.1 SQL objects
• Query settings
• 1.1.1 migration
• 1.1.1 release notes

vchord adds approximate vector indexes to PostgreSQL using pgvector’s types. It provides the partition-based vchordrq and graph-based vchordg access methods. The extension requires vector, shared preloading, and superuser privileges to create.

Create and Query an Index

Add the library to the existing preload list, preserving other entries, and restart PostgreSQL:

shared_preload_libraries = 'vchord'

CREATE EXTENSION vchord CASCADE;
CREATE TABLE items (id bigserial PRIMARY KEY, embedding vector(3));
INSERT INTO items(embedding) VALUES ('[1,2,3]'), ('[4,5,6]');
CREATE INDEX items_embedding_idx ON items
USING vchordrq (embedding vector_l2_ops);

SELECT id FROM items ORDER BY embedding <-> '[3,1,2]' LIMIT 5;
SELECT vchordrq_prewarm('items_embedding_idx'::regclass);

Use vector_l2_ops with <->, vector_ip_ops with <#>, and vector_cosine_ops with <=>. The inner-product operator returns a negative value for ascending index ordering. The same operator classes can be used with the graph access method; choose one index design for the workload:

CREATE INDEX items_embedding_graph_idx ON items
USING vchordg (embedding vector_l2_ops);

Range Queries and Tuning

The extension supplies explicit sphere predicates for range search:

SELECT id FROM items
WHERE embedding <<->> sphere('[1,2,3]'::vector, 0.5);

SET vchordrq.probes = '100';
SET vchordrq.epsilon = 1.9;
SET vchordg.ef_search = 64;

<<->>, <<#>>, and <<=>> are sphere predicates for L2, inner product, and cosine metrics. Probe counts depend on the partition layout; tune them with representative data. The epsilon setting controls the reranking tradeoff. The graph search setting controls its candidate search breadth. Both index methods are approximate: check recall, filters, and query plans before choosing settings.

Quantization in 1.1.1

rabitq8 and rabitq4 store quantized vectors. quantize_to_rabitq8 and quantize_to_rabitq4 accept vector or halfvec. Version 1.1.1 adds dequantize_to_vector and dequantize_to_halfvec overloads for both quantized types:

SELECT dequantize_to_vector(quantize_to_rabitq8('[1,2,3]'::vector));
SELECT dequantize_to_halfvec(quantize_to_rabitq4('[1,2,3]'::halfvec));

Quantization loses precision; dequantization returns an approximation. The release also replaces the quantization implementation. Install matching library and SQL files, restart for the preloaded library, then update each database:

ALTER EXTENSION vchord UPDATE TO '1.1.1';

The 1.1.0-to-1.1.1 script adds these four conversion overloads and declares no index-format migration. Earlier-version upgrade requirements depend on the starting version. Index construction and prewarming consume resources; schedule them for the dataset size. vchordg_prewarm is the corresponding graph-index helper. The control is relocatable, so qualify extension objects or include their installation schema in the search path when installed outside the usual schema.