# 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.
- `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 full-text hybrid query | Qdrant | `stable` | `pgcontext.query` supports dense vector plus PostgreSQL full-text 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` |
| Model versions and embedding migrations | Qdrant | `stable` | Model-version metadata and migration progress records are stable catalog APIs. | `docs/user_guide/collections.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 | `experimental` | Binary, scalar/SQ8-style, and product encodings serve from revision-bound mapped HNSW artifacts with exact source rerank; PostgreSQL index-AM pages still store full-precision graph vectors. | `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 | `intentionally different` | pgContext does not support IVFFlat in the first production surface; use exact search or HNSW paths, or keep pgvector IVFFlat indexes alongside pgContext during migration. | `docs/user_guide/indexes.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` |
