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.

perf(read): eliminate range(@timestamp) 340ms cliff + columnar rare_terms/significant_terms — all exact vs ES

xerj-org93e82b6f1c1a
diff --git a/engine/crates/xerj-engine/src/fast_aggs.rs b/engine/crates/xerj-engine/src/fast_aggs.rs
index 856133c9f..816d55ca1 100644
--- a/engine/crates/xerj-engine/src/fast_aggs.rs
+++ b/engine/crates/xerj-engine/src/fast_aggs.rs
@@ -1081,6 +1081,8 @@ impl<'a> FastCtx<'a> {
}
"auto_date_histogram" => self.exec_auto_date_histogram(params, sub),
"terms" => self.exec_terms(params, sub),
+ "rare_terms" => self.exec_rare_terms(params, sub),
+ "significant_terms" => self.exec_significant_terms(params, sub),
"cardinality" => self.exec_cardinality(params, sub),
"range" => self.exec_range(params, sub),
"date_range" => self.exec_date_range(params, sub),
@@ -2591,6 +2593,160 @@ impl<'a> FastCtx<'a> {
}))
}
+ // ── rare_terms ───────────────────────────────────────────────────────
+
+ /// Columnar `rare_terms`: `terms` restricted to the low-frequency tail
+ /// (buckets whose GLOBAL `doc_count <= max_doc_count`, default 1).
+ ///
+ /// Brute (`run_rare_terms`) JSON-walks every doc to build `term → doc`
+ /// indices, then keeps the rare tail — O(N) (≈1 s / 100 k docs). This arm
+ /// reuses the exact per-term counting of `exec_terms`' whole-segment
+ /// shortcut (segments' `per_ord_count` + the memtable columnar folder), then
+ /// applies the same rare filter and the same `count asc, key asc` ordering
+ /// and typed-key bucket rendering the brute path uses — so the result is
+ /// byte-identical, just O(distinct terms) instead of O(N).
+ ///
+ /// Deliberately narrow — bails (`None` → exact brute) on anything the
+ /// counting/rendering can't reproduce exactly: sub-aggs (need per-bucket
+ /// docs), `include`/`exclude`/`missing`/`precision` (params_only), a
+ /// non-keyword field (numeric/bool/date term-key subtleties render
+ /// differently), a dotted field, or a memtable shape the columnar folder
+ /// can't count (arrays / `_doc_count` weights). A top-level query filter is
+ /// already gated out by `exec_agg` (rare_terms is not in its allowlist).
+ fn exec_rare_terms(&self, params: &Value, sub: Option<&Value>) -> Option<Value> {
+ if sub.is_some() {
+ return None;
+ }
+ if !params_only(params, &["field", "max_doc_count"]) {
+ return None;
+ }
+ // `exec_agg` only reaches this arm when there is no top-level query
+ // filter (rare_terms is not in the filtered-executor allowlist), so the
+ // corpus is the whole index — matching `run_rare_terms(docs=all_docs)`.
+ debug_assert!(self.top_filter.is_none());
+ let field = params.get("field").and_then(Value::as_str)?;
+ if field.contains('.') {
+ return None;
+ }
+ let max_doc_count = params
+ .get("max_doc_count")
+ .and_then(Value::as_u64)
+ .unwrap_or(1);
+ // Keyword-only: a numeric/bool/date-numeric term column would render its
+ // keys differently from the brute string path.
+ match self.seg_field_kind(field) {
+ Ok(Some(ColKind::Keyword)) | Ok(None) => {}
+ _ => return None,
+ }
+
+ // Whole-corpus per-term counts (identical to `exec_terms`' `!has_row_work`
+ // shortcut): segments' `per_ord_count` + the memtable columnar folder.
+ let mut counts: HashMap<String, u64> = HashMap::new();
+ for seg in &self.segs {
+ match seg.cols.get(field) {
+ Some(Column::Keyword(k)) => {
+ for (ord, &cnt) in k.per_ord_count.iter().enumerate() {
+ // Skip empty-string values — `run_rare_terms` drops them
+ // (`extract_field_values` → `if v.is_empty() continue`).
+ if cnt > 0 && !k.terms[ord].is_empty() {
+ *counts.entry(k.terms[ord].clone()).or_default() += cnt as u64;
+ }
+ }
+ }
+ None => {} // field absent in this segment → no terms
+ _ => return None, // non-keyword column for a keyword field → bail
+ }
+ }
+ match self.idx.memtable.terms_counts_columnar(field) {
+ Some((mem_counts, _missing)) => {
+ for (term, cnt) in mem_counts {
+ if cnt > 0 && !term.is_empty() {
+ *counts.entry(term).or_default() += cnt;
+ }
+ }
+ }
+ // Array-valued field / `_doc_count` weights the columnar folder
+ // can't reproduce → exact brute.
+ None => return None,
+ }
+
+ // Rare filter + brute ordering (`count asc, key asc`, no truncation —
+ // rare_terms has no `size`), mirroring `run_rare_terms`.
+ let mut entries: Vec<(String, u64)> = counts
+ .into_iter()
+ .filter(|(_, c)| *c <= max_doc_count)
+ .collect();
+ entries.sort_by(|a, b| a.1.cmp(&b.1).then_with(|| a.0.cmp(&b.0)));
+
+ let buckets: Vec<Value> = entries
+ .into_iter()
+ .map(|(key, count)| {
+ let (typed_key, key_as_string) = typed_term_key(&key);
+ let mut b = Map::new();
+ b.insert("key".to_string(), typed_key);
+ if let Some(kas) = key_as_string {
+ b.insert("key_as_string".to_string(), json!(kas));
+ }
+ b.insert("doc_count".to_string(), json!(count));
+ Value::Object(b)
+ })
+ .collect();
+
+ Some(json!({ "buckets": buckets }))
+ }
+
+ // ── significant_terms (degenerate no-query case only) ─────────────────
+
+ /// Columnar `significant_terms` for the ONE case that is provably an empty
+ /// result: no top-level query and no `background_filter`, so the foreground
+ /// set equals the background set (the whole index). Every term then has
+ /// `fg_freq == bg_freq`, so the JLH significance score is exactly `0.0` for
+ /// all terms, and with the default `min_doc_count >= 2` (no threshold
+ /// bypass) every term is dropped — brute (`run_significant_terms`) returns
+ /// `{doc_count: N, bg_count: N, buckets: []}`. This arm returns the same in
+ /// O(1)+segment-count instead of the O(N) double JSON walk (≈1 s / 100 k).
+ ///
+ /// Everything else bails to exact brute (`None`): a `background_filter`
+ /// (foreground != background), `min_doc_count <= 1` (threshold bypass keeps
+ /// score-0 terms in a HashMap-order-dependent, non-reproducible order),
+ /// sub-aggs, or any param outside `field`/`size`/`min_doc_count`. A
+ /// top-level query filter is already gated out by `exec_agg`
+ /// (significant_terms is not in its allowlist), which is exactly what makes
+ /// foreground == background here.
+ fn exec_significant_terms(&self, params: &Value, sub: Option<&Value>) -> Option<Value> {
+ if sub.is_some() {
+ return None;
+ }
+ if !params_only(params, &["field", "size", "min_doc_count"]) {
+ return None; // background_filter / include / exclude / … → brute
+ }
+ debug_assert!(self.top_filter.is_none());
+ // Field must exist as a real agg field (keyword or numeric). `None`
+ // (fully unmapped) still yields empty buckets in brute, but keep the arm
+ // to the mapped case so `doc_count`/`bg_count` are unambiguous.
+ params.get("field").and_then(Value::as_str)?;
+ // Default ES `min_doc_count` is 3; only `<= 1` bypasses the score-0
+ // filter (and produces non-reproducible ordering) → brute.
+ let min_doc_count = params
+ .get("min_doc_count")
+ .and_then(Value::as_u64)
+ .unwrap_or(3);
+ if min_doc_count <= 1 {
+ return None;
+ }
+ // Whole-corpus live doc count = brute's `result_docs.len()` ==
+ // `all_docs.len()` (no deletes on the fast path; `run_significant_terms`
+ // counts docs, unweighted). Foreground == background ⇒ every term scores
+ // 0.0 ⇒ empty buckets.
+ let total: u64 = self.segs.iter().map(|s| s.docs as u64).sum::<u64>()
+ + self.idx.memtable.doc_count() as u64;
+ Some(json!({
+ "doc_count": total,
+ "bg_count": total,
+ "buckets": [],
+ }))
+ }
+
// ── range (numeric) ──────────────────────────────────────────────────
fn exec_range(&self, params: &Value, sub: Option<&Value>) -> Option<Value> {
diff --git a/engine/crates/xerj-engine/src/index.rs b/engine/crates/xerj-engine/src/index.rs
index c94a13fac..00f8e6e3c 100644
--- a/engine/crates/xerj-engine/src/index.rs
+++ b/engine/crates/xerj-engine/src/index.rs
@@ -8695,11 +8695,34 @@ impl Index {
continue;
}
let cols = self.dv_columns_for(&segments_dir, &meta.id)?;
- let col = match cols.get(field_str) {
- Some(xerj_storage::doc_values::Column::Numeric(n)) => n,
- _ => return None, // abandon — no numeric column
- };
- seg_matches = seg_matches.saturating_add(col.range_count(lo, hi, lo_incl, hi_incl));
+ match cols.get(field_str) {
+ Some(xerj_storage::doc_values::Column::Numeric(n)) => {
+ seg_matches = seg_matches
+ .saturating_add(n.range_count(lo, hi, lo_incl, hi_incl));
+ }
+ // DATE fields (e.g. `@timestamp`) are date-shaped Keyword dv
+ // columns, not Numeric — without this arm the shortcut
+ // abandoned and the stored scan tallied EVERY matching doc
+ // (O(N), the 340 ms cliff). The sorted epoch shadow gives the
+ // EXACT count via two bisects (same encoding + bounds
+ // derivation as the range dv prefilter). `None` from the
+ // shadow (nulls / ineligible column) abandons → full scan,
+ // still exact.
+ Some(xerj_storage::doc_values::Column::Keyword(_)) => {
+ let shadow = self.sorted_shadow_for(
+ &segments_dir,
+ &meta.id,
+ field_str,
+ meta.doc_count,
+ )?;
+ let (slo, slo_incl, shi, shi_incl) =
+ shadow_range_bounds(gte.as_ref(), gt.as_ref(), lte.as_ref(), lt.as_ref())?;
+ seg_matches = seg_matches.saturating_add(shadow_range_count(
+ &shadow, slo, shi, slo_incl, shi_incl,
+ ));
+ }
+ None => return None, // abandon — field absent in this segment
+ }
}
// Memtable side — abandon the shortcut if the memtable has
@@ -9119,17 +9142,21 @@ impl Index {
_ => None,
}
};
- let gte = parse(gte)?;
- let gt = parse(gt)?;
- let lte = parse(lte)?;
- let lt = parse(lt)?;
-
- let (lo, lo_incl) = match (gte, gt) {
+ // Numeric-scale bounds (parse_date_ms → epoch-ms f64) for the
+ // `Column::Numeric` arm. The ORIGINAL `gte/gt/lte/lt` `&Value` params
+ // are left un-shadowed so the date-shadow fallback below can re-derive
+ // its bounds on the shadow's own epoch scale.
+ let gte_n = parse(gte)?;
+ let gt_n = parse(gt)?;
+ let lte_n = parse(lte)?;
+ let lt_n = parse(lt)?;
+
+ let (lo, lo_incl) = match (gte_n, gt_n) {
(Some(v), _) => (v, true),
(None, Some(v)) => (v, false),
(None, None) => (f64::NEG_INFINITY, true),
};
- let (hi, hi_incl) = match (lte, lt) {
+ let (hi, hi_incl) = match (lte_n, lt_n) {
(Some(v), _) => (v, true),
(None, Some(v)) => (v, false),
(None, None) => (f64::INFINITY, true),
@@ -9162,10 +9189,32 @@ impl Index {
}
let cols = self.dv_columns_for(segments_dir, segment_id)?;
- let Some(Column::Numeric(n)) = cols.get(field) else {
- return None;
+ let matching: Vec<u32> = match cols.get(field) {
+ Some(Column::Numeric(n)) => n.range_doc_ids(lo, hi, lo_incl, hi_incl),
+ // DATE fields (e.g. `@timestamp`) are stored as date-shaped Keyword
+ // dv columns, NOT `Column::Numeric`, so the arm above missed and the
+ // whole query fell to a full O(N) stored-section scan. Their sorted
+ // epoch shadow uses the SAME `(f64-bits-as-i64, pos)` encoding as
+ // `NumericColumn.sorted` (sorted by f64 value ascending, one entry
+ // per segment doc, built by `build_sort_shadow` only when the column
+ // is dense with no nulls), so the identical O(log n + |matches|)
+ // bisect applies. Bounds are re-derived on the shadow's OWN epoch
+ // scale via `sort_date_normalize` — the exact fn that produced the
+ // shadow keys — so bound and key compare on the same scale (exact
+ // for the consistent-precision date fields every real ES mapping
+ // uses). The stored scan re-tests the full query per admitted
+ // position (`doc_matches_query`), so a superset is always safe; an
+ // unparseable bound or a column with null/absent values (shadow →
+ // `None`) → full scan, still correct.
+ Some(Column::Keyword(k)) => {
+ let seg_doc_count = k.doc_count as u64;
+ let shadow =
+ self.sorted_shadow_for(segments_dir, segment_id, field, seg_doc_count)?;
+ let (slo, slo_incl, shi, shi_incl) = shadow_range_bounds(gte, gt, lte, lt)?;
+ shadow_range_positions(&shadow, slo, shi, slo_incl, shi_incl)
+ }
+ None => return None,
};
- let matching = n.range_doc_ids(lo, hi, lo_incl, hi_incl);
let built: Arc<HashSet<u32>> = Arc::new(matching.into_iter().collect());
if self.range_prefilter_cache.len() >= 32 {
self.range_prefilter_cache.clear();
@@ -16164,6 +16213,113 @@ fn build_sort_shadow(
}
}
+/// Re-derive a `Range` query's `[lo,hi]` bounds on the sort-shadow's epoch
+/// scale for the date-shaped-Keyword fallback in `build_range_prefilter_cached`.
+///
+/// The shadow's per-doc key is `sort_date_normalize(value).as_f64()`, so a
+/// string bound is normalised with the SAME `sort_date_normalize` function —
+/// bound and key are then byte-identical functions of their date string, and
+/// the bisect is exact for any consistent-precision date field. A numeric bound
+/// is taken verbatim (a raw epoch against an epoch column). Returns `None` for a
+/// bound shape neither date-parseable nor numeric → caller bails to the full
+/// scan (still correct).
+fn shadow_range_bounds(
+ gte: Option<&Value>,
+ gt: Option<&Value>,
+ lte: Option<&Value>,
+ lt: Option<&Value>,
+) -> Option<(f64, bool, f64, bool)> {
+ let key = |v: Option<&Value>| -> Option<Option<f64>> {
+ match v {
+ None => Some(None),
+ Some(Value::Number(n)) => Some(n.as_f64()),
+ Some(Value::String(s)) => {
+ if let Some(f) = sort_date_normalize(s).and_then(|x| x.as_f64()) {
+ Some(Some(f))
+ } else if let Ok(f) = s.parse::<f64>() {
+ Some(Some(f))
+ } else {
+ None // unparseable bound → bail to brute
+ }
+ }
+ _ => None,
+ }
+ };
+ let gte = key(gte)?;
+ let gt = key(gt)?;
+ let lte = key(lte)?;
+ let lt = key(lt)?;
+ let (lo, lo_incl) = match (gte, gt) {
+ (Some(v), _) => (v, true),
+ (None, Some(v)) => (v, false),
+ (None, None) => (f64::NEG_INFINITY, true),
+ };
+ let (hi, hi_incl) = match (lte, lt) {
+ (Some(v), _) => (v, true),
+ (None, Some(v)) => (v, false),
+ (None, None) => (f64::INFINITY, true),
+ };
+ Some((lo, lo_incl, hi, hi_incl))
+}
+
+/// Two binary searches over a sort shadow (`(f64-bits-as-i64, pos)` sorted by
+/// f64 value ascending) collecting the positions whose key falls in the range —
+/// the exact bisect `NumericColumn::range_doc_ids` performs, applied to the
+/// date-shaped-Keyword epoch shadow.
+fn shadow_range_positions(
+ shadow: &[(i64, u32)],
+ lo: f64,
+ hi: f64,
+ lo_incl: bool,
+ hi_incl: bool,
+) -> Vec<u32> {
+ if shadow.is_empty() {
+ return Vec::new();
+ }
+ let lo_idx = if lo_incl {
+ shadow.partition_point(|(v, _)| f64::from_bits(*v as u64) < lo)
+ } else {
+ shadow.partition_point(|(v, _)| f64::from_bits(*v as u64) <= lo)
+ };
+ let hi_idx = if hi_incl {
+ shadow.partition_point(|(v, _)| f64::from_bits(*v as u64) <= hi)
+ } else {
+ shadow.partition_point(|(v, _)| f64::from_bits(*v as u64) < hi)
+ };
+ if lo_idx >= hi_idx {
+ return Vec::new();
+ }
+ shadow[lo_idx..hi_idx].iter().map(|(_, d)| *d).collect()
+}
+
+/// Count-only twin of `shadow_range_positions` — the exact match count via two
+/// `partition_point`s over the date-shaped-Keyword epoch shadow, mirroring
+/// `NumericColumn::range_count`. Used as the authoritative `shortcut_count` for
+/// a `range(<date field>)` so the stored scan can early-break at
+/// `size` instead of tallying every matching doc.
+fn shadow_range_count(
+ shadow: &[(i64, u32)],
+ lo: f64,
+ hi: f64,
+ lo_incl: bool,
+ hi_incl: bool,
+) -> u64 {
+ if shadow.is_empty() {
+ return 0;
+ }
+ let lo_idx = if lo_incl {
+ shadow.partition_point(|(v, _)| f64::from_bits(*v as u64) < lo)
+ } else {
+ shadow.partition_point(|(v, _)| f64::from_bits(*v as u64) <= lo)
+ };
+ let hi_idx = if hi_incl {
+ shadow.partition_point(|(v, _)| f64::from_bits(*v as u64) <= hi)
+ } else {
+ shadow.partition_point(|(v, _)| f64::from_bits(*v as u64) < hi)
+ };
+ (hi_idx.saturating_sub(lo_idx)) as u64
+}
+
/// The read-path caches a freshly-published segment must be warm in so
/// its first queries don't pay cold-start costs inside their own latency.
/// Bundled so the flush path (a free fn without `&Index`) can carry ONE