Getting Started

• 1: Overview
• 2: Installation
• 3: Vchord Suite

1 - Overview

vchord is a PostgreSQL extension designed for scalable, high-performance, and disk-efficient vector similarity search.

With vchord, you can store 400,000 vectors for just $1, enabling significant savings: 6x more vectors compared to Pinecone’s optimized storage and 26x more than pgvector/pgvecto.rs for the same price¹. For further insights, check out our launch blog post.

Features

vchord introduces remarkable enhancements over pgvecto.rs and pgvector:

⚡ Enhanced Performance: Delivering optimized operations with up to 5x faster queries, 16x higher insert throughput, and 16x quicker¹ index building compared to pgvector’s HNSW implementation.

💰 Affordable Vector Search: Query 100M 768-dimensional vectors using just 32GB of memory, achieving 35ms P50 latency with top10 recall@95%, helping you keep infrastructure costs down while maintaining high search quality.

🔌 Seamless Integration: Fully compatible with pgvector data types and syntax while providing optimal defaults out of the box - no manual parameter tuning needed. Just drop in vchord for enhanced performance.

🔧 Accelerated Index Build: Leverage IVF to build indexes externally (e.g., on GPU) for faster KMeans clustering, combined with RaBitQ² compression to efficiently store vectors while maintaining search quality through autonomous reranking.

📏 Long Vector Support: Store and search vectors up to 60,000³ dimensions, enabling the use of the best high-dimensional models like text-embedding-3-large with ease.

🌐 Scale As You Want: Based on horizontal expansion, the query of 5M / 100M 768-dimensional vectors can be easily scaled to 10000+ QPS with top10 recall@90% at a competitive cost⁴

Quick Start

For new users, we recommend using the Docker image to get started quickly. If you do not prefer Docker, please read installation guide for other installation methods.

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

In addition to the base image with the VectorChord extension, we provide an all-in-one image, tensorchord/vchord-suite:pg18-latest. This comprehensive image includes all official TensorChord extensions. Developers should select an image tag that is compatible with their extension’s version, as indicated in the support matrix.

Then you can connect to the database using the psql command line tool. The default username is postgres, and the default password is mysecretpassword.

psql -h localhost -p 5432 -U postgres

Now you can play with VectorChord!

VectorChord depends on pgvector, including the vector representation. Since you can use them directly, your application can be easily migrated without pain!

CREATE EXTENSION IF NOT EXISTS vchord CASCADE;

Similar to pgvector, you can create a table with vector column and insert some rows to it.

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);

With VectorChord, you can create vchordrq indexes.

CREATE INDEX ON items USING vchordrq (embedding vector_l2_ops);

And then perform a vector search using SELECT ... ORDER BY ... LIMIT ....

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

For more usage, please read:

• Indexing
• Multi-Vector Retrieval
• Graph Index
• Quantization Types
• Similarity Filter
• PostgreSQL Tuning
• Monitoring
• Fallback Parameters
• Measure Recall
• Prewarm
• Prefilter
• Prefetch
• Rerank in Table
• Partitioning Tuning
• External Build

License

vchord is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0-only). We welcome any commercial collaboration or support inquiries—please email us at [email protected] with any questions.

2 - Installation

VectorChord is tested on the following operating system:

• Ubuntu (x86_64, aarch64)
• MacOS (x86_64, aarch64)
• Windows (x86_64)
• Alpine Linux (x86_64, aarch64) ¹
• Debian (powerpc64le, s390x, riscv64) ²

Please report a bug if you encounter issues on any of the above operating systems, or submit a feature request for additional platform support.

Docker

VectorChord Image

The easiest way to try VectorChord is to run it from a ready-to use Docker image.

1. Launch a VectorChord container in Docker.

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

2. Connect to the database using the psql command line tool. The default username is postgres.

psql postgresql://postgres:mysecretpassword@localhost:5432/postgres

3. Run the following SQL to ensure the extension is enabled.

CREATE EXTENSION IF NOT EXISTS vchord CASCADE;

VectorChord Suite Image

In addition to the base image with the VectorChord extension, we provide an all-in-one image, tensorchord/vchord-suite:pg18-latest. This comprehensive image includes all official TensorChord extensions. Developers should select an image tag that is compatible with their extension’s version, as indicated in the support matrix.

1. Launch a VectorChord container in Docker.

