pgvector Documentation on Vchord

Getting Started

Mon, 01 Jan 0001 00:00:00 +0000

Installation

Pigsty / Native Linux Packages (Recommended)

Pigsty provides prebuilt native pgvector packages (v0.8.2) for PostgreSQL 14–18 across Debian, Ubuntu, and RHEL/Rocky/AlmaLinux (x86_64 and ARM64):

pig repo add pgdg pigsty -u
pig ext install pgvector

If you also want disk-friendly RaBitQ vector indexes and BM25 ranking, install the full Vchord suite together:

pig ext install pgvector vchord vchord_bm25 pg_tokenizer

Docker

Run the official pgvector container image:

Querying & Filtering

Mon, 01 Jan 0001 00:00:00 +0000

Distance Operators

pgvector supports six distance operators for ordering (ORDER BY) and threshold filtering:

Operator	Metric	Supported Types	Notes
`<->`	L2 (Euclidean) distance	`vector`, `halfvec`, `sparsevec`	$\sqrt{\sum (a_i - b_i)^2}$
`<#>`	Negative inner product	`vector`, `halfvec`, `sparsevec`	Returns $-\sum a_i b_i$ because PostgreSQL index scans only support `ASC` order
`<=>`	Cosine distance	`vector`, `halfvec`, `sparsevec`	$1 - \frac{a \cdot b}{\lVert a \rVert \lVert b \rVert}$ (range `[0, 2]`)
`<+>`	L1 (Taxicab / Manhattan) distance	`vector`, `halfvec`, `sparsevec`	$\sum \lvert a_i - b_i \rvert$ (added in `0.7.0`)
`<~>`	Hamming distance	`bit`	Number of differing bits (`XOR` popcount)
`<%>`	Jaccard distance	`bit`	$1 - \frac{\lvert A \cap B \rvert}{\lvert A \cup B \rvert}$

Normalized Vectors

If your vectors are already normalized to unit length (such as OpenAI text-embedding-3-* or BGE embeddings), prefer inner product (<#>) over cosine distance (<=>) for the best CPU throughput.

HNSW & IVFFlat Indexing

Mon, 01 Jan 0001 00:00:00 +0000

By default, pgvector performs exact nearest-neighbor search (sequential scan), which delivers 100% recall. When your dataset grows beyond tens of thousands of rows, add an approximate nearest-neighbor (ANN) index to trade a small amount of recall for orders-of-magnitude higher query speed.

pgvector includes two built-in index access methods:

HNSW (Hierarchical Navigable Small World): Multi-layer proximity graph. Higher recall-speed trade-off and no training step required, at the cost of slower build times and higher memory usage.
IVFFlat (Inverted File with Flat Vectors): K-means clustering over vectors. Faster index builds and smaller index footprint, but requires data to exist before index creation and delivers lower recall per probe than HNSW.

Scaling Beyond HNSW & IVFFlat

When datasets exceed available RAM (e.g., 10M–1B+ vectors) or HNSW index build times become a bottleneck, install vchord alongside pgvector. vchord’s vchordrq and vchordg index access methods work directly on pgvector’s vector and halfvec columns, compressing vectors with RaBitQ to build up to 100x faster and run efficiently from disk/SSD.

Quantization & Sparse Vectors

Mon, 01 Jan 0001 00:00:00 +0000

pgvector supports four vector representations so you can balance memory footprint, dimensionality limits, and recall:

Data Type	Element Type	Max Indexed Dimensions	Storage Size
`vector(n)`	32-bit float (`float32`)	2,000	$4n + 8$ bytes
`halfvec(n)`	16-bit float (`float16`)	4,000	$2n + 8$ bytes
`bit(n)`	1-bit binary (`0` / `1`)	64,000	$\lceil n / 8 \rceil + 8$ bytes
`sparsevec(n)`	Non-zero `index:float32` pairs	1,000 non-zero elements (up to 1,000,000 dims)	$8 \times \text{nnz} + 16$ bytes

RaBitQ Quantization in vchord

In addition to pgvector’s built-in quantization types, vchord provides rabitq8 (8-bit) and rabitq4 (4-bit) quantized vector types and supports indexing up to 60,000 dimensions in vchordrq. See vchord Quantization Types.

Reference, Tuning & FAQ

Mon, 01 Jan 0001 00:00:00 +0000

SQL Function Reference

Vector Functions

Function	Return Type	Description
`l2_distance(a, b)`	`float8`	Euclidean (L2) distance between `a` and `b` (`vector`, `halfvec`, `sparsevec`)
`inner_product(a, b)`	`float8`	Inner (dot) product $\sum a_i b_i$ (`vector`, `halfvec`, `sparsevec`)
`cosine_distance(a, b)`	`float8`	Cosine distance $1 - \frac{a \cdot b}{\lVert a \rVert \lVert b \rVert}$ (`vector`, `halfvec`, `sparsevec`)
`l1_distance(a, b)`	`float8`	Manhattan (L1) distance $\sum \lvert a_i - b_i \rvert$ (`vector`, `halfvec`, `sparsevec`)
`hamming_distance(a, b)`	`float8`	Hamming distance between two `bit` vectors
`jaccard_distance(a, b)`	`float8`	Jaccard distance between two `bit` vectors
`vector_dims(a)`	`integer`	Number of dimensions in `a` (`vector`, `halfvec`, `sparsevec`)
`vector_norm(a)`	`float8`	Euclidean norm $\lVert a \rVert_2$ (`vector`, `halfvec`, `sparsevec`)
`l2_normalize(a)`	same as input	Normalize vector `a` to unit L2 length (`vector`, `halfvec`, `sparsevec`)
`binary_quantize(a)`	`bit`	Quantize each element of `vector` or `halfvec` to `1` ( $> 0$ ) or `0` ( $\le 0$ )
`subvector(a, start, count)`	same as input	Extract `count` dimensions starting at 1-based index `start` (`vector`, `halfvec`)

Element-Wise Arithmetic Operators

a + b: Element-wise addition (vector, halfvec)
a - b: Element-wise subtraction (vector, halfvec)
a * b: Element-wise multiplication (vector, halfvec)
a || b: Vector concatenation (vector, halfvec)

GUC Parameters

Parameter	Type / Allowed Values	Default	Description
`hnsw.ef_search`	`integer` (`1`–`1000`)	`40`	Size of the dynamic candidate list during HNSW search
`hnsw.iterative_scan`	`off`, `relaxed_order`, `strict_order`	`off`	Automatically scan more HNSW tuples when `WHERE` filters reduce results below `LIMIT`
`hnsw.max_scan_tuples`	`integer`	`20000`	Maximum tuples visited during an HNSW iterative scan
`hnsw.scan_mem_multiplier`	`real`	`1`	Multiple of `work_mem` used for HNSW iterative scan state
`ivfflat.probes`	`integer` (`1`–`lists`)	`1`	Number of inverted lists probed during an IVFFlat query
`ivfflat.iterative_scan`	`off`, `relaxed_order`	`off`	Automatically probe additional IVFFlat lists when `WHERE` filters reduce results below `LIMIT`
`ivfflat.max_probes`	`integer`	`32768`	Maximum lists probed during an IVFFlat iterative scan

Performance Tuning & Monitoring

1. Check Index Size

SELECT pg_size_pretty(pg_relation_size('items_embedding_idx'));

2. Inspect Query Execution Plans

Use EXPLAIN ANALYZE to confirm whether an index scan is chosen and measure execution latency: