Skip to content

Record SearchTrace on the SQL backends, and the BM25 gate's choice - #78

Merged
manuc66 merged 1 commit into
mainfrom
feat/sql-search-trace
Nov 16, 2026
Merged

manuc66 merged 1 commit into
mainfrom
feat/sql-search-trace

Conversation

@manuc66

@manuc66 manuc66 commented Nov 16, 2026

Copy link
Copy Markdown
Owner

What this adds

SearchOptions.Trace was inert on every PostgreSQL backend: the in-memory scorers write a Score step per hit, and the SQL engines wrote nothing, so a hybrid pipeline explained one channel and silently dropped the other.

  • Every SQL engine records the Score stage 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.
  • The stock-PostgreSQL BM25 engine records one query-level Gate step (TraceStage.Gate), 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 — 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.RecordScoreStage becomes 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

  • One test per SQL engine asserting the Score steps match the page and carry the engine's name (ParadeDB self-skips without pg_search and runs in the CI image).
  • Two BM25 tests: the rare-term gate step (terms, budget, candidate count, empty id, NaN scores) and the disabled-gate fallback (all terms (gate disabled)).

Full suite with the integration runsettings: 2,938 passed, 32 skipped, 0 failed. api-docs check and the public API baseline are regenerated.

Docs

docs/observability.md gains a section on the gate and the SQL backends; docs/backends.md points the BM25 gate at it; the changelog carries the entry.

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-commenter

codecov-commenter commented Nov 16, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 78.57143% with 9 lines in your changes missing coverage. Please review.
✅ Project coverage is 89.25%. Comparing base (495cb1c) to head (9687db4).

Files with missing lines Patch % Lines
src/LexiSharp.Postgres/PostgresBm25SearchEngine.cs 79.31% 4 Missing and 2 partials ⚠️
...harp.Postgres/ParadeDB/ParadeDBTextSearchEngine.cs 0.00% 3 Missing ⚠️
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.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@manuc66
manuc66 merged commit 65c9e34 into main Nov 16, 2026
17 checks passed
@manuc66
manuc66 deleted the feat/sql-search-trace branch November 16, 2026 23:17
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants