VectorChord (vchord) Documentation

repository·main·Indexed 22 days ago

https://github.com/supervc-stack/vectorchord

A high-performance PostgreSQL extension for billion-scale vector search. VectorChord utilizes RaBitQ compression (RaBitQ4 and RaBitQ8) and hierarchical K-means for efficient indexing and low-cost storage. It is fully compatible with pgvector data types and syntax, supporting the vchordrq index type for scalable vector similarity search.

Tokens: 10K
Snippets: 15
Records: 62
Agent score: 83%

What's inside VectorChord

Overview of VectorChord
main
VectorChord (vchord) is a PostgreSQL extension designed for high-performance, scalable, and cost-effective vector search. It is engineered to handle billion-scale vector datasets by applying RaBitQ compression and autonomous reranking.
Key capabilities include:
- Cost-Effective Storage: Uses low-bit data types (RaBitQ4 and RaBitQ8) to significantly reduce storage costs compared to other vector extensions.
- Fast Indexing: Utilizes hierarchical K-means and optimized disk operations to index large datasets (e.g., 100M vectors) rapidly.
- Scalability: Employs dimensionality reduction and sampling to control memory growth, allowing massive indexes to be built on machines with limited RAM.
- Compatibility: Fully compatible with pgvector data types and syntax, allowing for seamless migration from pgvector to VectorChord.
https://github.com/supervc-stack/vectorchord/blob/main/README.md
Understand the VectorChord licensing model
main
VectorChord is available under a dual license model. You can choose the license that best fits your requirements:
1. GNU Affero General Public License v3 (AGPLv3): Allows use, modification, and distribution under AGPLv3 terms.
2. Elastic License v2 (ELv2): Allows use, modification, and distribution under ELv2 terms (note that ELv2 contains specific restrictions).
For commercial collaboration or questions regarding licensing, contact vectorchord-inquiry@tensorchord.ai.
https://github.com/supervc-stack/vectorchord/blob/main/README.md
Install and Use VectorChord in PostgreSQL
main
Once your PostgreSQL instance is running, connect using psql and follow these steps to enable and use VectorChord:
1. Connect to the database (default user postgres):
  psql -h localhost -p 5432 -U postgres
2. Enable the extension: VectorChord depends on pgvector, so use CASCADE to ensure dependencies are met.
  CREATE EXTENSION IF NOT EXISTS vchord CASCADE;
3. Create a table and insert data: You can use standard vector types compatible with pgvector.
  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);
4. Create a VectorChord index: Use the vchordrq index type.
  CREATE INDEX ON items USING vchordrq (embedding vector_l2_ops);
5. Perform a vector search: Use standard SQL ORDER BY with distance operators (e.g., <-> for L2 distance).
  SELECT * FROM items ORDER BY embedding <-> '[3,1,2]' LIMIT 5;
https://github.com/supervc-stack/vectorchord/blob/main/README.md
Quick Start with Docker
main
The fastest way to start using VectorChord is via a Docker container. You can choose between the base image containing the extension or an all-in-one suite image.
Base Image: Contains the VectorChord extension. All-in-one Image (tensorchord/vchord-suite:pg17-latest): Includes VectorChord, VectorChord-bm25, and pg_tokenizer.rs.
Note: Ensure your image tag version matches your extension version as per the support matrix.
```
docker run \
  --name vectorchord-demo \
  -e POSTGRES_PASSWORD=mysecretpassword \
  -p 5432:5432 \
  -d ghcr.io/tensorchord/vchord-postgres:pg18-v1.1.1
```
https://github.com/supervc-stack/vectorchord/blob/main/README.md
Implement custom sampling with the Sampler and Sample traits
main
To implement custom sampling logic for index operations, you can implement the Sampler and Sample traits.
- Sampler: The entry point that produces a Sample instance via the sample() method.
- Sample: An iterator-like interface that provides tuples via the next() method.
- Tuple: An abstraction for the data retrieved during sampling. It provides id() to get the ItemPointerData and build() to extract the underlying data values and null bitmaps.
This pattern is used to bridge PostgreSQL's sampling scan mechanisms with Rust-based index operations.
```
pub trait Tuple {
    fn id(&mut self) -> ItemPointerData;
    fn build(&mut self) -> (&[Datum; 32], &[bool; 32]);
}

pub trait Sample {
    type Tuple<'a>: Tuple where Self: 'a;
    fn next(&mut self) -> Option<Self::Tuple<'_>>;
}

pub trait Sampler {
    type Sample: Sample;
    fn sample(&self) -> Self::Sample;
}
```
https://github.com/supervc-stack/vectorchord/blob/main/src/index/sample.rs
Configure VectorChordRQ build sources
main
VectorChordRQ allows you to specify how an index is built using VchordrqBuildSourceOptions. You can choose between three modes:
1. Default: Uses VchordrqDefaultBuildOptions (currently an empty configuration).
2. Internal: Uses VchordrqInternalBuildOptions for fine-grained control over the build process (e.g., K-Means parameters, threads, and sampling).
3. External: Uses VchordrqExternalBuildOptions to specify a target table (format: schema.table_name or just table_name).
These options are typically wrapped within a VchordrqBuildOptions struct.
https://github.com/supervc-stack/vectorchord/blob/main/src/index/vchordrq/types.rs