docker run \
  --name vchord-suite \
  -e POSTGRES_PASSWORD=postgres \
  -p 5432:5432 \
  -d tensorchord/vchord-suite:pg18-latest
  # If you want to use ghcr image, you can change the image to `ghcr.io/tensorchord/vchord-suite:pg18-latest`.
  # if you want to use the specific version, you can use the tag `pg17-20250815`, supported version can be found in the support matrix.

Other sections may align with the above.

VectorChord Scratch Image

We provide a scratch image that contains only the files of VectorChord. You can install VectorChord in any image using Docker’s COPY, like

FROM tensorchord/vchord-scratch:pg18-v1.1.1 AS vchord_scratch
FROM postgres:18-bookworm
RUN apt-get update && apt-get install -y postgresql-18-pgvector
COPY --from=vchord_scratch / /
CMD ["postgres", "-c" ,"shared_preload_libraries=vchord,vector"]

This image can also be used as a CloudNativePG image volume extension. See also

• Image Volume Extensions
• Kubernetes

Source

If you have not installed PostgreSQL yet, please install PostgreSQL. If you have not installed pgvector yet, you could install pgvector before the 3rd step.

1. Download the source code, build and install it with make.

curl -fsSL https://github.com/tensorchord/VectorChord/archive/refs/tags/1.1.1.tar.gz | tar -xz
cd VectorChord-1.1.1
make build
make install # or `sudo make install`

2. Configure your PostgreSQL by modifying the shared_preload_libraries to include the extension. And then restart the PostgreSQL cluster.

psql -U postgres -c 'ALTER SYSTEM SET shared_preload_libraries = "vchord"'

3. Run the following SQL to ensure the extension is enabled.

CREATE EXTENSION IF NOT EXISTS vchord CASCADE;

Tuning

VectorChord performs runtime CPU dispatch for SIMD code. If you want the compiler to optimize the whole program for a particular CPU, you could instruct it to generate code for that CPU.

RUSTFLAGS="-Ctarget-cpu=icelake" make build

To see all valid CPU options and the default CPU for your target triple, run:

rustc --print target-cpus

To generate code for the host machine, run:

RUSTFLAGS="-Ctarget-cpu=native" make build

Please note that binaries generated with a specific target-cpu are not compatible with other CPUs.

You can also do it by using Cargo’s configuration.

cd VectorChord-1.1.1
mkdir -p .cargo
touch .cargo/config.toml
echo 'build.rustflags = ["-Ctarget-cpu=icelake"]' >> ./cargo/config.toml

Debian

If you have not installed PostgreSQL yet, please install PostgreSQL following https://www.postgresql.org/download/linux/debian/. If you have not installed pgvector yet, you could install pgvector by apt install postgresql-18-pgvector before the 3rd step.

1. Download Debian packages in the release page, and install them by apt.

wget https://github.com/tensorchord/VectorChord/releases/download/1.1.1/postgresql-18-vchord_1.1.1-1_$(dpkg --print-architecture).deb
sudo apt install ./postgresql-18-vchord_1.1.1-1_$(dpkg --print-architecture).deb

2. Configure your PostgreSQL by modifying the shared_preload_libraries to include the extension. And then restart the PostgreSQL cluster.

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

3. Run the following SQL to ensure the extension is enabled.

CREATE EXTENSION IF NOT EXISTS vchord CASCADE;

Ubuntu

If you have not installed PostgreSQL yet, please install PostgreSQL following https://www.postgresql.org/download/linux/ubuntu/. If you have not installed pgvector yet, you could install pgvector by apt install postgresql-18-pgvector before the 3rd step.

1. Download Debian packages in the release page, and install them by apt.

wget https://github.com/tensorchord/VectorChord/releases/download/1.1.1/postgresql-18-vchord_1.1.1-1_$(dpkg --print-architecture).deb
sudo apt install ./postgresql-18-vchord_1.1.1-1_$(dpkg --print-architecture).deb

2. Configure your PostgreSQL by modifying the shared_preload_libraries to include the extension. And then restart the PostgreSQL cluster.

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

3. Run the following SQL to ensure the extension is enabled.

CREATE EXTENSION IF NOT EXISTS vchord CASCADE;

PGXN

If you have not installed PostgreSQL yet, please install PostgreSQL. If you have not installed pgvector yet, you could install pgvector by pgrxclient install vector before the 3rd step.

1. Install VectorChord from PostgreSQL Extension Network with:

pgxnclient install vchord # or `pgxnclient install vchord --sudo`

2. Configure your PostgreSQL by modifying the shared_preload_libraries to include the extension. And then restart the PostgreSQL cluster.

