pgvector

Implements four distinct vector data types (vector/float32, halfvec/float16, sparsevec/sparse, bit/binary) as first-class PostgreSQL types via custom type system integration in src/vector.c, src/halfvec.c, src/sparsevec.c, and src/bitvector.c. Each type includes input/output functions, binary serialization (vector_recv/vector_send), and automatic casting between formats, enabling memory-efficient storage of embeddings directly in table columns alongside relational data without external serialization.

Provides six distance metrics (L2 Euclidean, inner product, cosine, L1 Manhattan, Hamming, Jaccard) exposed as SQL operators (<->, <#>, <=>, <+>, <~>, <%>) with C implementations in src/vector.c using CPU-specific SIMD dispatch (AVX-512, AVX2, SSE2 fallback). Each operator is registered as a PostgreSQL operator class enabling index-aware query planning and automatic selection of the fastest implementation for the host CPU architecture.

Integrates with PostgreSQL's VACUUM process to maintain index consistency as vectors are inserted, updated, or deleted. VACUUM removes deleted vectors from indexes and reclaims space, while INSERT/UPDATE operations incrementally update HNSW graph structure or IVFFlat cluster assignments. Index maintenance is automatic and transparent — no manual index rebuild required for normal operations. VACUUM can be run manually or automatically via autovacuum daemon, with configurable aggressiveness via vacuum_cost_delay and related parameters.

pgvector works with any PostgreSQL client library (psycopg2 for Python, pg for Node.js, pq for Go, etc.) via the standard PostgreSQL wire protocol. Vector types are transmitted as binary data using PostgreSQL's vector_send/vector_recv functions, requiring no special client-side code beyond standard parameterized queries. Clients can pass vectors as text literals (e.g., '[0.1, 0.2, 0.3]') or binary data, with automatic conversion handled by pgvector's type system.

Supports automatic and explicit casting between vector types (vector ↔ halfvec ↔ sparsevec ↔ bit) via PostgreSQL's CAST system. Casting from float32 to float16 rounds to nearest representable value (7 significant digits), casting to sparse requires external sparsification, and casting to binary uses threshold-based quantization. Casts are implemented in src/vector.c and registered via CREATE CAST statements, enabling implicit conversion in some contexts and explicit conversion via CAST() operator.

Implements Hierarchical Navigable Small World (HNSW) index as a PostgreSQL access method (hnswhandler in src/index.c) supporting approximate nearest neighbor search with configurable M (max connections per node) and ef_construction (search width during build) parameters. Index is built incrementally during INSERT operations and supports parallel construction via PostgreSQL's parallel index build framework, storing the hierarchical graph structure in PostgreSQL's B-tree storage with layer information and neighbor lists.

Implements Inverted File Flat (IVFFlat) index as a PostgreSQL access method (ivfflathandler in src/index.c) using k-means clustering to partition vectors into lists, storing cluster centroids and flat lists of vectors per cluster. Query execution performs exact distance calculation only within the top-k nearest clusters (determined by ef_search parameter), reducing search space from full dataset to typically 1-5% of vectors. Index is built via k-means clustering during CREATE INDEX and supports list-level parallelization during queries.

Enables combining vector similarity queries with standard SQL WHERE clauses via PostgreSQL's query planner, which can push distance calculations into index scans and apply relational filters before or after index lookups. The planner estimates selectivity of both vector and relational predicates, choosing between index-first (if vector predicate is selective) or filter-first (if relational predicate is selective) execution strategies. Supports re-ranking patterns where approximate index results are re-scored with exact distance calculations.

Implements binary quantization (bit type) that converts float32 vectors to single-bit representations via threshold-based quantization, reducing memory footprint from 4 bytes per dimension to 0.125 bytes (8 dimensions per byte). Supports Hamming distance for binary vectors and Jaccard distance for sparse binary vectors. Binary quantization is lossless for similarity ranking (preserves relative ordering) but lossy for absolute distance values, making it suitable for approximate search where only ranking matters.

Integrates with PostgreSQL's parallel index build framework to parallelize HNSW and IVFFlat index construction across multiple worker processes. For HNSW, parallel workers build independent graph sections that are merged during finalization. For IVFFlat, parallel workers perform k-means clustering iterations and assign vectors to clusters concurrently. Parallelization is controlled via max_parallel_workers_per_gather and maintenance_work_mem settings, with automatic work distribution based on vector count and available memory.

Integrates vector data fully into PostgreSQL's transaction system, ensuring ACID compliance for all vector operations (INSERT, UPDATE, DELETE). Vector changes are logged to PostgreSQL's Write-Ahead Log (WAL), enabling replication to standby servers and point-in-time recovery (PITR) of vector data. Index changes are also logged, allowing replicas to maintain consistent indexes. This integration means vector data participates in transactions, savepoints, and rollbacks like any other PostgreSQL data.

Integrates with PostgreSQL's query planner to estimate cost of vector operations (distance calculations, index scans) and select optimal execution plans. The planner estimates the number of distance calculations required for HNSW (based on ef_search parameter) and IVFFlat (based on nlist and ef_search), comparing against sequential scan cost. For hybrid queries, the planner chooses between index-first and filter-first strategies based on selectivity of vector and relational predicates. Cost estimates are based on vector dimensionality, index parameters, and table statistics.

Implements sparsevec type for storing sparse vectors (vectors with mostly zero values) using a compressed format that stores only non-zero indices and values. Sparse vectors are stored as (index, value) pairs, reducing storage from O(d) to O(k) where k is the number of non-zero elements. Supports Jaccard distance for sparse vectors, which measures set overlap rather than Euclidean distance. Sparse vectors can be indexed with HNSW or IVFFlat, with distance calculations optimized to skip zero elements.