vchord

vchord is a PostgreSQL extension engineered for scalable, high-performance, and disk-friendly vector similarity search, serving as the successor to pgvecto.rs.

Website | Documentation | vchord_bm25 | pg_tokenizer | Blog | PGEXT | Pigsty (中文) | Releases | Issues

---

To store vectors compactly while preserving recall, vchord combines RaBitQ¹ quantization with inverted-file (vchordrq) and single-layer graph (vchordg) indexes plus in-database reranking. It stores up to 400,000 vectors per $1—roughly 6x more vectors per dollar than Pinecone's storage-optimized tier and 26x more than in-memory pgvector / pgvecto.rs HNSW indexes.

---

Vchord Suite

vchord is the core extension of the Vchord family maintained by PGSTY:

• vchord (pgsty/vchord · PGEXT · Pigsty): Scalable, high-performance, and disk-friendly vector similarity search (vchordrq & vchordg).
• vchord_bm25 (pgsty/vchord_bm25 · PGEXT · Pigsty): Native BM25 full-text ranking index (Block-WeakAnd).
• pg_tokenizer (pgsty/pg_tokenizer · PGEXT · Pigsty): Standalone multilingual text analyzer and vocabulary tokenizer.

---

Features

• Cost-Effective Storage: Host 100M × 768-dim vectors on a single AWS i4i.xlarge ($247/mo)², or scale to 1B × 96-dim vectors on an i7ie.6xlarge ($2,246/mo)³ by keeping only compact centroids in RAM and streaming quantized lists from NVMe SSD.
• Fast Index Construction: Build a 100M-vector index in ~20 minutes using hierarchical K-means⁴ or external index precomputation.
• Bounded Memory Growth: Control index build memory via dimensionality reduction and sampling⁵, enabling billion-scale index builds on 128 GB RAM nodes.
• Drop-In pgvector Compatibility: Directly indexes pgvector data types (vector, halfvec) and supports standard distance operators (<->, <#>, <=>) alongside multi-vector MaxSim (@#) retrieval.
• Native Low-Bit Quantization Types: Provides native 4-bit (rabitq4) and 8-bit (rabitq8) vector types with <1% recall loss on rabitq8.

---

Quick Start

For full setup instructions (Debian/Ubuntu packages, PGXN, Kubernetes, and source builds), see the Installation Guide.

1. Install via Native Linux Packages (pig)

On EL 8/9/10, Debian 12/13, and Ubuntu 22.04/24.04 (PostgreSQL 14–18), you can install pre-built native packages from the Pigsty repository (see package matrix on pgext.cloud):

curl -fsSL https://repo.pigsty.io/pig | bash
pig repo add pgsql -u
pig ext add vchord

Then add vchord to shared_preload_libraries and restart PostgreSQL:

psql -U postgres -c 'ALTER SYSTEM SET shared_preload_libraries = "vchord"'
sudo systemctl restart postgresql

2. Run with Docker

To spin up a ready-to-use PostgreSQL 18 container with vchord preloaded:

docker run \
  --name vchord-demo \
  -e POSTGRES_PASSWORD=mysecretpassword \
  -p 5432:5432 \
  -d ghcr.io/tensorchord/vchord-postgres:pg18-v1.1.1

Note

For hybrid vector + full-text search, use the all-in-one tensorchord/vchord-suite:pg18-latest image, which bundles vchord, vchord_bm25, and pg_tokenizer.

Connect to the instance with psql:

psql -h localhost -p 5432 -U postgres

3. Basic SQL Usage

Enable the extension (this automatically enables pgvector as well):

CREATE EXTENSION IF NOT EXISTS vchord CASCADE;

Create a table with a vector column and insert sample data:

CREATE TABLE items (id bigserial PRIMARY KEY, embedding vector(3));

INSERT INTO items (embedding)
SELECT ARRAY[random(), random(), random()]::real[]
FROM generate_series(1, 1000);

Build a vchordrq index and run a nearest-neighbor query:

CREATE INDEX ON items USING vchordrq (embedding vector_l2_ops);

SELECT * FROM items ORDER BY embedding <-> '[3, 1, 2]' LIMIT 5;

When tuning vchordrq, use one comma-separated probes value per level in build.internal.lists. Each value must be in 0..=4294967295; empty entries and trailing commas are invalid. An empty string is valid for lists = []. For vchordg, alpha must contain 1–8 ascending values starting with 1.0, all below 2.0.

PostgreSQL 19 RC1 validation

PostgreSQL 19 is a prerelease. The pg19 feature and C API compatibility code are available in main for development validation; official support and packages remain PostgreSQL 14–18. RC1 source builds have been validated on Linux x86_64 and macOS arm64 with Rust 1.99.1, pgrx 0.19.3, and pgvector 0.8.7, including PostgreSQL assertions and the full SQL regression suite.

Install pgvector for PostgreSQL 19, then build and install vchord against the RC1 installation's pg_config:

git clone https://github.com/pgsty/vchord.git
cd vchord
PG_CONFIG=/path/to/pg19/bin/pg_config make build
make PG_CONFIG=/path/to/pg19/bin/pg_config install # use sudo if required

Add vchord to that server's shared_preload_libraries, restart it, and run CREATE EXTENSION IF NOT EXISTS vchord CASCADE;. PostgreSQL 19 is not included in the CI or release matrices. Formal release support will be considered after PostgreSQL 19 GA and a fresh compatibility check.

---

Documentation

Full documentation is available at vchord.pgsty.com/docs:

• Getting Started
  • Overview
  • Installation
  • Vchord Suite
• Indexing & Querying
  • Indexing (vchordrq)
  • Graph Index (vchordg)
  • Quantization Types (rabitq4 / rabitq8)
  • Multi-Vector Retrieval (MaxSim)
  • Similarity Filter (Range Query)
  • Prefilter & Rerank in Table
• Tuning & Operations
  • Partitioning Tuning
  • External Index Build
  • PostgreSQL Tuning
  • Prewarm & Prefetch
  • Monitoring, Measure Recall, & Fallback Parameters
• Benchmarks & Use Cases
  • Performance & Price Benchmarks
  • Hybrid Search & ColBERT Rerank

---

License

This software is licensed under the GNU Affero General Public License v3.0 (AGPLv3). You may use, modify, and distribute this software under the terms of the AGPLv3.

• Copyright (c) 2025-2026 TensorChord Inc.
• Copyright (c) 2026 PGSTY PTE. LTD.
• Maintained by Ruohang Feng @ PGSTY

Footnotes

1. Gao, Jianyang, and Cheng Long. "RaBitQ: Quantizing High-Dimensional Vectors with a Theoretical Error Bound for Approximate Nearest Neighbor Search." Proceedings of the ACM on Management of Data 2.3 (2024): 1–27. ↩

2. See Store 400k Vectors for $1 in PostgreSQL. ↩

3. See Scaling Vector Search to 1 Billion on PostgreSQL. ↩

4. See How We Made 100M Vector Indexing in 20 Minutes Possible on PostgreSQL and Partitioning Tuning. ↩

5. See Dimensionality Reduction and Sampling Factor Tuning. ↩