8000 fix(engine): hybrid/fusion reports a capped total as relation:gte, not a false eq (#569) by xerj-org · Pull Request #593 · xerj-org/xerj · GitHub
[go: up one dir, main page]

Skip to content

fix(engine): hybrid/fusion reports a capped total as relation:gte, not a false eq (#569) - #593

Merged
xerj-org merged 1 commit into
mainfrom
fix/569-hybrid-total-relation
Aug 22, 2026
Merged

xerj-org merged 1 commit into
mainfrom
fix/569-hybrid-total-relation

Conversation

@xerj-org
Copy link
Copy Markdown
Owner

Closes #569.

The bug (wrong results on a headline BM25+kNN feature)

run_hybrid_with_deadline fetches each sub-list at per_query_topk = max(50, size+from), RRF/linear-fuses them, and reported hits.total = { value: fused.len(), relation: Eq } unless the request timed out. When a sub-list is truncated at the fetch cap the fused union under-counts the true match set, so a hybrid query over thousands of lexical matches with size:10 claimed {"total":{"value":<=100,"relation":"eq"}} — a false exact count that track_total_hits cannot correct, while a plain lexical query reports the real count. Affects every hybrid query and (since #458) the ES 8.x knn-beside-query shape that routes to hybrid.

The fix (ES-style, minimal — issue's option (a))

Track fused_count_capped across the sub-query loop — a sub-list is truncated if it filled the per_query_topk page, or its own total exceeds the page, or its own count is already a lower bound (relation == Gte). Report Gte when any_timed_out || fused_count_capped, and Eq only when every sub-list was fully retrieved. The reported value (fused.len()) is a valid lower bound in the capped case — honest, not the exact tally (option (b), a union-aware exact count, is deliberately not attempted here).

if sub_result.hits.len() >= per_query_topk
    || sub_result.total.value > per_query_topk as u64
    || sub_result.total.relation == TotalHitsRelation::Gte
{ fused_count_capped = true; }
...
relation: if any_timed_out || fused_count_capped { Gte } else { Eq },

Verification

  • Tests: hybrid_reports_gte_when_a_sub_list_is_capped (256 vectors, a knn sub-list capped at 50, no timeout → Gte) and hybrid_reports_eq_when_no_sub_list_is_capped (6 docs, fully fetched → Eq, value 6).
  • Fail-before (reverting only || fused_count_capped): the capped hybrid reports a false Eq.
  • cargo test -p xerj-engine: 0 failed (full suite, exit 0). cargo fmt --check: clean. cargo clippy -p xerj-engine --all-targets -- -D warnings (1.98.0): exit 0.

The sibling min_score-vs-RRF-micro-scores note in #569 is separate and left tracked there. An independent 3-skeptic verification follows in a comment.

…t a false eq (#569)

`run_hybrid_with_deadline` fetches each sub-list at `per_query_topk = max(50,
size+from)`, RRF/linear-fuses them, and reported `hits.total = { value:
fused.len(), relation: Eq }` unless the request timed out. When any sub-list was
truncated at the fetch cap the fused union under-counts the true match set, so a
hybrid query over thousands of lexical matches with `size:10` claimed
`{"total":{"value":<=100,"relation":"eq"}}` — a false EXACT count that
`track_total_hits` cannot correct, while a plain lexical query reports the real
count. Affects every hybrid query and, once #458 landed, the ES 8.x
`knn`-beside-`query` shape that routes to hybrid.

Track `fused_count_capped` across the sub-query loop: a sub-list is truncated if
it filled the `per_query_topk` page, or its own total exceeds the page, or its
own count is already a lower bound (`relation == Gte`). Report `Gte` when
`any_timed_out || fused_count_capped`, and `Eq` only when every sub-list was
fully retrieved — the honest, ES-style wire shape. The reported `value`
(`fused.len()`) is a valid lower bound in the capped case.

Tests: `hybrid_reports_gte_when_a_sub_list_is_capped` (256 vectors, a knn
sub-list capped at 50, no timeout → Gte) and `hybrid_reports_eq_when_no_sub_list
_is_capped` (6 docs, fully fetched → Eq, value 6). Fail-before (reverting only
`|| fused_count_capped`): the capped hybrid reports a false Eq. Full xerj-engine
suite pending; fmt clean; clippy -D warnings 0 under 1.98.0.
@xerj-org
Copy link
Copy Markdown
Owner Author

Independent 3-skeptic verification — all 3 NON_BLOCKING

Verdicts verbatim. Gate (b) satisfied. The single finding across all three lenses is the safe-direction exact-boundary over-report, filed as follow-up #594.

🟢 CORRECTNESS — NON_BLOCKING

Honest lower bound confirmed: fuse_rrf dedups by h.id into a HashMap, so fused.len() ≤ |true hybrid union| — fusion can never EXCEED the true count, so value + Gte is honest (the dedup-vs-union overcount theory is refuted). Normal truncation forces hits.len() == per_query_topk → condition 1 fires (and the materialisation cap (from+size+100).max(256) never under-delivers below the page). track_total_hits forwarding is safe: a capped sub-total returns Gte/over-limit, caught by conditions 2/3, so it never masquerades as Eq. Only residual: false Gte at the exact boundary (safe/conservative, not a correctness defect). A kNN leg with user k < per_query_topk reporting Eq at k matches ES top-k semantics — not the #569 bug.

🟢 REGRESSION — NON_BLOCKING

cargo +1.98.0 test -p xerj-engine → CARGO_EXIT=0, 1035 passed / 0 failed across all 49 test binaries. Blast radius hybrid-only: git diff --name-only = single file (+119/-1), confined to run_hybrid_with_deadline. No pre-existing test flips Eq→Gte (the one hybrid-relation test asserts Gte via timeout with knn k=10 < per_query_topk=50, unaffected; es_compat's hybrid test asserts only HTTP 400). Both new tests pass. Only imperfection: the boundary over-report — standard ES/Lucene filled-collector convention, strictly safer than the pre-fix false Eq. Not a regression.

🟢 EVIDENCE — NON_BLOCKING

Fail-before reconstructed: reverting only || fused_count_capped → hybrid_reports_gte_when_a_sub_list_is_capped FAILS with left: Eq, right: Gte, reporting TotalHits { value: 50, relation: Eq } — a false-exact of 50 when 256 match. Load-bearing. Tests genuine (256 real docs; capped test asserts !timed_out so Gte comes from capping; exact test asserts Eq + value 6). Semantics honest — Gte-on-cap mirrors ES 8.x capping; value stays a valid lower bound, never a claimed exact; commit message makes no overclaim.

Tally: 3 NON_BLOCKING, 0 BLOCKING. Merge gate (b) ✅. Holding on (a) all-green + (c) CLEAN. Boundary nit → #594.

@xerj-org
xerj-org merged commit 88f9237 into main Aug 22, 2026
18 checks passed
buger pushed a commit to probelabs/xerj that referenced this pull request Aug 22, 2026
Tracks the v1.0.0-rc.32 tag (88f9237), landing xerj-org#536 (deterministic HNSW rebuild
await, xerj-org#592) and xerj-org#569 (hybrid/fusion total relation:gte when capped, xerj-org#593).
Clears the tag-ahead-of-stamps landing-constants-guard transient. Guard validated.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

hybrid/fusion queries report a fusion-depth-capped hits.total as relation:eq (false exact count)

1 participant

0