Known Limitations

This page describes the important limitations of pgContext 0.3.0. The Supported Features inventory is the canonical maturity reference; planned-only work remains in the roadmap.

Compatibility and installation

  • 0.3.0 is a clean-install baseline. There is no 0.1-to-0.3 or 0.2-to-0.3 extension update script.
  • The separate pgcontext_pgvector companion extension is retired. pgvector compatibility is enabled through the main extension.
  • Experimental HNSW, IVFFlat, codec, segment, and generated-artifact formats may require REINDEX or regeneration from authoritative rows.
  • PostgreSQL 17 and 18 are supported. Other PostgreSQL majors are not supported release targets.

See the release migration procedure before replacing an existing installation.

Vector types and indexes

  • Dense vector SQL and exact search are Stable. The halfvec, sparsevec, bitvec, int8vec, and uint8vec source surfaces remain Experimental even where individual opclass names and metric bindings are stable contracts.
  • The general page-native pgcontext_hnsw format remains Experimental. Quantized HNSW serving has a Stable source-reranked contract, but that does not promote every HNSW storage or maintenance path.
  • Densified HNSW records must fit the documented PostgreSQL page envelope. Effective indexable dimensions depend on representation, graph degree, and layer shape; oversized records fail before publication.
  • Segmented HNSW writes bound delta and compaction work, but a write that triggers rotation or pair compaction still pays that maintenance latency.
  • Native pgcontext_ivfflat is Experimental. Its v4 pages intentionally reject earlier development formats, and the retained one-million/ten-million comparative certification remains open.

Retrieval maturity

  • Named sparse ANN and internally maintained late interaction remain Experimental. Both recheck authoritative source values exactly after candidate generation.
  • Adaptive-dimension retrieval preserves exact full-dimension results but its current scan-based schedule has no demonstrated latency benefit.
  • Exact-first readiness preserves exact availability and passes its correctness gates, but misses the current indexed/building query-latency and temporary storage promotion ceilings.
  • Trigram fuzzy retrieval is optional and Experimental. pg_trgm is not an installation requirement.
  • The lazy HNSW cursor and virtual beam engine are Internal. The beam has no SQL or planner surface in 0.3.0, remains vector-only, and rejects topology expansion.

Semantic models and chunking

  • pgContext does not bundle model weights. Deterministic fixtures remain the default CI and worker contract.
  • Semantic reranking is Experimental. The detached envelope and PostgreSQL finalization boundary are implemented and a revision-pinned MiniLM cross-encoder passes the optional local smoke, but a general transformer backend is not integrated into pgcontext-worker.
  • Automatic chunking is Experimental. Its publication schema still uses deterministic fixture embeddings. The optional real-model smoke proves indexed 384-dimension retrieval with citation preservation, not a production embedding-job integration.
  • Stable semantic promotion still requires retained held-out quality, cancellation/timeout and authority-churn coverage, and hosted platform evidence across supported architectures.
  • The frozen one-million-row chunk-publication lanes miss the declared 1,000 chunks/second promotion floor.

Operations and resources

  • PostgreSQL rows remain authoritative. Generated indexes, codec files, mapped segments, model downloads, and worker reports are rebuildable or disposable artifacts, not backups.
  • Memory and work limits are conservative and fail closed. A request can return a typed incomplete or budget-exhausted outcome even when PostgreSQL itself still has resources available.
  • Automatic query telemetry is bounded and content-free but best-effort. Contention, worker restart, queue saturation, or database-slot exhaustion can lose an observation; the commit/acknowledgement window can duplicate one.
  • Generated artifact cleanup handles registered, root-confined files only. It does not follow symlinks, recursively delete directories, or repair arbitrary catalog paths.
  • PostgreSQL 17 remains the primary benchmark and deep-lifecycle target even though PostgreSQL 18 is supported and passes the complete integration suite.

Security boundary

  • SQL-visible paths apply PostgreSQL ACL/RLS and current-row rechecks as documented. Applications still own source-table grants, RLS policy quality, model licensing, model-input policy, and output sanitization.
  • ts_headline output and other caller-rendered snippets must be sanitized for their final HTML or UI context.
  • Optional model downloads require explicit operator action and live outside the source and release package. Their recorded revision and artifact digest must match before inference.