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.
Rust agent-memoryai-agentsbm25claude-codeclicode-searchcursordatabaseelasticsearchfull-text-searchhybrid-searchjsonllocal-firstmcpmcp-servermodel-context-protocolragrustsearch-enginevector-search
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.rsindex 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.rsindex 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