# pgvector and Qdrant Parity Matrix

This file is generated from `docs/user_guide/parity_matrix.data`.
Run `scripts/generate-parity-matrix.sh` after changing the source data.

Status values:

- `stable`: covered by the first production SQL compatibility contract.
- `experimental`: SQL-visible or implemented, but outside the production promise.
- `internal`: implemented for pgContext composition, with no public SQL promise.
- `planned`: explicitly not part of the first stable surface yet.
- `intentionally different`: pgContext deliberately uses PostgreSQL-native semantics.

| Capability | Reference | Status | pgContext release contract | Owning reference |
|---|---|---|---|---|
| Dense vector SQL type, casts, operators, aggregates | pgvector | `stable` | Dense `vector`, including `vector(n)` typmod metadata and assignment enforcement, is the stable first-release vector surface. | `docs/user_guide/api_reference.md` |
| Exact vector search over arrays and registered tables | pgvector,Qdrant | `stable` | Exact search is the correctness baseline for SQL search, recall checks, ANN, and hybrid retrieval. | `docs/user_guide/vector_search.md` |
| Collections over PostgreSQL source tables | Qdrant | `stable` | Collections reference authoritative PostgreSQL source tables and pgContext catalog metadata. | `docs/user_guide/collections.md` |
| Point upsert and delete mappings | Qdrant | `stable` | Point APIs map source keys to stable pgContext point IDs without owning source rows. | `docs/user_guide/collections.md` |
| Filter JSON over ordinary columns and JSONB paths | Qdrant | `stable` | Registered fields render through typed SQL predicates and SPI parameters. | `docs/user_guide/filters.md` |
| Scroll, count, and facet | Qdrant | `stable` | Stable APIs operate over active table-backed point mappings with shared filter semantics. | `docs/user_guide/api_reference.md` |
| Dense plus lexical hybrid query | Qdrant | `stable` | `pgcontext.query` supports dense vector plus registered lexical retrieval with reciprocal rank fusion. | `docs/user_guide/hybrid_retrieval.md` |
| Telemetry and operational status functions | Qdrant | `stable` | Diagnostics expose typed statuses and local counters without vectors, payloads, filters, or literal query text. | `docs/user_guide/operations.md` |
| Profile-backed embedding migrations | Qdrant | `experimental` | Migration progress references immutable source and target embedding profiles; the mutable model-version registry has been removed. | `docs/user_guide/multi_model.md` |
| HNSW access method | pgvector,Qdrant | `experimental` | `pgcontext_hnsw` serves dense and halfvec/sparsevec L2, inner-product, cosine, and L1 kNN plus bitvec Hamming/Jaccard through metric-bound persisted PostgreSQL pages. Non-dense opclass names and bindings are stable; the access method's on-disk compatibility remains experimental. Traversal exposes `hnsw_last_scan_work`, has no silent exact fallback, and every non-dense pair passes exact-oracle and bounded-candidate gates. | `docs/user_guide/indexes.md` |
| Filtered ANN serving | Qdrant | `experimental` | Filtered table search binds a validated HNSW index and, in one statement snapshot, materializes registered column/JSONB candidates once. Selective masks cross over to exact scoring; broader masks drive one page-backed HNSW traversal using the stored metric. Masked-out nodes remain connectors and sparse masks can expand through ACORN-like second-hop neighbors. Final source joins preserve logical PointId, MVCC/deletion state, ACL/RLS, predicate, and exact-distance rechecks. Selective, broad, empty, stale-stat, deleted, typed JSONB, tenant-isolation, and cancellation cases are covered. | `docs/user_guide/vector_search.md` |
| SQL halfvec | pgvector | `experimental` | `halfvec` text I/O, dimensions, typmods, exact distance helpers, distance operators, explicit rounding numeric-array casts, aggregates, and btree ordering remain experimental; stable HNSW opclasses cover L2, inner product, cosine, and L1 over dense graph storage. | `docs/user_guide/pgvector_migration.md` |
| SQL sparsevec | pgvector,Qdrant | `experimental` | `sparsevec` text I/O, dimensions, typmods, structured construction, casts, exact metrics, aggregates, and collection metadata remain experimental; stable HNSW opclasses cover L2, inner product, cosine, and L1, and named sparse search can bind them for bounded candidates with exact rerank. | `docs/user_guide/vector_search.md` |
| SQL bit vectors | pgvector | `experimental` | `bitvec` type helpers, casts, exact Hamming/Jaccard operators, aggregates, and btree ordering remain experimental; stable explicit HNSW opclasses serve Hamming and Jaccard. Default `pgcontext_hnsw` attempts fail with SQLSTATE `42704` so callers must choose the bit metric. | `docs/user_guide/pgvector_migration.md` |
| SQL quantization APIs | pgvector,Qdrant | `stable` | Binary, scalar/SQ8-style, and product encodings serve from revision-bound segmented packed shared or mapped HNSW artifacts with exact source rerank; the frozen 1M release lane passed on PG17 and PG18. | `docs/user_guide/indexes.md` |
| Named dense vector registration and search | Qdrant | `stable` | Named dense vector registration, dimensions, metrics, and search-by-name selection are part of the first stable table-backed search surface. | `docs/user_guide/collections.md` |
| Per-vector dense index and quantization metadata | Qdrant | `experimental` | The experimental `collection_vectors` and `configure_vector` functions expose validated metadata containers; HNSW/quantization option semantics and full planner use remain planned. | `docs/user_guide/collections.md` |
| Named sparse vectors per collection | Qdrant | `experimental` | Sparse registration, exact fallback, validated metric-matched HNSW attachment, filtered candidate masks, bounded work diagnostics, authoritative exact rerank, and exact dense+sparse RRF query fusion are SQL-visible. | `docs/user_guide/collections.md` |
| Multi-vector and late-interaction query | Qdrant | `experimental` | Exact late-interaction MaxSim rerank over explicit arrays, exact table-backed `vector[]` search, typed ANN-planner diagnostics, and HNSW token candidate generation with O(1) declared token-dimension validation, source-table exact MaxSim rerank, deleted-point checks, token-table prerequisite failures, planner preflight, and hydrated budget checks are SQL-visible; full memory/latency release gates remain open. | `docs/user_guide/vector_search.md` |
| Recommendation search | Qdrant | `stable` | Positive/negative point-ID and raw-vector recommendation search uses exact rerank with ACL/RLS and deleted-point checks. | `docs/user_guide/vector_search.md` |
| Discovery or explore search | Qdrant | `stable` | Exact diversity-oriented discover/explore search ranks active rows farthest from visible context examples. | `docs/user_guide/vector_search.md` |
| Query constructors and composite execution | Qdrant | `stable` | Validated SQL constructors produce bounded executable plans for named/filtered dense, named sparse, full-text, quantized mapped HNSW, owned late-interaction, recommend, discover, lookup, prefetch, weighting, thresholds, formulas, and final score ordering; every retrieval candidate is authoritatively rechecked before fusion. | `docs/user_guide/vector_search.md` |
| Grouped search | Qdrant | `stable` | Grouped exact search caps results per registered payload field with deterministic ordering and PostgreSQL ACL/RLS checks. | `docs/user_guide/collections.md` |
| Payload mutation helpers | Qdrant | `stable` | Registered payload fields can be set, deleted, or cleared through documented source-table mutation policy. | `docs/user_guide/collections.md` |
| Bulk point backfill APIs | Qdrant | `stable` | Bulk point upsert, delete, and source-table backfill APIs report bounded per-batch progress diagnostics. | `docs/user_guide/collections.md` |
| IVFFlat | pgvector | `experimental` | Native `pgcontext_ivfflat` provides deterministic external construction, bounded probes and iterative widening, DML/VACUUM/REINDEX/CIC/partition/WAL/replica lifecycle, dense/half/integer/bit opclasses, and shared SQ8/PQ posting codecs with exact source rerank. The optional conflict-safe facade supplies the `ivfflat` spelling when free, and ownership conversion preserves certified `lists` while rebuilding native pages. | `docs/user_guide/indexes.md` |
| pgvector migration and compatibility | pgvector | `stable` | The main extension publishes a precise compatibility inventory, conflict-safe native-name facade, pgvector-owned-type binding, and resumable HNSW/IVFFlat ownership conversion with exact validation, rollback, and PG17/18 lifecycle gates. | `docs/user_guide/pgvector_coexist.md` |
| PostgreSQL-native ACL, RLS, transactions, and backups | Postgres improvement | `intentionally different` | pgContext relies on PostgreSQL source tables, privileges, RLS, transactions, backup, and WAL instead of replacing them. | `docs/user_guide/security.md` |
| Rebuildable acceleration artifacts | Postgres improvement | `intentionally different` | Indexes and segment files are cache artifacts; PostgreSQL tables remain authoritative. | `docs/user_guide/storage.md` |
| PostgreSQL-native lexical retrieval | Elasticsearch | `stable` | Registered `tsvector` sources serve typed lexical queries with bounded GIN/GiST candidate probes and authoritative source recheck. | `docs/user_guide/lexical_retrieval.md` |
| Trigram fuzzy retrieval | Elasticsearch | `experimental` | Registered optional `pg_trgm` sources serve typed fuzzy queries with bounded GIN/GiST candidate probes, scoped thresholds, and authoritative source recheck. | `docs/user_guide/lexical_retrieval.md` |
| Adaptive-dimension Matryoshka retrieval | Qdrant | `experimental` | Model-certified prefixes drive candidate generation while final ranking uses the full authoritative dimensions, so a prefix cannot change the answer. | `docs/user_guide/adaptive_dimension.md` |
| Version-safe multi-model retrieval | Qdrant | `stable` | Version-bound active or draining profiles execute independent authorized branches and combine only ranks through bounded weighted RRF with explicit degraded policy. The frozen equal-weight held-out contract passes at one million rows on PostgreSQL 17 and 18. | `docs/user_guide/multi_model.md` |
| Provider-neutral semantic reranking | Qdrant,Elasticsearch | `experimental` | A detached bounded envelope releases only PostgreSQL-authorized current text to an external worker; untrusted scores cannot add candidates and every returned row is rechecked under current source hash/version, deletion, filter, ACL, and RLS state. Local PG17/PG18 certification and an opt-in revision-pinned MiniLM PostgreSQL prepare-score-finalize smoke pass. A general transformer backend inside pgcontext-worker, retained held-out quality and authority-churn tests, and hosted Darwin/Linux arm64/x86_64 evidence are still required for Stable promotion. | `docs/user_guide/semantic_reranking.md` |
| Automatic document chunking | Qdrant,Elasticsearch | `experimental` | Versioned plain-text, Markdown, and HTML workers produce deterministic citable chunks through fenced jobs, canonical source revalidation, private staging, fake-embedding work records, and atomic generation aliases under PostgreSQL ACL, RLS, MVCC, backup, and transaction rules. An opt-in revision-pinned MiniLM smoke proves 384-dimension HNSW retrieval with citation preservation, but no production embedding-job integration is implemented. Both frozen PG17 and PG18 one-million-row source-cardinality lanes miss the 1,000-chunks-per-second publication floor, so Stable promotion is a measured no-go. | `docs/user_guide/automatic_chunking.md` |
| Exact-first readiness | Qdrant,Postgres improvement | `experimental` | Dense-vector registration is queryable through a complete exact source scan immediately. Explicit immutable plans may later build and publish a structurally verified HNSW or IVFFlat index through fenced top-level concurrent DDL without changing source authority, ACL, RLS, or exact final order. Both frozen PG17 and PG18 ten-million-row lanes preserve exactness and 100% top-10 recall but miss building/indexed latency and temp ceilings, so Stable promotion is a measured no-go. | `docs/user_guide/exact_first_readiness.md` |
| Lazy HNSW cursor | Qdrant | `internal` | The bounded graph-read HNSW traversal is available as a deterministic statement-local cursor for internal composition. Existing eager APIs drain the same implementation; no SQL or planner default is exposed. | `docs/user_guide/lazy_hnsw_cursor.md` |
| Virtual beam engine | Qdrant | `internal` | The vector-only provider-neutral kernel owns a bounded parent arena, deterministic dominance and cycle pruning, separated score components, and content-free diagnostics. Topology expansion, SQL exposure, and planner selection remain later phases. | `docs/user_guide/virtual_beam.md` |