psql -U postgres -c 'ALTER SYSTEM SET shared_preload_libraries = "vchord"'

3. Run the following SQL to ensure the extension is enabled.

CREATE EXTENSION IF NOT EXISTS vchord CASCADE;

Prebuilt binaries

If you have not installed PostgreSQL yet, please install PostgreSQL. If you have not installed pgvector yet, you could install pgvector before the 3rd step.

1. Download prebuilt binaries in the release page, and repackage it referring to your distribution’s documentation. Then install it by system package manager. We do not recommend doing this, but if you wish, you can also manually copy the files to the system directory.

cp -r ./pkglibdir/. $(pg_config --pkglibdir)
cp -r ./sharedir/. $(pg_config --sharedir)

2. Configure your PostgreSQL by modifying the shared_preload_libraries to include the extension. And then restart the PostgreSQL cluster.

psql -U postgres -c 'ALTER SYSTEM SET shared_preload_libraries = "vchord"'

3. Run the following SQL to ensure the extension is enabled.

CREATE EXTENSION IF NOT EXISTS vchord CASCADE;

3 - Vchord Suite

Retrieval-Augmented Generation (RAG) is revolutionizing our interaction with vast datasets and language models. RAG systems offer more precise, contextually aware, and current answers by retrieving pertinent information before generating responses. Nonetheless, constructing robust, scalable, and efficient RAG pipelines poses considerable challenges, particularly for production use.

Many solutions feature complex architectures, using distinct databases for vector search, keyword search, and primary data storage. This commonly results in data synchronization challenges, greater infrastructure complexity, and higher operational costs.

What if you could build a powerful, production-ready RAG system directly within your trusted PostgreSQL database?

Enter the Vchord Suite, a collection of PostgreSQL extensions designed to bring high-performance vector search, native BM25 ranking, and flexible tokenization capabilities right into Postgres. Let’s explore the components and how they enable next-generation RAG solutions.

What is the Vchord Suite?

The suite comprises three key PostgreSQL extensions working in concert:

1. vchord (pgsty/vchord): The core vector search engine. It’s specifically designed for scalable, high-performance, and disk-efficient vector similarity search within PostgreSQL.

2. vchord_bm25 (pgsty/vchord_bm25): This extension implements the sophisticated BM25 ranking algorithm directly inside PostgreSQL, leveraging efficient Block-WeakAnd algorithms. BM25 is a standard for relevance ranking based on keyword frequency and document characteristics.

3. pg_tokenizer (pgsty/pg_tokenizer): Provides essential text tokenization capabilities needed for effective full-text search, enabling fine-grained control over how text is processed for full-text search.

By combining these extensions, you unlock powerful capabilities for building advanced RAG systems entirely within PostgreSQL.

How to Use the Vchord Suite

You can use the tensorchord/vchord-suite Docker image to run multiple extensions which are provided by TensorChord. The image is based on the Docker official PostgreSQL image and includes the following extensions:

• vchord
• pg_tokenizer
• vchord_bm25
• vector

docker run \
  --name vchord-suite \
  -e POSTGRES_PASSWORD=postgres \
  -p 5432:5432 \
  -d tensorchord/vchord-suite:pg18-latest

# If you want to use ghcr image, you can change the image to `ghcr.io/tensorchord/vchord-suite:pg18-latest`.
docker run \
  --name vchord-suite \
  -e POSTGRES_PASSWORD=postgres \
  -p 5432:5432 \
  -d tensorchord/vchord-suite:pg18-latest

# If you want to use the specific version, you can use the tag `pg17-20250414`, supported version can be found in the support matrix.
docker run \
  --name vchord-suite \
  -e POSTGRES_PASSWORD=postgres \
  -p 5432:5432 \
  -d tensorchord/vchord-suite:pg17-20250414

CREATE EXTENSION IF NOT EXISTS vchord CASCADE;
CREATE EXTENSION IF NOT EXISTS pg_tokenizer CASCADE;
CREATE EXTENSION IF NOT EXISTS vchord_bm25 CASCADE;
\dx
pg_tokenizer | 0.1.1   | tokenizer_catalog | pg_tokenizer
vchord       | 1.1.1   | public            | vchord: Vector database plugin for Postgres, written in Rust, specifically designed for LLM
vchord_bm25  | 0.3.0   | bm25_catalog      | vchord_bm25: A postgresql extension for bm25 ranking algorithm
vector       | 0.8.1   | public            | vector data type and ivfflat and hnsw access methods

