pgContext User Guide

pgContext is an open-source PostgreSQL extension for AI vector and hybrid retrieval.

This guide distinguishes stable, implemented behavior from experimental and planned paths. pgContext 0.1.0 targets PostgreSQL 17.

Current Status

The repository currently exposes dense vectors, array-based exact search, collection catalog APIs, dense vector-column registration, stable point ID mappings, basic exact search over registered table-backed collections, stable scroll cursors, filter-first exact search, filtered facets, and dense plus full-text hybrid retrieval with reciprocal rank fusion. The Rust core also has half-vector parsing and distance metrics plus sparse-vector canonicalization; bit-vector Hamming and Jaccard distances are also implemented in core. Named dense vector registration and search-by-name selection are part of the stable table-backed search surface. Stable metadata functions expose per-vector HNSW/quantization/status containers, but the option semantics remain experimental. Named sparse vector registration and storage/index/status metadata are also SQL-visible experimentally. Exact sparse top-k over explicit arrays and named sparse source columns is available through pgcontext.search_sparse, and exact dense+sparse RRF fusion is available through pgcontext.query; sparse ANN/index serving remains planned. Experimental SQL wrappers expose halfvec, sparsevec, and bitvec input/output, typmods, dimension helpers, exact distance helpers, and distance operators. halfvec also has explicit rounding numeric-array casts and aggregates; sparsevec also has structured construction, dense real[]/vector casts, and aggregates. bitvec also has boolean[], PostgreSQL bit, and PostgreSQL bit varying casts plus pgvector-compatible built-in bit distance functions/operators and bitwise OR/AND aggregates. All three variant types also install default btree ordering opclasses. halfvec and sparsevec also expose experimental L2 pgcontext_hnsw opclasses backed by dense vector storage, and bitvec exposes an explicit experimental pgcontext.bitvec_hnsw_hamming_ops opclass for Hamming order. Non-L2 sparse ANN indexing and bit-vector Jaccard ANN indexing remain planned; default pgcontext_hnsw attempts on bitvec columns fail with SQLSTATE 42704.

Capability Areas

  • Collections over ordinary PostgreSQL tables.
  • Named dense vector registration/search and experimental per-vector planner metadata.
  • Qdrant-style filter JSON over ordinary columns and JSONB metadata.
  • Exact search as the correctness baseline.
  • Hybrid dense plus full-text retrieval and experimental exact dense+sparse fusion.
  • Experimental persisted dense HNSW indexes and adaptive filtered ANN, with exact source rechecks and bounded PostgreSQL 17 lifecycle evidence.

Explicitly Not Implemented

V1 does not implement complete non-dense ANN metric coverage, quantized HNSW serving, named sparse ANN serving, internally maintained late-interaction token indexes, complete composite-query-plan execution, memory-mapped HNSW graph traversal, or complete automatic query telemetry. IVFFlat is intentionally not part of pgContext’s V1 product. Existing helper APIs, metadata containers, or artifact readers do not imply that these serving paths exist.

Their dependency order and acceptance requirements are in the post-V1 product roadmap.

Implemented Core Behavior

PostgreSQL Support

PostgreSQL 17 is the supported V1 release target. PostgreSQL 15, 16, and 18 require their later version-specific gates; PostgreSQL 14 is legacy best-effort only.