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): rank the memtable's bounded candidates by the page key too (#191)

xerj-org5f048cbc0e6c
diff --git a/engine/crates/xerj-engine/src/index.rs b/engine/crates/xerj-engine/src/index.rs
index 2b03a93f0..84a779b56 100644
--- a/engine/crates/xerj-engine/src/index.rs
+++ b/engine/crates/xerj-engine/src/index.rs
@@ -11836,6 +11836,39 @@ impl Index {
worst
}
+ /// Reduce `hits` to the best `cap` under the SAME comparator the final page
+ /// sort uses (`score DESC, seq_no ASC, _id ASC` — `index.rs:16222-16228`),
+ /// and return the surviving cap-th `(score, seq_no, _id)` page key.
+ ///
+ /// #191 — every bounded collector in `search` trims through here, so
+ /// admission and final ordering can never drift apart: a `size:5` page is
+ /// the first five of a `size:1000` one whatever order the walk visited the
+ /// documents in.
+ #[allow(clippy::type_complexity)]
+ fn trim_page_to_cap(
+ &self,
+ hits: Vec<Hit>,
+ cap: usize,
+ ) -> (Vec<Hit>, Option<(f32, u64, String)>) {
+ let mut decorated: Vec<(u64, Hit)> = hits
+ .into_iter()
+ .map(|h| (self.lookup_seq_no(&h.id).unwrap_or(u64::MAX), h))
+ .collect();
+ decorated.sort_by(|a, b| {
+ b.1.score
+ .partial_cmp(&a.1.score)
+ .unwrap_or(std::cmp::Ordering::Equal)
+ .then_with(|| a.0.cmp(&b.0))
+ .then_with(|| a.1.id.cmp(&b.1.id))
+ });
+ decorated.truncate(cap);
+ let worst = decorated
+ .last()
+ .map(|(seq, h)| (h.score, *seq, h.id.clone()));
+ let kept = decorated.into_iter().map(|(_, h)| h).collect();
+ (kept, worst)
+ }
+
/// Look up the latest `seq_no` for a document by id via the version
/// map. Returns `None` when the doc is unknown or tombstoned.
///
@@ -13501,6 +13534,26 @@ impl Index {
// memtable and a segment (possible during a flush race). We prefer
// the first appearance (which is usually the memtable, i.e. the
// newest version).
+ //
+ // #191 — the `materialisation_limit` bound here is a plain FIFO cut,
+ // and it is only CORRECT because every arm that feeds it upholds one
+ // of two invariants:
+ //
+ // * `AllDocIds` / `DocValuesHits` — the memtable already narrowed
+ // its candidates to the globally best `limit` by `(seq_no, _id)`
+ // (`ShardedFtsMemtable::narrow_to_page`), so the FIFO never
+ // truncates at all; and
+ // * `FtsHits` — the memtable returns its hits already sorted by the
+ // full page key (`sort_hits_by_page_key`), so the first `limit`
+ // ARE the page. This matters on the ghost-window path, which asks
+ // the memtable for every hit rather than a bounded prefix.
+ //
+ // The brute-scan arm upholds neither (it walks shards in index order),
+ // so it does NOT route post-cap admissions through here — see the
+ // `DocsForScan` arm. Before #191 the FIFO was applied to unordered
+ // input and the surviving tied documents were decided by shard-walk
+ // order: `size:5` and `size:1000` disagreed on a 600-document
+ // all-tied memtable.
macro_rules! admit_hit {
($hit:expr) => {{
total_count += 1;
@@ -13616,7 +13669,11 @@ impl Index {
/// The `u64` is the UNCOLLECTED matching-doc remainder (bounded
/// fused-bool path); it still counts toward `hits.total`.
DocValuesHits(Vec<(String, usize)>, u64),
- DocsForScan(Vec<(String, Arc<Value>)>), // doc_id + shared source for term-level scan
+ /// `(seq_no, doc_id, shared source)` for a term-level brute scan.
+ /// #191 — `seq_no` rides along so the bounded collector can rank a
+ /// document it reaches after filling the cap against the page it
+ /// already holds; shard-concatenation order is not arrival order.
+ DocsForScan(Vec<(u64, String, Arc<Value>)>),
}
// Search the memtable (unflushed docs only). Flushed docs are searched
@@ -13796,7 +13853,7 @@ impl Index {
// the heap is full (NOT the id-only snapshot,
// whose per-doc deep clone cost ~1 s/query at a
// 1 M-doc memtable).
- None => MemSnapshot::DocsForScan(mem.all_docs_with_sources_arc()),
+ None => MemSnapshot::DocsForScan(mem.all_docs_with_seq_arc()),
}
} else {
let (ids, total) = mem.doc_ids_bounded(materialisation_limit);
@@ -13880,7 +13937,7 @@ impl Index {
} else {
// Brute per-doc scan — same authority the size>0
// path falls back to; `doc_matches_query` semantics.
- MemSnapshot::DocsForScan(mem.all_docs_with_sources_arc())
+ MemSnapshot::DocsForScan(mem.all_docs_with_seq_arc())
}
} else if let Some((hits, total)) = (|| {
// Fused columnar term/range/bool: ONE position walk
@@ -13934,7 +13991,7 @@ impl Index {
// query (plus a second per-doc clone for `_id`
// injection below) was the single hottest search-side
// cost in the read-under-write thread dumps.
- let docs: Vec<(String, Arc<Value>)> = mem.all_docs_with_sources_arc();
+ let docs: Vec<(u64, String, Arc<Value>)> = mem.all_docs_with_seq_arc();
MemSnapshot::DocsForScan(docs)
}
} else {
@@ -14100,7 +14157,15 @@ impl Index {
let query_may_read_id: bool = serde_json::to_string(query)
.map(|s| s.contains("_id") || s.contains("Ids") || s.contains("ids"))
.unwrap_or(true);
- for (doc_id, source) in docs {
+ // #191 — the cap-th page key the bounded collector currently
+ // holds, recomputed only when it can have changed (the moment
+ // the collector first fills, and after every trim). A stale
+ // value is always a WEAKER threshold than the truth — it admits
+ // more than strictly necessary, never less — which is the safe
+ // direction, the same argument the segment walk's `page_worst`
+ // relies on.
+ let mut scan_worst: Option<(f32, u64, String)> = None;
+ for (seq_no, doc_id, source) in docs {
let matched = if let QueryNode::Ids { values } = query {
values.iter().any(|v| v == doc_id.as_str())
} else if !query_may_read_id || source.get("_id").is_some() {
@@ -14121,13 +14186,31 @@ impl Index {
// Materialise (score + owned source) ONLY when the
// hit can actually enter the bounded collector /
// top-N heap; everything else is a bare count.
- // Identical outcome to unconditionally building the
- // Hit: `admit_hit!` drops post-cap hits anyway.
+ //
+ // #191 — "can enter" is no longer "the collector still
+ // has room". This walk visits shards in index order
+ // and each shard in arrival order, so it is NOT a
+ // globally arrival-ordered walk: a document reached
+ // after the cap is full can still hold a smaller
+ // `seq_no` than the page's worst hit and therefore win
+ // the tie-break against it. Admit exactly those as
+ // well — one `u64` compare against `scan_worst`, no
+ // extra source clone for the ones that lose — and let
+ // the trim below put the collector back at the cap by
+ // the final comparator. Documents that lose on
+ // `seq_no` but would have won on SCORE are still
+ // dropped here; that is pre-existing (they were dropped
+ // outright before) and is recorded under Residual risk.
+ let competitive = all_hits.len() < materialisation_limit || {
+ if scan_worst.is_none() {
+ scan_worst = self.worst_page_key(&all_hits);
+ }
+ scan_worst.as_ref().is_some_and(|w| seq_no < w.1)
+ };
if count_only {
total_count += 1;
} else if sort_topk.is_some()
- || (all_hits.len() < materialisation_limit
- && !seen_ids.contains(&doc_id))
+ || (competitive && !seen_ids.contains(&doc_id))
{
// Field-sorted: pre-clone primary-key rejection.
// Once the heap is full, a doc whose PRIMARY
@@ -14147,7 +14230,7 @@ impl Index {
}
}
let score = score_doc(&source, &doc_id);
- admit_hit!(Hit {
+ let hit = Hit {
id: doc_id,
score,
source: (*source).clone(),
@@ -14156,7 +14239,30 @@ impl Index {
highlight: None,
matched_queries: Vec::new(),
passage: None,
- });
+ };
+ if sort_topk.is_some() {
+ admit_hit!(hit);
+ } else {
+ // `admit_hit!`'s FIFO bound would throw the
+ // post-cap admissions above straight back
+ // away, so this arm collects them itself and
+ // trims by the page comparator once the
+ // overflow reaches 2×cap — the same eager-trim
+ // shape the segment walk uses.
+ total_count += 1;
+ if !seen_ids.contains(&hit.id) {
+ seen_ids.insert(hit.id.clone());
+ all_hits.push(hit);
+ if all_hits.len() > materialisation_limit.saturating_mul(2) {
+ let (kept, worst) = self.trim_page_to_cap(
+ std::mem::take(&mut all_hits),
+ materialisation_limit,
+ );
+ all_hits = kept;
+ scan_worst = worst;
+ }
+ }
+ }
} else {
total_count += 1;
}
@@ -14165,6 +14271,18 @@ impl Index {
}
}
+ // #191 — normalise the memtable contribution back to exactly the cap
+ // before the segment walk starts, so every downstream stage sees the
+ // documented shape (`all_hits` holds the best `materialisation_limit`
+ // by the final comparator). Only the brute-scan arm can overshoot —
+ // it admits post-cap documents that outrank the page it holds — and
+ // only up to 2×cap before its own eager trim fires.
+ if sort_topk.is_none() && all_hits.len() > materialisation_limit {
+ let (kept, _worst) =
+ self.trim_page_to_cap(std::mem::take(&mut all_hits), materialisation_limit);
+ all_hits = kept;
+ }
+
// --- Segment search ---
// `snap` is captured ABOVE the memtable arms (see the point-in-time
// capture ORDER comment there): segment snapshot strictly before the
@@ -15177,31 +15295,8 @@ impl Index {
Vec<Hit>,
Option<(f32, u64, String)>,
) {
- let mut decorated: Vec<(u64, Hit)> = hits
- .into_iter()
- .map(|h| {
- (
- self.lookup_seq_no(&h.id)
- .unwrap_or(u64::MAX),
- h,
- )
- })
- .collect();
- decorated.sort_by(|a, b| {
- b.1.score
- .partial_cmp(&a.1.score)
- .unwrap_or(std::cmp::Ordering::Equal)
- .then_with(|| a.0.cmp(&b.0))
- .then_with(|| a.1.id.cmp(&b.1.id))
- });
- decorated.truncate(materialisation_limit);
- let worst = decorated
- .last()
- .map(|(seq, h)| (h.score, *seq, h.id.clone()));
- let kept =
- decorated.into_iter().map(|(_, h)| h).collect();
- (kept, worst)
- };
+ self.trim_page_to_cap(hits, materialisation_limit)
+ };
for sh in &seg_hits {
// `seg_hits` descends by score, so once
// a hit's score is STRICTLY below the
diff --git a/engine/crates/xerj-engine/src/memtable.rs b/engine/crates/xerj-engine/src/memtable.rs
index 0005b41fa..cc7346b8f 100644
--- a/engine/crates/xerj-engine/src/memtable.rs
+++ b/engine/crates/xerj-engine/src/memtable.rs
@@ -23,6 +23,33 @@ use xerj_fts::bm25::Bm25Scorer;
pub struct MemtableHit {
pub doc_id: String,
pub score: f32,
+ /// WAL `seq_no` of the buffered document (`u64::MAX` when it can't be
+ /// resolved). #191 — the memtable's bounded FTS materialisation has to
+ /// truncate under the SAME total order the final page sort uses
+ /// (`score DESC, seq_no ASC, _id ASC`); score alone leaves the survivors
+ /// of a tie decided by shard-walk order, which is not arrival order.
+ pub seq_no: u64,
+}
+
+/// Order `hits` by the page key XERJ's final sort uses: `score DESC`, then
+/// `seq_no ASC` (arrival order — the `_doc` analogue), then `_id ASC`
+/// (`index.rs:16222-16228`).
+///
+/// #191 — any bounded materialisation must truncate under the SAME total order
+/// the page is finally sorted by, otherwise the documents that survive a tie
+/// are decided by whatever order the walk happened to visit them in. Lucene
+/// makes the same comparator total for the same reason
+/// (`HitQueue.lessThan` breaks an equal score by the smaller doc id,
+/// `lucene/core/src/java/org/apache/lucene/search/HitQueue.java:76-82`);
+/// approach only, no code taken.
+fn sort_hits_by_page_key(hits: &mut [MemtableHit]) {
+ hits.sort_unstable_by(|a, b| {
+ b.score
+ .partial_cmp(&a.score)
+ .unwrap_or(std::cmp::Ordering::Equal)
+ .then_with(|| a.seq_no.cmp(&b.seq_no))
+ .then_with(|| a.doc_id.cmp(&b.doc_id))
+ });
}
#[cfg(test)]
@@ -829,17 +856,49 @@ impl ShardedFtsMemtable {
/// on every request — ~1 s per query at a 300 k-doc memtable under
/// sustained bulk load (the `mem_admit` phase of the read-under-write
/// breakdown).
+ /// #191 — reduce per-shard bounded candidates to the globally best `limit`
+ /// under the order the final page sort uses.
+ ///
+ /// Every hit these paths produce carries the SAME score (`1.0` for the
+ /// id-only and doc-values collectors; a top-level `constant_score` rewrites
+ /// them all to the wrapper's boost), so the page order reduces to
+ /// `(seq_no ASC, _id ASC)` — the tail of `(score DESC, seq_no ASC, _id ASC)`
+ /// at `index.rs:16222-16228`.
+ ///
+ /// Returns the surviving cap-th `seq_no` as the next shard's cutoff, so the
+ /// walk can stop cloning ids that can no longer reach the page.
+ fn narrow_to_page<T>(cands: &mut Vec<(u64, String, T)>, limit: usize) -> u64 {
+ if cands.len() <= limit {
+ return u64::MAX;
+ }
+ cands.sort_unstable_by(|a, b| a.0.cmp(&b.0).then_with(|| a.1.cmp(&b.1)));
+ cands.truncate(limit);
+ cands.last().map_or(u64::MAX, |c| c.0)
+ }
+
pub fn doc_ids_bounded(&self, limit: usize) -> (Vec<String>, u64) {
- let mut out: Vec<String> = Vec::with_capacity(limit.min(4096));
+ // #191 — this used to fill greedily from shard 0 (`limit - out.len()`
+ // of room for each later shard), so an index whose memtable held more
+ // than `limit` documents returned "shard 0's first `limit` ids", not
+ // "the `limit` earliest-arriving ids". Shard assignment is by doc-id
+ // hash (and by BATCH for bulk), so that set is neither arrival order
+ // nor stable, and `size:5` stopped being a prefix of `size:1000` on an
+ // all-tied corpus. Bound each shard independently and keep the global
+ // best `limit` by `(seq_no, _id)` instead.
+ let mut cands: Vec<(u64, String, ())> = Vec::with_capacity(limit.min(4096));
let mut total: u64 = 0;
+ let mut cutoff = u64::MAX;
for s in &self.shards {
let g = s.read();
total += g.doc_count() as u64;
- if out.len() < limit {
- out.extend(g.doc_ids_up_to(limit - out.len()));
- }
+ cands.extend(
+ g.ranked_ids_up_to(limit, cutoff)
+ .into_iter()
+ .map(|(q, id)| (q, id, ())),
+ );
+ cutoff = Self::narrow_to_page(&mut cands, limit);
}
- (out, total)
+ (cands.into_iter().map(|(_, id, ())| id).collect(), total)
}
/// Return every (doc_id, source) pair. Aggregates across all
@@ -863,6 +922,22 @@ impl ShardedFtsMemtable {
out
}
+ /// `(seq_no, doc_id, source_arc)` for every buffered document.
+ ///
+ /// #191 — the brute per-doc scan's bounded collector has to decide whether
+ /// a document it reaches AFTER filling the cap still belongs on the page.
+ /// Shards are concatenated in index order, which is not arrival order, so
+ /// that decision needs the document's arrival `seq_no`. Carrying it in the
+ /// snapshot costs 8 bytes per entry and saves a `VersionMap` hash lookup
+ /// per match on the hottest memtable read path.
+ pub fn all_docs_with_seq_arc(&self) -> Vec<(u64, String, Arc<Value>)> {
+ let mut out = Vec::new();
+ for s in &self.shards {
+ out.extend(s.read().all_docs_with_seq_arc());
+ }
+ out
+ }
+
/// Columnar-filtered twin of `all_docs_with_sources_arc`: materialise ONLY
/// the `(doc_id, source_arc)` pairs matching `preds` (a pure conjunction of
/// Term/Range predicates), so a filtered `size:0` aggregation folds
@@ -1294,11 +1369,12 @@ impl ShardedFtsMemtable {
field_boosts,
));
}
- all.sort_by(|a, b| {
- b.score
- .partial_cmp(&a.score)
- .unwrap_or(std::cmp::Ordering::Equal)
- });
+ // #191 — the cross-shard merge sorts by the FULL page key, not by score
+ // alone. Score alone leaves ties in shard-concatenation order, so
+ // `truncate(limit)` kept "the tied documents that happen to live in the
+ // lowest-numbered shards" rather than the earliest-arriving ones, and a
+ // `size:5` page stopped being a prefix of a `size:1000` one.
+ sort_hits_by_page_key(&mut all);
// A doc_id lives in exactly ONE shard, so `all` has no duplicates:
// its pre-truncation length IS the exact global match count when
// `shard_limit == usize::MAX` (a lower bound otherwise).
@@ -1482,19 +1558,28 @@ impl ShardedFtsMemtable {
if preds.is_empty() {
return None;
}
- let mut out: Vec<(String, usize)> = Vec::new();
+ // #191 — bound each shard independently and keep the global best
+ // `limit` by `(seq_no, _id)`; `limit - out.len()` starved every shard
+ // after the first, so the page was "shard 0's first `limit` matches".
+ let mut cands: Vec<(u64, String, usize)> = Vec::new();
let mut total: u64 = 0;
for s in &self.shards {
let g = s.read();
if g.doc_count() == 0 {
continue;
}
- let room = limit.saturating_sub(out.len());
- let (mut hits, t) = g.doc_values_bool_hits(preds, room)?;
- out.append(&mut hits);
+ let (hits, t) = g.doc_values_bool_hits(preds, limit)?;
+ cands.extend(
+ hits.into_iter()
+ .map(|(id, pos)| (g.seq_no_at(pos), id, pos)),
+ );
total += t;
+ Self::narrow_to_page(&mut cands, limit);
}
- Some((out, total))
+ Some((
+ cands.into_iter().map(|(_, id, pos)| (id, pos)).collect(),
+ total,
+ ))
}
/// Columnar per-value counts for one field across all shards, for the
@@ -1597,23 +1682,30 @@ impl ShardedFtsMemtable {
value: &str,
limit: usize,
) -> Option<(Vec<(String, usize)>, u64)> {
- let mut out: Vec<(String, usize)> = Vec::new();
+ let mut cands: Vec<(u64, String, usize)> = Vec::new();
let mut total: u64 = 0;
let mut any_hit = false;
for s in &self.shards {
let g = s.read();
- // Step 1: bound the id clone to the remaining global window;
- // the total is still exact per shard. Mirrors
- // `doc_values_bool_query`.
- let room = limit.saturating_sub(out.len());
- if let Some((mut hits, t)) = g.doc_values_term_query(field, value, room) {
+ // Step 1: bound the id clone per shard; the total is still exact
+ // per shard. Mirrors `doc_values_bool_query`. #191 — the bound
+ // used to be the REMAINING global window, which handed the whole
+ // page to shard 0.
+ if let Some((hits, t)) = g.doc_values_term_query(field, value, limit) {
any_hit = true;
- out.append(&mut hits);
+ cands.extend(
+ hits.into_iter()
+ .map(|(id, pos)| (g.seq_no_at(pos), id, pos)),
+ );
total += t;
+ Self::narrow_to_page(&mut cands, limit);
}
}
if any_hit {
- Some((out, total))
+ Some((
+ cands.into_iter().map(|(_, id, pos)| (id, pos)).collect(),
+ total,
+ ))
} else {
None
}
@@ -1625,20 +1717,28 @@ impl ShardedFtsMemtable {
values: &[String],
limit: usize,
) -> Option<(Vec<(String, usize)>, u64)> {
- let mut out: Vec<(String, usize)> = Vec::new();
+ // #191 — per-shard bound + global `(seq_no, _id)` narrowing, as in
+ // `doc_values_term_query`.
+ let mut cands: Vec<(u64, String, usize)> = Vec::new();
let mut total: u64 = 0;
let mut any_hit = false;
for s in &self.shards {
let g = s.read();
- let room = limit.saturating_sub(out.len());
- if let Some((mut hits, t)) = g.doc_values_terms_query(field, values, room) {
+ if let Some((hits, t)) = g.doc_values_terms_query(field, values, limit) {
any_hit = true;
- out.append(&mut hits);
+ cands.extend(
+ hits.into_iter()
+ .map(|(id, pos)| (g.seq_no_at(pos), id, pos)),
+ );
total += t;
+ Self::narrow_to_page(&mut cands, limit);
}
}
if any_hit {
- Some((out, total))
+ Some((
+ cands.into_iter().map(|(_, id, pos)| (id, pos)).collect(),
+ total,
+ ))
} else {
None
}
@@ -1709,20 +1809,28 @@ impl ShardedFtsMemtable {
lt: Option<f64>,
limit: usize,
) -> Option<(Vec<(String, usize)>, u64)> {
- let mut out: Vec<(String, usize)> = Vec::new();
+ // #191 — per-shard bound + global `(seq_no, _id)` narrowing, as in
+ // `doc_values_term_query`.
+ let mut cands: Vec<(u64, String, usize)> = Vec::new();
let mut total: u64 = 0;
let mut any_hit = false;
for s in &self.shards {
let g = s.read();
- let room = limit.saturating_sub(out.len());
- if let Some((mut hits, t)) = g.doc_values_range_query(field, gte, gt, lte, lt, room) {
+ if let Some((hits, t)) = g.doc_values_range_query(field, gte, gt, lte, lt, limit) {
any_hit = true;
- out.append(&mut hits);
+ cands.extend(
+ hits.into_iter()
+ .map(|(id, pos)| (g.seq_no_at(pos), id, pos)),
+ );
total += t;
+ Self::narrow_to_page(&mut cands, limit);
}
}
if any_hit {
- Some((out, total))
+ Some((
+ cands.into_iter().map(|(_, id, pos)| (id, pos)).collect(),
+ total,
+ ))
} else {
None
}
@@ -2623,18 +2731,27 @@ impl FtsMemtable {
let mut hits: Vec<MemtableHit> = scores
.into_iter()
- .map(|(doc_id, score)| MemtableHit {
- doc_id: doc_id.to_string(),
- score,
+ .map(|(doc_id, score)| {
+ // #191 — carry the arrival order with the hit. `scores` is a
+ // HashMap, so without it the pre-truncation order of an
+ // all-tied hit set is the hash iteration order: the surviving
+ // documents changed from run to run.
+ let seq_no = self
+ .doc_id_index
+ .get(&doc_id)
+ .map_or(u64::MAX, |&pos| self.seq_no_at(pos));
+ MemtableHit {
+ doc_id: doc_id.to_string(),
+ score,
+ seq_no,
+ }
})
.collect();
- // Sort by score descending.
- hits.sort_by(|a, b| {
- b.score
- .partial_cmp(&a.score)
- .unwrap_or(std::cmp::Ordering::Equal)
- });
+ // Sort by the FULL page key (score DESC, seq_no ASC, `_id` ASC) — the
+ // comparator `index.rs:16222-16228` applies to the final page — so a
+ // truncation at `limit` keeps exactly the documents that page would.
+ sort_hits_by_page_key(&mut hits);
hits.truncate(limit);
hits
}
@@ -2664,6 +2781,37 @@ impl FtsMemtable {
self.docs.iter().take(n).map(|e| e.doc_id.clone()).collect()
}
+ /// The WAL `seq_no` of the document at shard-local position `pos`
+ /// (`u64::MAX` when the position is out of range).
+ ///
+ /// #191 — the bounded memtable paths must rank candidates ACROSS shards
+ /// by the same key the final page sort uses, and `seq_no` is that key's
+ /// tie-break. Positions are only comparable within a shard; `seq_no` is
+ /// global.
+ pub fn seq_no_at(&self, pos: usize) -> u64 {
+ self.docs.get(pos).map_or(u64::MAX, |e| e.seq_no)
+ }
+
+ /// `(seq_no, doc_id)` for the first `n` buffered documents, stopping early
+ /// once an entry's `seq_no` exceeds `cutoff`.
+ ///
+ /// #191 — `docs` is append-ordered and `remove` preserves that order, so a
+ /// shard's entries ascend by `seq_no`: once one entry is past the caller's
+ /// running cap-th key, so is every entry after it, and neither needs its
+ /// `doc_id` cloned. That early break is what keeps the per-shard bound
+ /// (which replaced a greedy "fill from shard 0" walk) from multiplying the
+ /// id clones by the shard count.
+ pub fn ranked_ids_up_to(&self, n: usize, cutoff: u64) -> Vec<(u64, String)> {
+ let mut out = Vec::new();
+ for e in self.docs.iter().take(n) {
+ if e.seq_no > cutoff {
+ break;
+ }
+ out.push((e.seq_no, e.doc_id.clone()));
+ }
+ out
+ }
+
/// Resolve a MemEntry's source Value — if `source` is Null but
/// `source_bytes` is non-empty, lazily parse the bytes. This is
/// the M5.11 deferred-parse path used by `insert_raw_bytes_with_seq`.
@@ -2709,6 +2857,14 @@ impl FtsMemtable {
.collect()
}
+ /// `seq_no`-carrying twin of [`Self::all_docs_with_sources_arc`] (#191).
+ pub fn all_docs_with_seq_arc(&self) -> Vec<(u64, String, Arc<Value>)> {
+ self.docs
+ .iter()
+ .map(|e| (e.seq_no, e.doc_id.clone(), Self::resolve_source_arc(e)))
+ .collect()
+ }
+
/// Return the full original source JSON for a document by ID.
/// O(1) doc lookup via `doc_id_index` (maintained by every insert /
/// remove path), with a linear-scan fallback in case an entry is ever
diff --git a/engine/crates/xerj-engine/tests/tied_score_page_order.rs b/engine/crates/xerj-engine/tests/tied_score_page_order.rs
index 7b248ba81..6101dd730 100644
--- a/engine/crates/xerj-engine/tests/tied_score_page_order.rs
+++ b/engine/crates/xerj-engine/tests/tied_score_page_order.rs
@@ -214,21 +214,35 @@ async fn tie_straddling_a_page_boundary_resolves_the_same_way_at_every_size() {
/// The same property with an UNFLUSHED tail — the shape a live index is in
/// between flushes, and the one a paginating client hits most often.
///
-/// The corpus is deliberately larger than the collector's 256-hit floor
-/// (`materialisation_limit = (from + size + 100).max(256)`; the `from + size`
-/// narrowing applies only to an EMPTY memtable, so a mixed fixture always
-/// pays the floor plus 100 hits of slack). A smaller mixed fixture proves
-/// nothing at all: the whole corpus fits under the cap, the bounded collector
-/// never truncates, and every page agrees trivially.
+/// Sizing this fixture takes two conditions at once, and an earlier revision
+/// of this test met neither. With `materialisation_limit = (from + size +
+/// 100).max(256)` and the flushed documents arriving FIRST (so they own the
+/// low `seq_no`s and the head of every page):
///
-/// Honest scope: unlike the two tests above, this one PASSED on the pre-fix
-/// engine in the runs we measured — the 100-hit slack means truncation only
-/// ever reached documents past the prefixes asserted here, so the pre-fix
-/// walk got away with dropping whichever segment it reached last. It earns
-/// its place as a REGRESSION guard, not a reproducer: the fix changes both
-/// the segment walk order and the per-segment headroom, and the memtable
-/// (which seeds the collector past its cap before the first segment is even
-/// opened) is where a mistake in either would surface first.
+/// 1. the UNFLUSHED batch must be larger than the cap, or the memtable hands
+/// up every buffered hit and its bound is never exercised; and
+/// 2. some asserted page position must actually LAND on a memtable
+/// document — i.e. `size` must exceed the flushed count — while (1) still
+/// holds, which bounds `flushed < size < unflushed - 100`.
+///
+/// 40 flushed + 300 unflushed satisfies both across `size` 41…199. The
+/// original 320 flushed + 40 unflushed satisfied neither: 40 buffered hits
+/// never reached a 256-hit cap, so the memtable collector could not truncate,
+/// and every page position asserted (`size` ≤ 359, against 320 flushed
+/// documents) was answered from segments. That test passed before the fix and
+/// after it, and would have kept passing however broken the memtable path
+/// became. Measured on this fixture at the pre-repair commit, `size` 60, 100
+/// and 150 each returned a non-prefix page for all three shapes below.
+///
+/// `constant_score` is deliberately NOT one of the shapes here, and that is a
+/// known gap rather than an oversight: on a MIXED corpus its bounded page
+/// contains only memtable documents (`size:1` returns `mem0000` where the full
+/// page starts `seg0000`) because the segment walk is skipped once the
+/// collector is already full. That reproduces identically before and after
+/// this change — it is a separate, pre-existing defect in the segment-side
+/// early-out, not the memtable bound under test here — and it is why this PR
+/// says `Refs #191` rather than `Fixes #191`. The memtable-only test below
+/// does cover `constant_score`, which is the path this change fixes.
#[tokio::test]
async fn tied_scores_page_the_same_way_with_an_unflushed_memtable() {
let dir = TempDir::new().unwrap();
@@ -237,8 +251,8 @@ async fn tied_scores_page_the_same_way_with_an_unflushed_memtable() {
let idx = engine.get_index("mixed").unwrap();
let mut inserted = Vec::new();
- for batch in 0..4 {
- for i in 0..80 {
+ for batch in 0..2 {
+ for i in 0..20u32 {
let id = format!("seg{batch}{i:03}");
idx.index_document(
Some(id.clone()),
@@ -250,8 +264,10 @@ async fn tied_scores_page_the_same_way_with_an_unflushed_memtable() {
}
idx.flush().await.unwrap();
}
- // Deliberately NOT flushed — these stay in the memtable.
- for i in 0..40 {
+ // Deliberately NOT flushed — these stay in the memtable, and there are
+ // more of them than any cap the sizes below imply, so the memtable-side
+ // bound is the thing under test.
+ for i in 0..300 {
let id = format!("mem{i:03}");
idx.index_document(
Some(id.clone()),
@@ -261,7 +277,7 @@ async fn tied_scores_page_the_same_way_with_an_unflushed_memtable() {
.unwrap();
inserted.push(id);
}
- let total = inserted.len() as u64; // 360 > the 256 floor
+ let total = inserted.len() as u64; // 340: 40 flushed + 300 unflushed
for (label, q) in [
("match", json!({"match": {"body": "listpack"}})),
@@ -276,14 +292,120 @@ async fn tied_scores_page_the_same_way_with_an_unflushed_memtable() {
"{label}: an all-tied page must come back in arrival order, \
segment documents before memtable ones"
);
- // Sizes on both sides of the 256 floor.
- for size in [1usize, 5, 50, 255, 256, 257, 300, 359] {
+ // Every one of these implies a cap below 300, so the memtable is
+ // always truncating; the ones past 40 are the ones whose page actually
+ // contains buffered documents.
+ for size in [1usize, 5, 41, 60, 100, 150, 199] {
+ let p = idx.search(&req(0, size, &q)).await.unwrap();
+ assert_eq!(
+ page_ids(&p.hits),
+ full_ids[..size],
+ "{label}: size:{size} page disagrees with the full materialisation"
+ );
+ }
+ }
+}
+
+/// #191's most natural reproduction, and the one the PR originally shipped
+/// without: index N identical documents and page them BEFORE the flush.
+///
+/// Nothing here has been written to a segment, so every collector decision is
+/// made on the memtable side. That side bounds its materialisation twice over
+/// — the sharded memtable caps each shard's contribution, and `admit_hit!`
+/// caps the merged result — and neither bound used to rank candidates by the
+/// page key. A `ShardedFtsMemtable` holds 16 independent shards, a document
+/// lands in one by id hash (a whole bulk batch by its FIRST id's hash), and
+/// the query path walks them in INDEX order while filling a global budget.
+/// So the page was "the tied documents that happen to live in the
+/// lowest-numbered shards", which is neither arrival order nor stable.
+///
+/// Measured pre-fix, release, 600 byte-identical documents (every score bit
+/// pattern `1065353216`, an exact tie), for `match`, `term`, `match_all` AND
+/// `constant_score` alike:
+///
+/// ```text
+/// size:5 → ["m0000", "m0001", "m0004", "m0005", "m0008"]
+/// size:1000 → ["m0000", "m0001", "m0002", "m0003", "m0004"], …
+/// ```
+///
+/// Each shape reaches a different memtable collector, which is why all four
+/// are asserted: `match` takes the scored FTS merge, `term` the columnar
+/// doc-values walk, `match_all` the bounded id list, and `constant_score` the
+/// brute per-document scan.
+#[tokio::test]
+async fn tied_scores_page_the_same_way_with_no_flush_at_all() {
+ let dir = TempDir::new().unwrap();
+ let engine = make_engine(&dir);
+ engine.create_index("memonly", Schema::empty()).unwrap();
+ let idx = engine.get_index("memonly").unwrap();
+
+ // Comfortably past the 256-hit floor. `size:300` implies a 400-hit cap
+ // and so still truncates; `size:599` implies 699 and does not, which is
+ // why the full page below is a complete materialisation to compare
+ // against.
+ let mut inserted = Vec::new();
+ for i in 0..600 {
+ let id = format!("m{i:04}");
+ idx.index_document(
+ Some(id.clone()),
+ json!({"body": "listpack encoding", "kind": "same"}),
+ )
+ .await
+ .unwrap();
+ inserted.push(id);
+ }
+
+ for (label, q) in [
+ ("match", json!({"match": {"body": "listpack"}})),
+ ("term", json!({"term": {"kind": "same"}})),
+ ("match_all", json!({"match_all": {}})),
+ (
+ "constant_score",
+ json!({"constant_score": {"filter": {"match_all": {}}}}),
+ ),
+ ] {
+ let full = idx.search(&req(0, 1000, &q)).await.unwrap();
+ let full_ids = page_ids(&full.hits);
+ assert_eq!(full.total.value, 600, "{label}: every doc matches");
+
+ // The tie really is exact — otherwise the test proves nothing.
+ let scores: Vec<f32> = full.hits.iter().map(|h| h.score).collect();
+ assert!(
+ scores.windows(2).all(|w| w[0].to_bits() == w[1].to_bits()),
+ "{label}: fixture must produce an EXACT tie, got {:?}",
+ &scores[..5]
+ );
+ assert_eq!(
+ full_ids, inserted,
+ "{label}: an all-tied memtable page must come back in arrival order"
+ );
+
+ // Sizes on both sides of the 256 floor. Measured pre-fix, `size` 5,
+ // 50 and 300 each returned a page drawn from the low-numbered shards
+ // for all four shapes; `size:1` happened to survive, because the
+ // globally-first document also lived in a shard the truncated walk
+ // reached.
+ for size in [1usize, 2, 5, 50, 255, 256, 257, 300, 599] {
let p = idx.search(&req(0, size, &q)).await.unwrap();
assert_eq!(
page_ids(&p.hits),
full_ids[..size],
"{label}: size:{size} page disagrees with the full materialisation"
);
+ assert_eq!(
+ p.total.value, 600,
+ "{label}: size:{size} total must stay exact"
+ );
+ }
+
+ // Paging one hit at a time reproduces the same order.
+ for from in [0usize, 1, 254, 255, 256, 300] {
+ let p = idx.search(&req(from, 1, &q)).await.unwrap();
+ assert_eq!(
+ page_ids(&p.hits),
+ full_ids[from..from + 1],
+ "{label}: from:{from} size:1 disagrees with the full materialisation"
+ );
}
}
}