Use Cases for the Vchord Suite

Use Case 1: Powerful Hybrid Search with Native BM25 and vchord

In the RAG era, effective retrieval is paramount. Neither keyword search nor vector search alone is perfect:

• Keyword Search (like BM25): Excels at precision, finding documents with exact keyword matches. It’s great for structured queries and term-specific searches. However, it struggles with synonyms, paraphrasing, and understanding the underlying meaning or semantic intent. (Leverages vchord_bm25 and pg_tokenizer).

• Vector Search: Captures deep semantic meaning and relationships between concepts, allowing it to find relevant information even if the exact keywords aren’t present. However, it can sometimes lack precision for queries demanding specific term matches. (Leverages vchord).

The Solution: Hybrid Search. By combining the strengths of both approaches within PostgreSQL, the Vchord Suite bridges this gap. You can run a query that leverages:

• vchord_bm25 (powered by pg_tokenizer) for keyword precision.

• vchord for semantic understanding.

The results from both can be intelligently combined (e.g., using reciprocal rank fusion - RRF or Model-based rerank) to produce a final ranking that is more accurate, contextually relevant, and semantically aware than either method could achieve alone. This delivers significantly better retrieval performance for your RAG applications.

Use Case 2: Beyond Text - OCR-Free RAG with ColQwen2 & vchord

Building RAG systems for documents like PDFs or scanned images often involves cumbersome pre-processing pipelines. Traditional methods rely heavily on Optical Character Recognition (OCR) and layout analysis to extract text. This process can be:

• Slow: OCR can be computationally expensive.

• Error-Prone: OCR accuracy varies significantly depending on document quality.

• Lossy: Crucial visual contexts like tables, figures, formatting, and relative positioning is often lost during text extraction.

The Solution: OCR-Free, Visually-Aware RAG. What if you could query documents based on how they look and their content, without explicit OCR?

This is now achievable by combining:

1. Multi-Modal Vision Language Models (VLMs): Models like ColQwen2 can process images (document pages) and generate embeddings that capture both textual content and visual layout information.

2. vchord’s Multi-Vector Capabilities: vchord can efficiently store and search multiple vectors per document within PostgreSQL – allowing you to store embeddings representing different aspects (e.g., text content, visual layout).

With this setup, you can query your document database using prompts that reference visual elements (“Find documents with a bar chart comparing sales figures”) or combined textual and visual cues, directly within PostgreSQL. This simplifies your RAG stack, potentially boosts retrieval accuracy by preserving visual context, and eliminates the bottlenecks associated with traditional OCR pipelines.

Why Build RAG in PostgreSQL?

Leveraging the Vchord Suite within PostgreSQL offers significant advantages:

• Unified Data: Keep your source data, text, metadata, and vector embeddings all in one place.

• Reduced Complexity: Eliminate the need for separate vector databases and synchronization pipelines.

• Leverage Existing Infrastructure: Utilize your existing PostgreSQL expertise, tooling, and operational practices.

• Transactional Integrity: Benefit from PostgreSQL’s robust ACID compliance.

• Rich Ecosystem: Access the wide array of tools and features available within the PostgreSQL ecosystem.

Conclusion

The Vchord Suite transforms PostgreSQL into a powerful, production-ready platform for building advanced RAG solutions. By integrating high-performance vector search (vchord), sophisticated keyword ranking (vchord_bm25), and flexible text processing (pg_tokenizer), you can implement cutting-edge techniques like hybrid search and OCR-free multi-modal retrieval directly within your database. Simplify your architecture, enhance retrieval accuracy, and unlock the full potential of RAG with Vchord in PostgreSQL.

Blog Posts

In our recent blog posts, we shared some user cases where all Docker images can be replaced with VectorChord Suite image.

• Supercharge vector search with ColBERT rerank in PostgreSQL

• Hybrid search with Postgres Native BM25 and VectorChord

• Beyond Text: Unlock OCR-Free RAG in PostgreSQL with Modal & VectorChord

References

• https://vchord.pgsty.com/blog/post/vectorchord-store-400k-vectors-for-1-in-postgresql/

• https://vchord.pgsty.com/blog/post/vectorchord-bm25-revolutionize-postgresql-search-with-bm25-ranking-3x-faster-than-elasticsearch/

• https://vchord.pgsty.com/blog/post/vectorchord-bm25-introducing-pgtokenizera-standalone-multilingual-tokenizer-for-advanced-search/