Skip to content

armgit / xerj

Public Imported from GitHub
0

AI search engine and MCP server for bots and agents. One Rust binary indexes code, docs, logs, JSONL/CSV and PDFs for BM25 full-text, vector and hybrid search, code search without grep, agent memory and RAG. Elasticsearch-compatible API; Corpus Hub serves hundreds of reference memory corpora.

fix(search): knn beside query takes the indexed route again (#892) (#895)

xerj-org1642be9ff0e2
diff --git a/CHANGELOG.md b/CHANGELOG.md
index a69e22312..278c5e7f1 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -60,6 +60,80 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
### Fixed
+- **`knn` beside a `query` is answered from the inverted index again — and its
+ page no longer drops the documents matched by both halves**
+ ([#892](https://github.com/xerj-org/xerj/issues/892)). This closes the
+ regression rc.72 shipped knowingly: the
+ [#825](https://github.com/xerj-org/xerj/issues/825) fix pre-executes the
+ vector leg and pins its top-`k` into the query tree as `constant_score{ids}`
+ clauses, `_id` is not in the FTS term dictionary, so the projection declined
+ the whole tree and every segment fell to a stored-document scan.
+
+ That route was not only slow. The scan admits documents in stored-layout
+ order and stops materialising once it reaches the page cap — no score
+ comparison — so on any index with more lexical matches than that cap, the
+ documents reached by BOTH halves, the ones ES scores `query_score +
+ knn_score` and ranks first, never entered the page. `hits.total` was right;
+ the page was not. Live-verified on 100 000 documents: for a `match` + `knn`
+ k=10 request whose vector top-10 held exactly two lexical matches, rc.72's
+ top 20 was twenty lexical-only documents tied at 1.693 and neither
+ both-halves document appeared at all. They now rank 1 and 2, at 3.153 and
+ 3.144.
+
+ The projection now lifts the pinned disjunct to an FTS leaf carrying
+ `(doc_id, score)` pairs, resolved per segment through the same `_id` →
+ stored-position index that `ids` queries and `_mget` already use. The
+ lexical half keeps the inverted index and exact BM25, the vector half keeps
+ its own scores, and the `bool` sums them exactly as before.
+
+ Measured on that corpus (`text` + 8-dim `dense_vector`, ~10 % lexical
+ selectivity, bulk-loaded once and never updated — which is the only state in
+ which this route engages, see the scope note below — closed-loop, fresh query
+ vector per request so the query cache cannot answer twice, medians of 2
+ rounds × 7 requests, on a shared build machine — the two control rows bound
+ the noise):
+
+ | request | rc.72 | with this fix |
+ |---|---|---|
+ | `query` alone (control) | 0.45 ms | 0.52 ms |
+ | `knn` alone, k=10 (control) | 1.99 ms | 2.12 ms |
+ | `query` + `knn` k=10 | 265.9 ms | **6.4 ms** |
+ | `query` + `knn` k=100 | 326.9 ms | **8.4 ms** |
+ | `query` + `knn` k=1000 | 505.0 ms | **27.5 ms** |
+ | `query` + `knn` + `aggs` k=10 | 784.1 ms | **534.4 ms** |
+
+ `hits.total`, the aggregation buckets and the field-sorted page came back
+ identical across the two arms — one request shape per column, compared as
+ JSON — and so did `query`-alone and `knn`-alone. The agg row keeps most of
+ its cost because a `terms` agg over this shape still materialises the whole
+ corpus — a different path, untouched here.
+
+ Two things to know:
+
+ - **`_score` values change for this shape.** The lexical half is now scored
+ by exact BM25 — the same number the identical query returns *without* a
+ `knn` beside it — instead of the stored scan's heuristic. Ordering follows
+ the #825 contract as before; absolute values move, so a `min_score` tuned
+ against rc.72's hybrid needs revisiting.
+ - **The indexed route applies only to an index that has never taken an
+ overwrite or a delete** — that is the scope of every number above, and it
+ is a one-way door, not a transient window. The gate is the one the `ids`
+ pre-filter already applies: the per-segment `_id` index keeps one position
+ per id, so a segment physically holding a document twice (an overwrite
+ flushed alongside its predecessor) could hand back the superseded copy. It
+ reads `VersionMap::ghost_events`, which is **monotonic by design** — it
+ counts overwrite and delete events for the life of the open index and is
+ never decremented, not even by the merge that purges the superseded copies.
+ One `PUT` over an existing `_id`, or one `DELETE`, therefore turns this
+ route off for that index until it is re-opened, and it stays off across
+ that re-open while superseded copies remain on disk. An index that takes
+ updates or deletes keeps rc.72's stored scan for `knn` beside `query` —
+ still correct, and no slower than it was, but with none of the speedups
+ above. Append-only indexes — bulk load, reindex-and-swap, log and event
+ corpora — get them. Widening the route to ghost-bearing indexes is
+ separate work: it has to prove the #825 union/sum contract with tombstones
+ present, and is not attempted here.
+
- **A code symbol's retrievable unit is the whole declaration, not the single
physical line the name sits on**
([#500](https://github.com/xerj-org/xerj/issues/500)). Promoting each
diff --git a/engine/crates/xerj-engine/src/index.rs b/engine/crates/xerj-engine/src/index.rs
index 3efebec56..dfc801d3e 100644
--- a/engine/crates/xerj-engine/src/index.rs
+++ b/engine/crates/xerj-engine/src/index.rs
@@ -17346,6 +17346,86 @@ impl Index {
// is a transient undercount during an in-flight flush — the
// pre-existing, self-healing behaviour.
let snap = self.store.snapshot();
+ // F1 correctness gate (hoisted to the snapshot so the scan-early-stop
+ // decision, the post-loop `total_count` overwrite and the #892 pinned-kNN
+ // projection gate below can all see it): the doc-values/FST
+ // `shortcut_count` is DELETE-BLIND (counts physical postings, not live
+ // docs), whereas the stored-doc scan it lets us skip filters tombstones.
+ // The shortcut may only stand in for the EXACT `hits.total` when the
+ // index has no deleted/superseded docs. Conservative O(segments) signal:
+ // any flushed tombstone, OR live_count < physical (updates + deletes
+ // inflate the per-segment/memtable physical tally above the version-map
+ // live count). MatchAll is unaffected — overwritten with the
+ // delete-aware live_doc_count() regardless of this flag.
+ // EXACT ghost signal (see `VersionMap::ghost_events`): flushed
+ // tombstones OR any overwrite/delete event ever recorded. The old
+ // `live_count() < seg_physical + mem_physical` arithmetic also
+ // tripped on unrelated physical-count drift — live-verified: two
+ // duplicate docs per merged segment turned the gate permanently ON
+ // for a pure append-only corpus, disabling the F1 bounded scan and
+ // forcing every size>0 term/range/bool into a full O(N) stored
+ // scan. That was the dominant per-query cost in the
+ // read-under-write collapse.
+ //
+ // #892 hoist, stated because the binding moved and so did its READ
+ // TIME: `ghost_events()` is a live counter, and this read now happens
+ // ~850 lines and two `.await` points earlier than it used to. The two
+ // pre-existing F1 consumers (the scan early-stop and the post-loop
+ // `total_count` overwrite) therefore see a marginally staler value —
+ // a delete landing mid-search is slightly less likely to be observed
+ // by them. That race pre-dates this change (the counter was always
+ // read once and reused across awaits); the hoist widens the window,
+ // it does not create it. The consequence is the pre-existing one: a
+ // delete that lands after this read can leave that single request's
+ // `hits.total` served by the delete-blind shortcut. The #892 gate
+ // itself is unaffected — it is paired with `snap`, taken on the line
+ // above, so the route it admits reads a consistent segment set.
+ let deletes_present: bool = snap.segments.iter().any(|m| m.has_tombstones)
+ || self.store.version_map.ghost_events() > 0;
+
+ // ── #892: the #825 pinned kNN disjunct takes the INDEXED route ────
+ //
+ // `pin_knn_clause` names its top-k documents by `_id`, and `_id` is not
+ // in the FTS term dictionary — so the projection `?`-aborted on the
+ // pinned `should` clause, `fts_query` came back `None`, and EVERY
+ // `knn`-beside-`query` request fell to a full stored-document scan of
+ // every segment. Resolving those ids to each segment's stored positions
+ // (`id_pos_map_for`, the index `ids` queries and `_mget` already use)
+ // turns the disjunct into an ordinary FTS leaf, so the lexical half
+ // keeps the inverted index and the `bool` serves the same union with
+ // the same summed scores.
+ //
+ // `Probe` is the shape-only answer for the callers that have no segment
+ // in hand — `query_needs_fts` and the index-wide BM25 statistics
+ // pre-pass, both of which only need "does this project at all?". The
+ // real per-segment map is resolved inside the segment loop.
+ //
+ // GATED ON `!deletes_present`, exactly like `build_ids_prefilter_cached`
+ // gates the `ids` prefilter: `id_pos_map_for` keeps ONE position per
+ // `_id`, so a segment physically holding two copies of a document (an
+ // overwrite flushed alongside its predecessor) can hand back the
+ // superseded one — and an FTS leaf, unlike the stored scan, never
+ // re-reads `_id` per position to notice. With ghosts present the
+ // request keeps the #879 scan: correct, and no slower than it was.
+ //
+ // SCOPE, stated plainly because it is easy to read this gate as a
+ // transient one: `ghost_events` is MONOTONIC (version_map.rs — never
+ // decremented, not even by the merge that purges the superseded
+ // copies), so this is a one-way door per open index, not an in-flight
+ // window. A single overwrite or delete anywhere in the index's history
+ // disables this route for the life of the open index; at re-open it
+ // re-arms only while `live < physical` still holds on disk. Only
+ // append-only indexes take the indexed route today. Widening it to
+ // ghost-bearing indexes means proving the #825 union/sum contract with
+ // tombstones present — the per-segment `map.len() == expect_docs`
+ // guard in `id_pos_map_for` already rejects a duplicate-bearing
+ // segment, but a tombstoned-yet-present row still resolves to a
+ // position, so that proof is a separate piece of work.
+ let pinned_probe: Option<PinnedIds<'_>> = if pinned_query.is_some() && !deletes_present {
+ Some(PinnedIds::Probe)
+ } else {
+ None
+ };
// Exact memtable match total captured by the fused DV walk below and
// threaded into `try_shortcut_count`, whose bool-conjunction arm
// then skips its DUPLICATE memtable walk (mixed-RUW Fix 1: the
@@ -17427,6 +17507,7 @@ impl Index {
&exact_fields,
&kw_fields,
mem_doc_count,
+ pinned_probe,
)
.map(Arc::new)
})
@@ -18119,9 +18200,25 @@ impl Index {
// and materialises only the top prefix, so the F1 bounded-scan / count
// overwrite must NOT touch FTS queries — it only applies to the
// non-FTS stored-doc scan (match_all / term-on-keyword / range).
- let query_needs_fts: bool =
- query_node_to_fts_with_keyword_fields(query, &text_fields, &exact_fields, &kw_fields)
- .is_some();
+ //
+ // #892 note: this flips false → true for a pinned `knn`-beside-`query`
+ // (it is the whole point of the change), so the three branches gated on
+ // `!query_needs_fts` are RE-EVALUATED for that shape, not bypassed —
+ // the `size:0` columnar agg fast path below, `count_authoritative`, and
+ // the F1 `total_count` overwrite after the segment loop. All three are
+ // inert here: the fast path additionally needs `is_match_all ||
+ // agg_filter.is_some()` and `query_node_to_agg_filter` declines a
+ // `should` bool, and the other two only ever REMOVE a bounded-count
+ // shortcut, leaving the FTS path's own authoritative `seg_hits.len()`
+ // tally. Outcome unchanged; the gates themselves are not.
+ let query_needs_fts: bool = query_node_to_fts_projected(
+ query,
+ &text_fields,
+ &exact_fields,
+ &kw_fields,
+ pinned_probe,
+ )
+ .is_some();
// ── Precomputed segment agg fast path (M2 G2) ─────────────────────
//
@@ -18192,28 +18289,6 @@ impl Index {
}
}
- // F1 correctness gate (hoisted so both the scan-early-stop decision and
- // the post-loop `total_count` overwrite can see it): the doc-values/FST
- // `shortcut_count` is DELETE-BLIND (counts physical postings, not live
- // docs), whereas the stored-doc scan it lets us skip filters tombstones.
- // The shortcut may only stand in for the EXACT `hits.total` when the
- // index has no deleted/superseded docs. Conservative O(segments) signal:
- // any flushed tombstone, OR live_count < physical (updates + deletes
- // inflate the per-segment/memtable physical tally above the version-map
- // live count). MatchAll is unaffected — overwritten with the
- // delete-aware live_doc_count() regardless of this flag.
- // EXACT ghost signal (see `VersionMap::ghost_events`): flushed
- // tombstones OR any overwrite/delete event ever recorded. The old
- // `live_count() < seg_physical + mem_physical` arithmetic also
- // tripped on unrelated physical-count drift — live-verified: two
- // duplicate docs per merged segment turned the gate permanently ON
- // for a pure append-only corpus, disabling the F1 bounded scan and
- // forcing every size>0 term/range/bool into a full O(N) stored
- // scan. That was the dominant per-query cost in the
- // read-under-write collapse.
- let deletes_present: bool = snap.segments.iter().any(|m| m.has_tombstones)
- || self.store.version_map.ghost_events() > 0;
-
// LOSS_BATTLE_PLAN B6 — page-cap materialisation. The +100/256
// hydration slack in `materialisation_limit` buys headroom against
// memtable/segment dedup overlap and version-map rejections; with an
@@ -18382,11 +18457,12 @@ impl Index {
// entirely — that call eagerly reads .fst/.meta/.post/.norms
// for every text field, which costs ~50 MB per segment and is
// wasted work when the query is a stored-doc scan.
- let fts_query_probe = query_node_to_fts_with_keyword_fields(
+ let fts_query_probe = query_node_to_fts_projected(
query,
&text_fields,
&exact_fields,
&kw_fields,
+ pinned_probe,
);
let needs_fts = fts_query_probe.is_some();
// #361: a bool with a non-projectable non-scoring (`filter`/`must_not`)
@@ -18401,6 +18477,7 @@ impl Index {
&text_fields,
&exact_fields,
&kw_fields,
+ pinned_probe,
);
// A `query_string` whose projection DECLINED still has to be
// answered by the stored-doc scan — an over-cap `tokens × fields`
@@ -18613,11 +18690,21 @@ impl Index {
// document happens to sit in. `None` keeps this
// segment's own stats (single-arm gate).
.with_collection_stats(collection_stats());
- let fts_query = query_node_to_fts_with_keyword_fields(
+ // #892 — resolve the pinned kNN ids to THIS segment's
+ // stored positions. `None` (no pinned tree, ghosts present,
+ // or a segment whose id index is incomplete) leaves the
+ // projection exactly as it was: it declines, and this
+ // segment alone falls through to the stored-doc scan below.
+ let pinned_positions = pinned_probe
+ .and_then(|_| self.id_pos_map_for(seg_id.as_str(), meta.doc_count));
+ let fts_query = query_node_to_fts_projected(
query,
&text_fields,
&exact_fields,
&kw_fields,
+ pinned_positions
+ .as_ref()
+ .map(|map| PinnedIds::Positions(map)),
);
// Count-only fast path for single-term FTS queries:
@@ -18755,6 +18842,8 @@ impl Index {
// way for count-only and size>0 so the fall-through
// decision (and thus the count) agrees.
fts_handled = true;
+ #[cfg(test)]
+ SEG_FTS_HANDLED.with(|c| c.set(c.get() + 1));
// #361 — this segment's hits carry exact BM25.
fts_scored_applied = true;
// #361 — residual membership gate. This bool has a
@@ -19425,6 +19514,8 @@ impl Index {
// returns correct results (just slower).
let scan_stored = scan_stored || (needs_fts && !fts_handled);
if !fts_handled && scan_stored {
+ #[cfg(test)]
+ SEG_STORED_SCANS.with(|c| c.set(c.get() + 1));
// #361 — this segment's hits are scored by
// `score_query_against_doc` (no IDF, no length norm), so
// the page mixes score scales and the IDF rescore below
@@ -24195,6 +24286,11 @@ impl Index {
/// gate's (and re-paid the 16-shard lock fan-out the capture exists to
/// avoid). The stats CONTENT still reads the live shards — exactly like
/// the memtable search arm it feeds, which holds no snapshot either.
+ // One argument over clippy's default: `pinned` (#892) joins the field
+ // sets, the snapshot and the memtable count that this pre-pass already
+ // needs, and they are all borrowed from `search_inner`'s frame — bundling
+ // them into a struct would only move the same list one level out.
+ #[allow(clippy::too_many_arguments)]
fn build_collection_stats(
&self,
snap: &xerj_storage::index_store::IndexSnapshot,
@@ -24203,6 +24299,10 @@ impl Index {
exact_fields: &HashSet<String>,
keyword_fields: &HashSet<String>,
mem_doc_count: usize,
+ // #892: same projection the segment loop will run, so a pinned kNN
+ // hybrid resolves its lexical leaves here too instead of declining and
+ // silently reverting every segment to per-segment BM25 statistics.
+ pinned: Option<PinnedIds<'_>>,
) -> Option<xerj_fts::CollectionStats> {
// Widest (field × term) pre-pass we will pay for. A field-less
// `query_string` over a wide mapping can project hundreds of leaves;
@@ -24212,12 +24312,8 @@ impl Index {
// convention as `MAX_QS_CROSS_PRODUCT`).
const MAX_STATS_PROBES: usize = 4096;
- let fq = query_node_to_fts_with_keyword_fields(
- query,
- text_fields,
- exact_fields,
- keyword_fields,
- )?;
+ let fq =
+ query_node_to_fts_projected(query, text_fields, exact_fields, keyword_fields, pinned)?;
let mut fields: Vec<String> = Vec::new();
collect_fts_query_fields(&fq, &mut fields);
if fields.is_empty() {
@@ -35342,8 +35438,8 @@ fn lower_lexically_typeless_clauses(
// THIS `retain` IS THE ONE WIRE-VISIBLE SCORE CHANGE in the pass.
// It does not move a hit COUNT — `doc_matches_query` never counts a
// `MatchNone` as a satisfied `should` — but the shrunken bool is
- // projectable through `query_node_to_fts_with_keyword_fields` where
- // the original was not, so BM25 scores it instead of
+ // projectable through `query_node_to_fts_projected` where the
+ // original was not, so BM25 scores it instead of
// `score_query_against_doc`. On the 300-doc fixture
// `bool{should:[term emb, term cat:"even"]}` keeps its 150 hits and
// goes `_score` 0.008402659 → 0.6931471 (exactly what
@@ -35386,8 +35482,8 @@ fn lower_lexically_typeless_clauses(
// ("bubble up MatchNoDocsQuery") and `BoostQuery.java:87`. It is exact
// — neither wrapper can make a non-matching inner query match — and it
// matters here because `Constant` is the ONLY wrapper with an arm in
- // `query_node_to_fts_with_keyword_fields`: left as
- // `Constant{MatchNone}` it projects to `None`, and `Constant` is in
+ // `query_node_to_fts_projected`: left as `Constant{MatchNone}` it
+ // projects to `None`, and `Constant` is in
// `is_doc_scan_query`, so `{"constant_score":{"filter":{"term":
// {"emb":…}}}}` would trade an inverted-index lookup for a full
// stored-doc scan.
@@ -35528,8 +35624,8 @@ fn lower_lexically_typeless_clauses(
/// is what decides whether the query then runs on the inverted index or on the
/// stored-doc scan. The distinction is not cosmetic: `Bool{must_not:[MatchNone]}`
/// and `Bool{}` give the same hits, but only the second projects through
-/// `query_node_to_fts_with_keyword_fields` — the first `?`s out on its
-/// `must_not` child and falls to a full corpus walk.
+/// `query_node_to_fts_projected` — the first `?`s out on its `must_not`
+/// child and falls to a full corpus walk.
#[cfg(test)]
mod lexically_typeless_lowering_tests {
use super::*;
@@ -35985,8 +36081,8 @@ mod lexically_typeless_lowering_tests {
// ── Wrappers ─────────────────────────────────────────────────────────
/// `Constant` is the only wrapper with an arm in
- /// `query_node_to_fts_with_keyword_fields`, so it is the only one where
- /// failing to bubble up costs an inverted-index lookup.
+ /// `query_node_to_fts_projected`, so it is the only one where failing to
+ /// bubble up costs an inverted-index lookup.
#[test]
fn constant_score_and_boost_bubble_up_match_none() {
assert!(lower(&QueryNode::Constant {
@@ -36124,8 +36220,8 @@ fn rewrite_keyword_full_text_to_term(q: &QueryNode, schema: &Schema) -> QueryNod
// keyword `Term`(s) and the text `multi_match` combine by MAX
// (+ tie_breaker 0.0), not the SUM a `Bool.should` gives. This
// mirrors the all-text per-field combination in
- // `query_node_to_fts_with_keyword_fields`, so a doc matching
- // both halves scores `max(keyword, text)` as ES does, not the
+ // `query_node_to_fts_projected`, so a doc matching both
+ // halves scores `max(keyword, text)` as ES does, not the
// sum. `most_fields` stays a `should` (ES sums it), and
// `cross_fields`/phrase variants are a separate concern (#572).
QueryNode::DisMax {
@@ -43721,6 +43817,10 @@ fn collect_fts_query_fields(q: &FtsQuery, out: &mut Vec<String>) {
collect_fts_query_fields(sub, out);
}
}
+ // #892: caller-supplied `(doc_id, score)` pairs — no field, so
+ // nothing to add and nothing for the "segment has FTS data for every
+ // queried field" gate to check.
+ FtsQuery::DocScores(_) => {}
FtsQuery::MatchAll => {}
}
}
@@ -43756,7 +43856,13 @@ fn collect_fts_query_terms(q: &FtsQuery, out: &mut Vec<(String, String)>) {
push(&p.field, term, out);
}
}
- FtsQuery::Prefix(_) | FtsQuery::Wildcard(_) | FtsQuery::Fuzzy(_) | FtsQuery::MatchAll => {}
+ // #892 `DocScores`: no term, and no `doc_freq` to unify — its
+ // scores are the vector leg's, already final.
+ FtsQuery::Prefix(_)
+ | FtsQuery::Wildcard(_)
+ | FtsQuery::Fuzzy(_)
+ | FtsQuery::MatchAll
+ | FtsQuery::DocScores(_) => {}
FtsQuery::Bool(b) => {
// `filter` is non-scoring, so its df never reaches a `_score`;
// it is collected anyway because the clause is still EXECUTED
@@ -43908,15 +44014,131 @@ fn query_node_to_fts(
// The projection tests below pass the exact-field set as their keyword
// subset. The search path uses the schema-aware helper so IP/date/numeric
// terms retain their source/DV semantics.
- query_node_to_fts_with_keyword_fields(q, text_fields, exact_fields, exact_fields)
+ query_node_to_fts_projected(q, text_fields, exact_fields, exact_fields, None)
+}
+
+/// #892: how the projection may resolve a #825-pinned kNN disjunct.
+///
+/// The pinned sub-tree `pin_knn_clause` splices in names documents by `_id`,
+/// and `_id` is not in the FTS term dictionary — so without this the whole
+/// projection `?`-aborts and the request falls to a stored-document scan of
+/// every segment. Resolving the ids to the segment's stored positions turns
+/// the disjunct into an ordinary FTS leaf ([`FtsQuery::DocScores`]).
+///
+/// `Copy` and `Sync`, so it can be held across the `await`s in `search_inner`
+/// without making that future non-`Send`.
+#[derive(Clone, Copy)]
+enum PinnedIds<'a> {
+ /// Shape probe: no segment in hand, so no id resolves. The projection
+ /// still SUCCEEDS, with an empty leaf — which is what the callers that
+ /// only ask "does this project at all?" (the needs-FTS probe, the
+ /// index-wide BM25 statistics pre-pass) need to hear.
+ Probe,
+ /// One segment's `_id` → stored-position map (`id_pos_map_for`), the same
+ /// index `ids` queries and `_mget` resolve through.
+ Positions(&'a std::collections::HashMap<String, u32>),
+}
+
+impl PinnedIds<'_> {
+ fn position(&self, id: &str) -> Option<u32> {
+ match self {
+ PinnedIds::Probe => None,
+ PinnedIds::Positions(map) => map.get(id).copied(),
+ }
+ }
}
-fn query_node_to_fts_with_keyword_fields(
+/// #892: recognise EXACTLY the sub-tree `pin_knn_clause` emits — a
+/// disjunction of `Constant{score, Ids{…}}` clauses, optionally gated by its
+/// redundant `filter: [Ids{union}]` accelerator — and return the
+/// `(id, score)` pairs it pins.
+///
+/// Deliberately narrow. It is a *shape* match, not an identity check, so a
+/// hand-written query of the same shape would also be recognised; that is
+/// sound (the answer is the same set of documents with the same constant
+/// scores) but the search path only ever offers it a tree it pinned itself.
+///
+/// Declines when:
+/// * the bool carries `must`/`must_not`, a `minimum_should_match` other
+/// than the implicit/explicit 1, or a `filter` that is not a single
+/// `Ids` — anything that is not the emitted shape;
+/// * a `should` child is not `Constant{Ids}`;
+/// * an id is pinned twice. `pin_knn_clause` never does that (the leg
+/// returns distinct ids), and a duplicate would be counted twice by the
+/// FTS bool's `should` tally.
+///
+/// The `filter` is an intersection, so ids outside it are dropped — which is
+/// exactly what the doc-scan does with the same tree.
+fn pinned_constant_ids_pairs(q: &QueryNode) -> Option<Vec<(&str, f32)>> {
+ let QueryNode::Bool {
+ must,
+ should,
+ filter,
+ must_not,
+ minimum_should_match,
+ } = q
+ else {
+ return None;
+ };
+ if !must.is_empty() || !must_not.is_empty() || should.is_empty() {
+ return None;
+ }
+ match minimum_should_match {
+ None => {}
+ Some(MinShouldMatch::Fixed(1)) => {}
+ Some(_) => return None,
+ }
+ let gate: Option<std::collections::HashSet<&str>> = match filter.as_slice() {
+ [] => None,
+ [QueryNode::Ids { values }] => Some(values.iter().map(String::as_str).collect()),
+ _ => return None,
+ };
+ let mut out: Vec<(&str, f32)> = Vec::with_capacity(should.len());
+ let mut seen: std::collections::HashSet<&str> = std::collections::HashSet::new();
+ for clause in should {
+ let QueryNode::Constant { score, query } = clause else {
+ return None;
+ };
+ let QueryNode::Ids { values } = query.as_ref() else {
+ return None;
+ };
+ for id in values {
+ if !seen.insert(id.as_str()) {
+ return None;
+ }
+ if gate.as_ref().is_none_or(|g| g.contains(id.as_str())) {
+ out.push((id.as_str(), *score));
+ }
+ }
+ }
+ Some(out)
+}
+
+/// The projection proper. `pinned` is `None` everywhere except the #825
+/// kNN-beside-`query` route (#892), where it lets the pinned disjunct become
+/// an FTS leaf instead of aborting the projection.
+fn query_node_to_fts_projected(
q: &QueryNode,
text_fields: &[String],
exact_fields: &std::collections::HashSet<String>,
keyword_fields: &std::collections::HashSet<String>,
+ pinned: Option<PinnedIds<'_>>,
) -> Option<FtsQuery> {
+ // #892: the pinned kNN disjunct, resolved to this segment's positions.
+ // Checked before the `match` because the sub-tree IS a `Bool` and would
+ // otherwise be walked clause by clause — where `Ids` projects to `None`
+ // and takes the whole request with it.
+ if let Some(pinned) = pinned {
+ if let Some(pairs) = pinned_constant_ids_pairs(q) {
+ let docs: Vec<(u32, f32)> = pairs
+ .into_iter()
+ .filter_map(|(id, score)| pinned.position(id).map(|pos| (pos, score)))
+ .collect();
+ return Some(FtsQuery::DocScores(xerj_fts::search::DocScoresQuery::new(
+ docs,
+ )));
+ }
+ }
match q {
QueryNode::MatchAll => {
// Return None; MatchAll is handled separately by reading stored docs.
@@ -43929,7 +44151,7 @@ fn query_node_to_fts_with_keyword_fields(
// keyword-schema shape is served bit-exactly by `scored_columnar`
// before this projection is ever consulted).
QueryNode::Constant { query, .. } => {
- query_node_to_fts_with_keyword_fields(query, text_fields, exact_fields, keyword_fields)
+ query_node_to_fts_projected(query, text_fields, exact_fields, keyword_fields, pinned)
}
QueryNode::Match {
field,
@@ -44269,11 +44491,12 @@ fn query_node_to_fts_with_keyword_fields(
let children: Vec<FtsQuery> = queries
.iter()
.filter_map(|c| {
- query_node_to_fts_with_keyword_fields(
+ query_node_to_fts_projected(
c,
text_fields,
exact_fields,
keyword_fields,
+ pinned,
)
})
.collect();
@@ -44356,11 +44579,12 @@ fn query_node_to_fts_with_keyword_fields(
// None in that case so the caller falls back to stored-scan,
// which handles all child shapes correctly.
for sub in must {
- let fq = query_node_to_fts_with_keyword_fields(
+ let fq = query_node_to_fts_projected(
sub,
text_fields,
exact_fields,
keyword_fields,
+ pinned,
)?;
bool_q = bool_q.must(fq);
projected_positive = true;
@@ -44387,11 +44611,12 @@ fn query_node_to_fts_with_keyword_fields(
// `residual_gate` pass in `search` (a `doc_matches_query` sweep
// over the original query; the shape is detected up-front by
// `bool_has_nonprojectable_nonscoring`).
- if let Some(fq) = query_node_to_fts_with_keyword_fields(
+ if let Some(fq) = query_node_to_fts_projected(
sub,
text_fields,
exact_fields,
keyword_fields,
+ pinned,
) {
bool_q = bool_q.filter(fq);
projected_positive = true;
@@ -44403,11 +44628,12 @@ fn query_node_to_fts_with_keyword_fields(
// dropped — dropping it makes the bool LESS permissive and
// loses docs that match only via that clause. Fall back to
// the stored-doc scan, which handles every child shape.
- let fq = query_node_to_fts_with_keyword_fields(
+ let fq = query_node_to_fts_projected(
sub,
text_fields,
exact_fields,
keyword_fields,
+ pinned,
)?;
bool_q = bool_q.should(fq);
projected_positive = true;
@@ -44419,11 +44645,12 @@ fn query_node_to_fts_with_keyword_fields(
// non-scoring residual — skip it (don't `?`-abort); the
// `residual_gate` pass in `search` re-excludes it via
// `doc_matches_query` over the original query.
- if let Some(fq) = query_node_to_fts_with_keyword_fields(
+ if let Some(fq) = query_node_to_fts_projected(
sub,
text_fields,
exact_fields,
keyword_fields,
+ pinned,
) {
bool_q = bool_q.must_not(fq);
}
@@ -44803,8 +45030,8 @@ fn query_node_to_fts_with_keyword_fields(
/// projected to FTS (e.g. `exists`, non-numeric `range`, `script`)?
///
/// Such a non-scoring child is skipped from the FTS bool by the projection
-/// (`query_node_to_fts_with_keyword_fields`) so the scoring subtree keeps exact
-/// BM25 — but it is then absent from the FTS match set, so membership must be
+/// (`query_node_to_fts_projected`) so the scoring subtree keeps exact BM25 —
+/// but it is then absent from the FTS match set, so membership must be
/// re-applied by a `doc_matches_query` gate over the original query, and the
/// count/materialisation fast path (which assumes the FTS bool IS the exact
/// match set) must be switched off for the segment.
@@ -44813,7 +45040,17 @@ fn bool_has_nonprojectable_nonscoring(
text_fields: &[String],
exact_fields: &std::collections::HashSet<String>,
keyword_fields: &std::collections::HashSet<String>,
+ pinned: Option<PinnedIds<'_>>,
) -> bool {
+ // #892: the #825 pinned sub-tree projects WHOLE (to a `DocScores` leaf),
+ // so its internal `filter: [Ids{…}]` accelerator is never consulted by the
+ // projection and must not arm the residual gate here. Without this the
+ // gate fires on every pinned hybrid, forcing `fts_cap = usize::MAX` plus an
+ // O(matches) `doc_matches_query` sweep — the scan this fix removes, one
+ // layer down.
+ if pinned.is_some() && pinned_constant_ids_pairs(q).is_some() {
+ return false;
+ }
match q {
QueryNode::Bool {
must,
@@ -44823,11 +45060,12 @@ fn bool_has_nonprojectable_nonscoring(
..
} => {
for sub in filter.iter().chain(must_not.iter()) {
- if query_node_to_fts_with_keyword_fields(
+ if query_node_to_fts_projected(
sub,
text_fields,
exact_fields,
keyword_fields,
+ pinned,
)
.is_none()
{
@@ -44839,12 +45077,22 @@ fn bool_has_nonprojectable_nonscoring(
.chain(filter.iter())
.chain(must_not.iter())
.any(|c| {
- bool_has_nonprojectable_nonscoring(c, text_fields, exact_fields, keyword_fields)
+ bool_has_nonprojectable_nonscoring(
+ c,
+ text_fields,
+ exact_fields,
+ keyword_fields,
+ pinned,
+ )
})
}
- QueryNode::Constant { query, .. } => {
- bool_has_nonprojectable_nonscoring(query, text_fields, exact_fields, keyword_fields)
- }
+ QueryNode::Constant { query, .. } => bool_has_nonprojectable_nonscoring(
+ query,
+ text_fields,
+ exact_fields,
+ keyword_fields,
+ pinned,
+ ),
_ => false,
}
}
@@ -50769,6 +51017,15 @@ thread_local! {
/// reached inside the `residual_gate` per-segment loop.
pub(crate) static RESIDUAL_HITS_PEAK: std::cell::Cell<usize> =
const { std::cell::Cell::new(0) };
+ /// #892 fail-before instrument: how many segments the search answered
+ /// from the inverted index (`fts_handled`) and how many it answered by
+ /// parsing their stored section. Which route a request took is invisible
+ /// from the response — the hits, the total and the ordering contract are
+ /// the same either way — so this is what a test can assert on.
+ pub(crate) static SEG_FTS_HANDLED: std::cell::Cell<usize> =
+ const { std::cell::Cell::new(0) };
+ pub(crate) static SEG_STORED_SCANS: std::cell::Cell<usize> =
+ const { std::cell::Cell::new(0) };
}
#[cfg(test)]
@@ -50833,3 +51090,245 @@ mod residual_gate_trim_577_tests {
);
}
}
+
+#[cfg(test)]
+mod pinned_knn_fts_892_tests {
+ use super::*;
+ use serde_json::json;
+
+ /// #892: a `knn` clause beside a `query` must be answered from the
+ /// INVERTED INDEX, not by parsing every stored document of every segment.
+ ///
+ /// #825/#879 made this shape CORRECT by pre-executing the vector leg and
+ /// splicing its top-k back in as `Constant{score, Ids{[id]}}` pinned
+ /// clauses. `Ids` has no FTS projection — `_id` is not a term — so the
+ /// projection's `should` loop `?`-aborted, `fts_query` came back `None`,
+ /// and every segment fell to `scan_stored_section_into`.
+ ///
+ /// That route is not merely slow, and this test asserts the part that is
+ /// USER-VISIBLE. The stored scan admits documents in STORED-LAYOUT order
+ /// and, once `all_hits` reaches `materialisation_limit`, materialises
+ /// nothing further — it `continue`s to keep counting, with no score
+ /// comparison (see the cap in `scan_stored_section_into`). So on a corpus
+ /// with more lexical matches than the page cap, the documents reached by
+ /// BOTH halves — the ones the #825 contract scores `query_score +
+ /// knn_score` and puts at the top — never enter the page at all if they
+ /// sit late in the segment. `hits.total` stays exact; the page is wrong.
+ ///
+ /// FAIL-BEFORE (watched): with `pinned_probe` forced to `None` in
+ /// `search_inner` — the pre-#892 behaviour — the page is 10 lexical-only
+ /// documents and the assertion below reports the both-halves documents
+ /// missing. `hits.total` is 407 either way.
+ #[tokio::test]
+ async fn pinned_knn_hybrid_is_answered_from_the_inverted_index() {
+ let dir = tempfile::tempdir().unwrap();
+ let mut config = Config::default();
+ config.server.data_dir = dir.path().to_string_lossy().into_owned();
+ let engine = crate::Engine::new(config).unwrap();
+ let mut schema = Schema::empty();
+ schema
+ .add_field(FieldConfig::new("body", FieldType::Text))
+ .unwrap();
+ let mut vector = FieldConfig::new("v", FieldType::Vector);
+ vector.options.dimensions = Some(2);
+ schema.add_field(vector).unwrap();
+ engine.create_index("hy892", schema).unwrap();
+ let idx = engine.get_index("hy892").unwrap();
+
+ // 1200 documents. Every third carries the lexical probe term with
+ // IDENTICAL text (same tf, same field length → identical BM25), so
+ // 400 lexical matches — comfortably more than the page cap, which is
+ // what makes the stored scan's layout-ordered admission observable.
+ // Vectors fan from [0,1] to [1,0], so the query vector [1,0] puts the
+ // LAST ten (d1190..d1199) in the k=10 neighbourhood; three of those
+ // are also lexical matches (1191, 1194, 1197) and must lead the page
+ // in vector order, 1197 first.
+ const N: usize = 1200;
+ for i in 0..N {
+ let body = if i % 3 == 0 {
+ "alpha filler"
+ } else {
+ "beta filler"
+ };
+ let t = i as f32 / N as f32;
+ idx.index_document(
+ Some(format!("d{i}")),
+ json!({ "body": body, "v": [t, 1.0 - t] }),
+ )
+ .await
+ .unwrap();
+ }
+ idx.flush().await.unwrap();
+
+ SEG_FTS_HANDLED.with(|c| c.set(0));
+ SEG_STORED_SCANS.with(|c| c.set(0));
+ let req = xerj_query::parse_request(&json!({
+ "size": 10,
+ "track_total_hits": true,
+ "query": {"bool": {"should": [
+ {"match": {"body": "alpha"}},
+ {"knn": {"field": "v", "query_vector": [1.0, 0.0], "k": 10,
+ "num_candidates": 100}}
+ ]}}
+ }))
+ .unwrap();
+ let res = idx.search(&req).await.unwrap();
+
+ // The union: 400 lexical matches ∪ 10 neighbours, overlapping in
+ // three documents. Exact on BOTH routes — the page is what differs.
+ assert_eq!(
+ res.total.value, 407,
+ "hits.total must be the UNION of the lexical half (400) and the \
+ vector top-10, which share d1191/d1194/d1197: got {:?}",
+ res.total
+ );
+
+ let page: Vec<(&str, f32)> = res.hits.iter().map(|h| (h.id.as_str(), h.score)).collect();
+ let ids: Vec<&str> = page.iter().map(|(id, _)| *id).collect();
+ assert_eq!(
+ &ids[..3],
+ &["d1197", "d1194", "d1191"],
+ "#825/#892: the documents reached by BOTH halves score \
+ `query_score + knn_score` and must lead the page, ordered by \
+ their vector scores — the stored-doc scan drops them because it \
+ admits in layout order and stops materialising at the page cap: \
+ page={page:?}"
+ );
+ assert!(
+ page[2].1 > page[3].1,
+ "the last both-halves document must still outrank the best \
+ lexical-only one: {page:?}"
+ );
+
+ // And it came from the index, on every segment.
+ let fts = SEG_FTS_HANDLED.with(|c| c.get());
+ let scans = SEG_STORED_SCANS.with(|c| c.get());
+ assert!(
+ fts > 0 && scans == 0,
+ "the pinned kNN hybrid must be served by the FTS path on every \
+ segment: fts={fts} stored_scans={scans}"
+ );
+ }
+
+ /// The projection arm in isolation: `pin_knn_clause`'s output lifts to a
+ /// `DocScores` leaf carrying the resolved positions and the pinned
+ /// scores, and the ids the segment does not hold are simply absent.
+ #[test]
+ fn pinned_sub_tree_projects_to_a_doc_scores_leaf() {
+ let pinned = QueryNode::Bool {
+ must: Vec::new(),
+ should: vec![
+ QueryNode::Constant {
+ score: 0.75,
+ query: Box::new(QueryNode::Ids {
+ values: vec!["a".into()],
+ }),
+ },
+ QueryNode::Constant {
+ score: 0.25,
+ query: Box::new(QueryNode::Ids {
+ values: vec!["elsewhere".into()],
+ }),
+ },
+ ],
+ filter: vec![QueryNode::Ids {
+ values: vec!["a".into(), "elsewhere".into()],
+ }],
+ must_not: Vec::new(),
+ minimum_should_match: Some(MinShouldMatch::Fixed(1)),
+ };
+ let text_fields: Vec<String> = vec!["body".into()];
+ let empty: std::collections::HashSet<String> = std::collections::HashSet::new();
+
+ // Without a resolver the projection declines exactly as it did before
+ // #892 — `Ids` is not a term.
+ assert!(
+ query_node_to_fts_projected(&pinned, &text_fields, &empty, &empty, None).is_none(),
+ "no resolver ⇒ the pinned sub-tree must still decline"
+ );
+
+ let mut positions: std::collections::HashMap<String, u32> =
+ std::collections::HashMap::new();
+ positions.insert("a".into(), 7);
+ let projected = query_node_to_fts_projected(
+ &pinned,
+ &text_fields,
+ &empty,
+ &empty,
+ Some(PinnedIds::Positions(&positions)),
+ )
+ .expect("a resolvable pinned sub-tree must project");
+ match projected {
+ FtsQuery::DocScores(ds) => assert_eq!(
+ ds.docs,
+ vec![(7u32, 0.75f32)],
+ "only the id this segment holds, at its stored position, with \
+ the vector leg's score"
+ ),
+ other => panic!("expected a DocScores leaf, got {other:?}"),
+ }
+ }
+
+ /// Guard rails on the shape match: anything that is not what
+ /// `pin_knn_clause` emits must NOT be lifted, because the arm skips the
+ /// clause-by-clause walk that would otherwise check it.
+ #[test]
+ fn only_the_pinned_shape_is_lifted() {
+ let ids = |v: &str| QueryNode::Ids {
+ values: vec![v.into()],
+ };
+ let pinned_child = |v: &str| QueryNode::Constant {
+ score: 1.0,
+ query: Box::new(ids(v)),
+ };
+ // A `must` alongside the pinned disjuncts is not the emitted shape.
+ assert!(pinned_constant_ids_pairs(&QueryNode::Bool {
+ must: vec![ids("a")],
+ should: vec![pinned_child("a")],
+ filter: Vec::new(),
+ must_not: Vec::new(),
+ minimum_should_match: None,
+ })
+ .is_none());
+ // A `minimum_should_match` other than 1 changes the match set.
+ assert!(pinned_constant_ids_pairs(&QueryNode::Bool {
+ must: Vec::new(),
+ should: vec![pinned_child("a"), pinned_child("b")],
+ filter: Vec::new(),
+ must_not: Vec::new(),
+ minimum_should_match: Some(MinShouldMatch::Fixed(2)),
+ })
+ .is_none());
+ // A duplicate id would be tallied twice by the FTS `should` counter.
+ assert!(pinned_constant_ids_pairs(&QueryNode::Bool {
+ must: Vec::new(),
+ should: vec![pinned_child("a"), pinned_child("a")],
+ filter: Vec::new(),
+ must_not: Vec::new(),
+ minimum_should_match: None,
+ })
+ .is_none());
+ // A non-`Constant` disjunct is an ordinary scoring clause.
+ assert!(pinned_constant_ids_pairs(&QueryNode::Bool {
+ must: Vec::new(),
+ should: vec![ids("a")],
+ filter: Vec::new(),
+ must_not: Vec::new(),
+ minimum_should_match: None,
+ })
+ .is_none());
+ // The emitted shape itself IS lifted.
+ assert_eq!(
+ pinned_constant_ids_pairs(&QueryNode::Bool {
+ must: Vec::new(),
+ should: vec![pinned_child("a"), pinned_child("b")],
+ filter: vec![QueryNode::Ids {
+ values: vec!["a".into(), "b".into()]
+ }],
+ must_not: Vec::new(),
+ minimum_should_match: Some(MinShouldMatch::Fixed(1)),
+ }),
+ Some(vec![("a", 1.0f32), ("b", 1.0f32)])
+ );
+ }
+}
diff --git a/engine/crates/xerj-fts/src/search.rs b/engine/crates/xerj-fts/src/search.rs
index 1a2545ab1..aae6b60ec 100644
--- a/engine/crates/xerj-fts/src/search.rs
+++ b/engine/crates/xerj-fts/src/search.rs
@@ -432,6 +432,43 @@ impl DisMaxQuery {
}
}
+/// A leaf whose match set and per-document scores are supplied by the
+/// CALLER, already resolved to this segment's stored positions
+/// (#892).
+///
+/// Every other leaf in this enum resolves its documents through the term
+/// dictionary. Some match sets cannot be expressed that way — the engine's
+/// `_id` primary keys are not indexed as FTS terms — yet they still have to
+/// take part in an inverted-index query instead of forcing the whole request
+/// onto a stored-document scan. The engine's kNN-beside-`query` hybrid is
+/// exactly that shape: the vector leg has already run, so its top-k documents
+/// and their scores are known facts, and this node carries them into the same
+/// `BoolQuery` combination as the lexical half.
+///
+/// Contract for the caller:
+/// * `docs` holds `(doc_id, score)` pairs for ONE segment — the doc ids are
+/// that segment's stored positions, exactly what the postings lists use.
+/// * ids that do not live in this segment are simply absent; the segment's
+/// own projection is responsible for resolving them.
+/// * duplicates are the caller's business (scores are emitted verbatim).
+///
+/// Liveness is NOT applied here — like every other leaf, this one reports
+/// physical positions and the engine filters tombstones/superseded copies
+/// during materialisation.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct DocScoresQuery {
+ /// `(doc_id, score)`, ascending by `doc_id` so the emitted hits keep the
+ /// ascending-doc_id order every other leaf produces.
+ pub docs: Vec<(u32, f32)>,
+}
+
+impl DocScoresQuery {
+ pub fn new(mut docs: Vec<(u32, f32)>) -> Self {
+ docs.sort_unstable_by_key(|&(doc_id, _)| doc_id);
+ Self { docs }
+ }
+}
+
/// Top-level query enum.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
@@ -445,6 +482,8 @@ pub enum Query {
Bool(Box<BoolQuery>),
DisMax(Box<DisMaxQuery>),
MatchAll,
+ /// Caller-supplied `(doc_id, score)` set — see [`DocScoresQuery`].
+ DocScores(DocScoresQuery),
}
// ── FtsSearcher ───────────────────────────────────────────────────────────────
@@ -618,6 +657,20 @@ impl FtsSearcher {
Query::Bool(bq) => self.execute_bool(bq, explain),
Query::DisMax(dq) => self.execute_dis_max(dq, explain),
Query::MatchAll => self.execute_match_all(),
+ // #892: the pairs are already this segment's answer — no term
+ // dictionary, no postings decode, no scorer. `explain` produces
+ // no breakdown because there is no term-level derivation to
+ // show; the engine never asks this leaf to explain (its FTS
+ // calls all pass `explain: false`).
+ Query::DocScores(ds) => Ok(ds
+ .docs
+ .iter()
+ .map(|&(doc_id, score)| ScoredHit {
+ doc_id,
+ score,
+ explanation: None,
+ })
+ .collect()),
}
}