# 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 L2, inner-product, cosine, and L1 kNN through metric-bound persisted PostgreSQL pages, retains only published topology during concurrent inserts, exposes cancellation and `hnsw_last_scan_work` counters, has no silent exact fallback, resets on rescan, and does not support mark/restore. Table-driven mutation, VACUUM, REINDEX, exact-oracle, and crash/restart coverage runs for every dense metric; Hamming kNN remains unavailable. | `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, btree ordering opclass, and L2 `pgcontext_hnsw` opclass backed by dense vector storage are SQL-visible. | `docs/user_guide/pgvector_migration.md` |
| SQL sparsevec | pgvector,Qdrant | `experimental` | `sparsevec` text I/O, dimensions, typmods, structured array construction, dense `real[]`/`vector` casts, canonical accessors, exact L2, inner-product, cosine, and L1 helpers/operators, aggregates, btree ordering opclass, L2 `pgcontext_hnsw` opclass backed by dense vector storage, sparse collection metadata, exact array top-k, and named table search are SQL-visible; non-L2 sparse ANN branches remain planned. | `docs/user_guide/vector_search.md` |
| SQL bit vectors | pgvector | `experimental` | `bitvec` text I/O, dimensions, typmods, Hamming/Jaccard distance, distance operators, `boolean[]` casts, PostgreSQL `bit`/`bit varying` casts, pgvector-compatible built-in `bit` Hamming/Jaccard functions and operators, bitwise OR/AND aggregates, btree ordering opclass, and explicit Hamming `pgcontext_hnsw` indexing through `pgcontext.bitvec_hnsw_hamming_ops` are SQL-visible; Jaccard ANN indexing remains planned and default `pgcontext_hnsw` attempts fail with SQLSTATE `42704`. | `docs/user_guide/pgvector_migration.md` |
| SQL quantization APIs | pgvector,Qdrant | `experimental` | Binary, scalar/SQ8-style, product quantize/reconstruct helpers, and exact quantized-candidate rerank are SQL-visible; quantized HNSW index serving remains planned. | `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 vector registration, storage/index/status metadata, exact named sparse table search, and exact dense+sparse RRF query fusion are SQL-visible; sparse ANN/index serving remains planned. | `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 | Qdrant | `stable` | Validated SQL constructors produce JSON plans for nearest, recommend, discover, lookup, prefetch, weighting, thresholds, formulas, and final rerank. | `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` |