Repository navigation
Record SearchTrace on the SQL backends, and the BM25 gate's choice - #78
Merged
Merged
Conversation
SearchOptions.Trace was inert on every PostgreSQL engine: the in-memory scorers wrote a Score step per hit and the SQL ones wrote nothing, so a hybrid pipeline explained one channel and silently dropped the other. Each SQL engine now records the page it returns under a name that says where the score came from -- Postgres lexical, Postgres BM25, pgvector, sparsevec, pg_trgm, ParadeDB BM25 -- which is the same bounded-by-the-page shape the core engines use. The stock-PostgreSQL BM25 engine records one query-level Gate step as well, with an empty document id and NaN scores: gate Nan -> NaN rare-term gate [brown, quick] under a 1,000-row budget; 120 candidates That is the one decision on this backend a reader cannot reconstruct from the page. The score is Bm25Scorer's, but which documents were eligible is the gate's, and a result missing because no gate term matched is otherwise indistinguishable from one that scored badly. The step also spells the fallbacks: "phrase gate", "all terms (gate disabled)" and "all terms (no term within a N-row budget)". SearchTrace.RecordScoreStage becomes public for the same reason: a custom engine outside the core assembly has to report the stage under the same name, and a friend assembly would have kept the seam private to this repository's own packages. Tests cover the Score stage on all six engines (ParadeDB self-skips without pg_search) and the Gate step for the rare-term and disabled cases.
Codecov Report❌ Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## main #78 +/- ##
==========================================
+ Coverage 89.21% 89.25% +0.04%
==========================================
Files 270 270
Lines 21350 21383 +33
Branches 4610 4621 +11
==========================================
+ Hits 19047 19086 +39
+ Misses 1382 1375 -7
- Partials 921 922 +1 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this adds
SearchOptions.Tracewas inert on every PostgreSQL backend: the in-memory scorers write aScorestep per hit, and the SQL engines wrote nothing, so a hybrid pipeline explained one channel and silently dropped the other.Scorestage for the page it returns, under a name that says where it came from:Postgres lexical,Postgres BM25,pgvector,sparsevec,pg_trgm,ParadeDB BM25. The stage is bounded by the page, the same shape the core engines use.Gatestep (TraceStage.Gate), with an empty document id andNaNscores:That is the one decision on this backend a reader cannot reconstruct from the page. The score is
Bm25Scorer's, but which documents were eligible is the gate's — a result missing because no gate term matched is otherwise indistinguishable from one that scored badly. The step also spells the fallbacks:phrase gate,all terms (gate disabled),all terms (no term within a 1,000-row budget).SearchTrace.RecordScoreStagebecomes public, so a custom engine outside the core assembly can report the same stage under the same name. A friend assembly would have kept the seam private to this repository's own packages.Tests
Scoresteps match the page and carry the engine's name (ParadeDB self-skips withoutpg_searchand runs in the CI image).NaNscores) and the disabled-gate fallback (all terms (gate disabled)).Full suite with the integration runsettings: 2,938 passed, 32 skipped, 0 failed.
api-docs checkand the public API baseline are regenerated.Docs
docs/observability.mdgains a section on the gate and the SQL backends;docs/backends.mdpoints the BM25 gate at it; the changelog carries the entry.