pgvector

Implements four distinct vector data types (vector/float32, halfvec/float16, sparsevec/sparse, bit/binary) as PostgreSQL native types via the extension system, with automatic input/output serialization through vector_in/vector_out functions and binary protocol support via vector_recv/vector_send. Each type is registered with PostgreSQL's type system during CREATE EXTENSION, enabling direct column definitions and type casting without application-layer serialization overhead.

Exposes six distance metrics (L2 Euclidean, inner product, cosine, L1 Manhattan, Hamming, Jaccard) as PostgreSQL operators (<->, <#>, <=>, <+>, <~>, <%>) that compile to SIMD-optimized C implementations in src/vector.c. Each operator is registered with PostgreSQL's operator system and can be used directly in WHERE clauses, ORDER BY, and index scans without application-layer distance calculation.

Integrates pgvector indexes with PostgreSQL's VACUUM process to reclaim space from deleted vectors and maintain index quality. VACUUM scans the index structure, removes entries for deleted rows, and optionally compacts the index to improve query performance. For HNSW, VACUUM can trigger re-linking of graph nodes to maintain connectivity; for IVFFlat, VACUUM can trigger re-clustering if cluster quality degrades. Index maintenance is transparent to applications and runs automatically during VACUUM operations.

Supports explicit type casting between vector types (vector ↔ halfvec, vector ↔ sparsevec, vector ↔ bit) via PostgreSQL's CAST system. Casting from float32 to float16 applies automatic quantization; casting from dense to sparse applies sparsification logic; casting from float to bit applies binary quantization. Type conversions are implemented as C functions registered with PostgreSQL's type system, enabling seamless conversion in SQL expressions and function arguments.

Integrates vector storage and indexing with PostgreSQL's transaction system (ACID guarantees), write-ahead logging (WAL), and replication infrastructure. Vector data participates in transactions like any other PostgreSQL data type; updates to vectors are atomic and durable. Indexes are automatically replicated across PostgreSQL replicas via WAL streaming, ensuring consistency between primary and replicas. Point-in-time recovery (PITR) works with vector data, enabling restoration to any historical state. The integration is transparent; no special application logic is required to achieve transactional consistency.

Implements Hierarchical Navigable Small World (HNSW) index structure as a PostgreSQL access method via hnswhandler, supporting configurable M (max connections per node) and ef_construction (search width during build) parameters. Index building uses parallel workers when maintenance_work_mem permits, and queries execute approximate nearest neighbor search by navigating the hierarchical graph structure, with optional re-ranking of results against the full dataset.

Implements Inverted File Flat (IVFFlat) index structure using k-means clustering to partition vectors into nlist clusters, storing cluster centroids and flat vectors within each partition. Queries perform approximate nearest neighbor search by computing distance to cluster centroids, searching the nprobe nearest clusters, and re-ranking results. Index building uses k-means clustering via PostgreSQL's parallel workers, and supports tuning nlist (number of clusters) and nprobe (clusters to search) parameters.

Integrates with PostgreSQL's query planner to estimate index scan costs based on vector distance operators and index type (HNSW vs IVFFlat). The planner compares index scan cost against sequential scan cost and chooses the optimal execution plan. Index access methods register cost estimation functions that account for approximate search overhead and re-ranking costs, enabling the planner to make informed decisions about when to use indexes vs full table scans.

Supports combining vector similarity with traditional SQL filters via WHERE clauses that execute before or after index scans. Queries can filter by metadata (e.g., WHERE category = 'news') and then search for nearest neighbors within the filtered set, or search for approximate neighbors and re-rank against exact distances. The planner optimizes filter placement based on selectivity estimates, and index scans support iterative refinement where initial approximate results are re-ranked against exact distances.

Supports bit vector type for storing binary quantized embeddings (1 bit per dimension) with Hamming and Jaccard distance metrics. Binary vectors reduce memory footprint by 32x compared to float32 vectors (1 bit vs 32 bits per dimension) and enable fast Hamming distance computation via CPU bitwise operations. Applications can quantize float embeddings to binary format during INSERT or use pre-quantized embeddings from embedding models.

Integrates pgvector indexes with PostgreSQL's Write-Ahead Logging (WAL) system to ensure crash recovery and replication consistency. Index modifications (INSERT/UPDATE/DELETE on vector columns) are logged to WAL before being applied to the index structure, enabling point-in-time recovery and streaming replication to standby servers. The extension registers index access methods with PostgreSQL's WAL infrastructure, ensuring durability guarantees equivalent to standard PostgreSQL indexes.

Implements distance functions (L2, cosine, inner product, etc.) in C with SIMD (Single Instruction Multiple Data) optimizations for x86-64, ARM, and other architectures. The extension detects CPU capabilities at runtime and dispatches to optimized code paths (SSE, AVX, AVX-512, NEON) that compute distances on multiple vector elements in parallel. Distance computation is inlined in index scans and query operators, avoiding function call overhead.

Leverages PostgreSQL's parallel query execution infrastructure to build HNSW and IVFFlat indexes using multiple worker processes. Index building is decomposed into parallel phases: for HNSW, vectors are partitioned and inserted in parallel; for IVFFlat, k-means clustering is parallelized across workers. The leader process coordinates workers via shared memory and synchronization primitives, collecting partial results and merging them into the final index structure.