Configure VchordrqInternalBuildOptions

main

Use VchordrqInternalBuildOptions to tune the internal build parameters of the VectorChordRQ index.

Field	Type	Default	Constraints
`lists`	`Vec<u32>`	`[]`	Length 0-8; must be sorted ascending; values in range `1..=2^24`
`spherical_centroids`	`bool`	`false`	-
`sampling_factor`	`u32`	`256`	Range `1..=1024`
`kmeans_iterations`	`u32`	`10`	Range `0..=1024`
`build_threads`	`u16`	`1`	Range `1..=255`
`kmeans_algorithm`	`KMeansAlgorithm`	`Lloyd`	`lloyd` or `hierarchical`
`kmeans_dimension`	`Option<u32>`	`None`	Range `1..=16000`

Note: kmeans_algorithm uses snake_case in JSON (lloyd or hierarchical).

Configure VchordrqIndexOptions

main

When initializing a Vchordrq index, you can provide a VchordrqIndexOptions struct to tune performance and accuracy. This struct is serializable/deserializable and uses deny_unknown_fields to ensure configuration integrity.

Configuration Fields

Field	Type	Default	Description
`residual_quantization`	`bool`	`false`	Enables residual quantization for the index.
`rerank_in_table`	`bool`	`false`	Enables re-ranking within the table.
`degree_of_parallelism`	`u32`	`32`	Controls the level of parallelism. Must be between `1` and `256` inclusive.

Configure VchordrqExternalBuildOptions
main
When using the external build source, you must provide a table identifier. The identifier can be a simple table name or a qualified name in the format schema_name.table_name.
Validation Rules:
- Schema and table names must not be empty.
- They must start with an ASCII letter (A-Z, a-z) or an underscore (_).
- Subsequent characters can include alphanumeric characters, underscores, or dollar signs ($).
https://github.com/supervc-stack/vectorchord/blob/main/src/index/vchordrq/types.rs

Configure VchordgIndexOptions

main

The VchordgIndexOptions struct defines the configuration parameters for a VectorChordG index. It supports serialization and deserialization via serde and includes validation rules for each field.

Configuration Fields

Field	Type	Default	Constraints
`bits`	`u8`	`2`	Range: `1` to `2`
`m`	`u32`	`32`	Range: `1` to `512`
`alpha`	`Vec<f32>`	`[1.0, 1.2]`	Length: `1` to `8`. Must be sorted ascending, must contain `1.0`, and all values must be in the range `(1.0, 2.0)`
`ef_construction`	`u32`	`64`	Range: `1` to `65535`
`beam_construction`	`u32`	`1`	Range: `1` to `65535`

Configure VectorOptions
main
The VectorOptions struct defines the properties of the vectors used in the index. It must satisfy specific validation constraints.
Fields
Field Type Description
dim u32 The dimensionality of the vector. Must be between 1 and 60000 inclusive.
v VectorKind The underlying vector type/encoding.
d DistanceKind The distance metric used for comparison.
Supported VectorKind
Variant Bits per Element Description
Vecf32 32 32-bit floating point
Vecf16 16 16-bit floating point
Rabitq8 8 8-bit Rabitq quantization
Rabitq4 8 4-bit Rabitq quantization
Supported DistanceKind
Variant Description
L2S L2 Squared distance
Dot Dot product
https://github.com/supervc-stack/vectorchord/blob/main/crates/vchordrq/src/types.rs
Convert between f32 and Distance
main
You can convert between f32 and Distance using explicit methods or the From/Into traits. This is useful when you need to perform standard floating-point arithmetic or when you need to pass the value into a system expecting the optimized Distance type.
Methods:
- Distance::from_f32(value: f32) -> Distance
- Distance::to_f32(self) -> f32
- Distance::to_i32(self) -> i32 (returns the underlying integer representation)
Trait implementations:
- impl From<f32> for Distance
- impl From<Distance> for f32
https://github.com/supervc-stack/vectorchord/blob/main/crates/distance/src/lib.rs

Field	Type	Description
`dim`	`u32`	The dimensionality of the vector. Must be between `1` and `60000` inclusive.
`v`	`VectorKind`	The underlying vector type/encoding.
`d`	`DistanceKind`	The distance metric used for comparison.

Variant	Bits per Element	Description
`Vecf32`	32	32-bit floating point
`Vecf16`	16	16-bit floating point
`Rabitq8`	8	8-bit Rabitq quantization
`Rabitq4`	8	4-bit Rabitq quantization

Variant	Description
`L2S`	L2 Squared distance
`Dot`	Dot product

VectorChord (vchord) Documentation

What's inside VectorChord

Configuration Fields

Configuration Fields

Fields

Supported VectorKind

Supported DistanceKind