# supervc-stack/vectorchord architecture

> Architecture diagram of the GitHub repository supervc-stack/vectorchord, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/supervc-stack/vectorchord
- Repository: https://github.com/supervc-stack/vectorchord

## Overview

VectorChord is a PostgreSQL extension for storing and searching vectors through RaBitQ-compressed and graph-based indexes. The principal workflow is a SQL client creating vector data and an index, then issuing an ordered similarity query whose selected index scans return matching rows. The README also documents accelerated index construction, multi-vector retrieval, filters, reranking, prefetching, and prewarming. The excerpts establish extension initialization, PostgreSQL page access, and parts of both search engines; several other links reflect documented capabilities and module boundaries rather than inspected call sites.

Main entry points: [`src/index/vchordrq/build.rs`](https://github.com/supervc-stack/vectorchord/blob/main/src/index/vchordrq/build.rs) (RaBitQ build), [`crates/vchordrq/src/search.rs`](https://github.com/supervc-stack/vectorchord/blob/main/crates/vchordrq/src/search.rs) (RaBitQ search), [`src/index/vchordrq/dispatch.rs`](https://github.com/supervc-stack/vectorchord/blob/main/src/index/vchordrq/dispatch.rs) (RaBitQ dispatch), [`src/index/storage.rs`](https://github.com/supervc-stack/vectorchord/blob/main/src/index/storage.rs) (PostgreSQL pages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_pg["PostgreSQL interface"]
  node_extension["Extension init<br/>[lib.rs]"]
  node_types["Vector types<br/>[mod.rs]"]
  node_recorder["Query recorder<br/>[mod.rs]"]
  node_recorder_store[("Recorder storage<br/>[worker.rs]")]
end

subgraph group_index["Index lifecycle"]
  node_index_init["Index registration<br/>[mod.rs]"]
  node_am_rq["RaBitQ access method<br/>[mod.rs]"]
  node_am_g["Graph access method<br/>[mod.rs]"]
  node_rq_dispatch["RaBitQ dispatch<br/>[dispatch.rs]"]
  node_g_dispatch["Graph dispatch<br/>[dispatch.rs]"]
  node_rq_build["RaBitQ build<br/>[build.rs]"]
  node_g_build["Graph build"]
  node_pages[("PostgreSQL pages<br/>[storage.rs]")]
  node_scan["Scan and filtering<br/>[mod.rs]"]
  node_results["Scan results<br/>[default.rs]"]
end

subgraph group_engines["Search engines"]
  node_rq_search["RaBitQ search<br/>[search.rs]"]
  node_g_search["Graph search<br/>[search.rs]"]
  node_rerank["Autonomous reranking<br/>[rerank.rs]"]
end

subgraph group_compute["Vector compute"]
  node_clustering["Hierarchical K-means<br/>[hierarchical.rs]"]
  node_quantization["RaBitQ encoding<br/>[lib.rs]"]
  node_vector_ops["Vector operations<br/>[lib.rs]"]
end

node_client(("SQL client"))

node_client -->|"uses SQL"| node_extension
node_extension -->|"initializes"| node_index_init
node_extension -->|"initializes"| node_recorder
node_client -->|"writes vectors"| node_types
node_client -->|"creates and scans"| node_am_rq
node_client -.->|"creates and scans"| node_am_g
node_am_rq -->|"dispatches"| node_rq_dispatch
node_am_g -->|"dispatches"| node_g_dispatch
node_rq_dispatch -->|"builds index"| node_rq_build
node_g_dispatch -->|"builds index"| node_g_build
node_rq_dispatch -->|"searches"| node_rq_search
node_g_dispatch -->|"searches"| node_g_search
node_rq_build -->|"writes pages"| node_pages
node_g_build -->|"writes pages"| node_pages
node_rq_search -->|"reads pages"| node_pages
node_g_search -->|"reads pages"| node_pages
node_am_rq -->|"sets up scans"| node_scan
node_scan -->|"dispatches search"| node_rq_dispatch
node_scan -->|"emits rows"| node_results
node_rq_search -.->|"reranks candidates"| node_rerank
node_rq_build -.->|"clusters vectors"| node_clustering
node_rq_build -->|"encodes vectors"| node_quantization
node_g_build -->|"processes vectors"| node_vector_ops
node_rq_search -->|"scores vectors"| node_vector_ops
node_g_search -->|"scores vectors"| node_vector_ops
node_recorder -->|"records samples"| node_recorder_store

click node_extension "https://github.com/supervc-stack/vectorchord/blob/main/src/lib.rs"
click node_types "https://github.com/supervc-stack/vectorchord/blob/main/src/datatype/mod.rs"
click node_index_init "https://github.com/supervc-stack/vectorchord/blob/main/src/index/mod.rs"
click node_am_rq "https://github.com/supervc-stack/vectorchord/blob/main/src/index/vchordrq/am/mod.rs"
click node_am_g "https://github.com/supervc-stack/vectorchord/blob/main/src/index/vchordg/am/mod.rs"
click node_rq_dispatch "https://github.com/supervc-stack/vectorchord/blob/main/src/index/vchordrq/dispatch.rs"
click node_g_dispatch "https://github.com/supervc-stack/vectorchord/blob/main/src/index/vchordg/dispatch.rs"
click node_rq_build "https://github.com/supervc-stack/vectorchord/blob/main/src/index/vchordrq/build.rs"
click node_pages "https://github.com/supervc-stack/vectorchord/blob/main/src/index/storage.rs"
click node_rq_search "https://github.com/supervc-stack/vectorchord/blob/main/crates/vchordrq/src/search.rs"
click node_g_search "https://github.com/supervc-stack/vectorchord/blob/main/crates/vchordg/src/search.rs"
click node_scan "https://github.com/supervc-stack/vectorchord/blob/main/src/index/vchordrq/scanners/mod.rs"
click node_results "https://github.com/supervc-stack/vectorchord/blob/main/src/index/vchordrq/scanners/default.rs"
click node_rerank "https://github.com/supervc-stack/vectorchord/blob/main/crates/vchordrq/src/rerank.rs"
click node_clustering "https://github.com/supervc-stack/vectorchord/blob/main/crates/k_means/src/hierarchical.rs"
click node_quantization "https://github.com/supervc-stack/vectorchord/blob/main/crates/rabitq/src/lib.rs"
click node_vector_ops "https://github.com/supervc-stack/vectorchord/blob/main/crates/vector/src/lib.rs"
click node_recorder "https://github.com/supervc-stack/vectorchord/blob/main/src/recorder/mod.rs"
click node_recorder_store "https://github.com/supervc-stack/vectorchord/blob/main/src/recorder/worker.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_extension,node_types,node_recorder,node_recorder_store,node_client toneBlue
class node_index_init,node_am_rq,node_am_g,node_rq_dispatch,node_g_dispatch,node_rq_build,node_g_build,node_pages,node_scan,node_results toneAmber
class node_rq_search,node_g_search,node_rerank toneMint
class node_clustering,node_quantization,node_vector_ops toneRose
```

## Components

### PostgreSQL interface

- [Extension init](https://github.com/supervc-stack/vectorchord/blob/main/src/lib.rs): `src/lib.rs`
- [Vector types](https://github.com/supervc-stack/vectorchord/blob/main/src/datatype/mod.rs): `src/datatype/mod.rs`
- [Query recorder](https://github.com/supervc-stack/vectorchord/blob/main/src/recorder/mod.rs): `src/recorder/mod.rs`
- [Recorder storage](https://github.com/supervc-stack/vectorchord/blob/main/src/recorder/worker.rs): `src/recorder/worker.rs`

### Index lifecycle

- [Index registration](https://github.com/supervc-stack/vectorchord/blob/main/src/index/mod.rs): `src/index/mod.rs`
- [RaBitQ access method](https://github.com/supervc-stack/vectorchord/blob/main/src/index/vchordrq/am/mod.rs): `src/index/vchordrq/am/mod.rs`
- [Graph access method](https://github.com/supervc-stack/vectorchord/blob/main/src/index/vchordg/am/mod.rs): `src/index/vchordg/am/mod.rs`
- [RaBitQ dispatch](https://github.com/supervc-stack/vectorchord/blob/main/src/index/vchordrq/dispatch.rs): `src/index/vchordrq/dispatch.rs`
- [Graph dispatch](https://github.com/supervc-stack/vectorchord/blob/main/src/index/vchordg/dispatch.rs): `src/index/vchordg/dispatch.rs`
- [RaBitQ build](https://github.com/supervc-stack/vectorchord/blob/main/src/index/vchordrq/build.rs): `src/index/vchordrq/build.rs`
- **Graph build**
- [PostgreSQL pages](https://github.com/supervc-stack/vectorchord/blob/main/src/index/storage.rs): `src/index/storage.rs`
- [Scan and filtering](https://github.com/supervc-stack/vectorchord/blob/main/src/index/vchordrq/scanners/mod.rs): `src/index/vchordrq/scanners/mod.rs`
- [Scan results](https://github.com/supervc-stack/vectorchord/blob/main/src/index/vchordrq/scanners/default.rs): `src/index/vchordrq/scanners/default.rs`

### Search engines

- [RaBitQ search](https://github.com/supervc-stack/vectorchord/blob/main/crates/vchordrq/src/search.rs): `crates/vchordrq/src/search.rs`
- [Graph search](https://github.com/supervc-stack/vectorchord/blob/main/crates/vchordg/src/search.rs): `crates/vchordg/src/search.rs`
- [Autonomous reranking](https://github.com/supervc-stack/vectorchord/blob/main/crates/vchordrq/src/rerank.rs): `crates/vchordrq/src/rerank.rs`

### Vector compute

- [Hierarchical K-means](https://github.com/supervc-stack/vectorchord/blob/main/crates/k_means/src/hierarchical.rs): `crates/k_means/src/hierarchical.rs`
- [RaBitQ encoding](https://github.com/supervc-stack/vectorchord/blob/main/crates/rabitq/src/lib.rs): `crates/rabitq/src/lib.rs`
- [Vector operations](https://github.com/supervc-stack/vectorchord/blob/main/crates/vector/src/lib.rs): `crates/vector/src/lib.rs`

### Other components

- **SQL client**

## Connections

- SQL client → Extension init: uses SQL
- Extension init → Index registration: initializes
- Extension init → Query recorder: initializes
- SQL client → Vector types: writes vectors
- SQL client → RaBitQ access method: creates and scans
- SQL client → Graph access method: creates and scans
- RaBitQ access method → RaBitQ dispatch: dispatches
- Graph access method → Graph dispatch: dispatches
- RaBitQ dispatch → RaBitQ build: builds index
- Graph dispatch → Graph build: builds index
- RaBitQ dispatch → RaBitQ search: searches
- Graph dispatch → Graph search: searches
- RaBitQ build → PostgreSQL pages: writes pages
- Graph build → PostgreSQL pages: writes pages
- RaBitQ search → PostgreSQL pages: reads pages
- Graph search → PostgreSQL pages: reads pages
- RaBitQ access method → Scan and filtering: sets up scans
- Scan and filtering → RaBitQ dispatch: dispatches search
- Scan and filtering → Scan results: emits rows
- RaBitQ search → Autonomous reranking: reranks candidates
- RaBitQ build → Hierarchical K-means: clusters vectors
- RaBitQ build → RaBitQ encoding: encodes vectors
- Graph build → Vector operations: processes vectors
- RaBitQ search → Vector operations: scores vectors
- Graph search → Vector operations: scores vectors
- Query recorder → Recorder storage: records samples