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(xerj-engine): columnar fast path for exists-in-filter-conjunction

xerj-org2f052d9a05d5
diff --git a/engine/crates/xerj-autoindex/src/sync_executor.rs b/engine/crates/xerj-autoindex/src/sync_executor.rs
index 93c93c031..da676d67a 100644
--- a/engine/crates/xerj-autoindex/src/sync_executor.rs
+++ b/engine/crates/xerj-autoindex/src/sync_executor.rs
@@ -659,7 +659,14 @@ impl<'a> EsSyncBackend<'a> {
&serde_json::json!({
"size": 0,
"track_total_hits": true,
- "query": {"bool": {"must": [
+ // Filter context, term first: the engine's columnar
+ // filter executor checks leaves in order, so the
+ // ax_file term narrows the walk before the `exists`
+ // leaf parses any stored source. In scoring context
+ // (`must`) this query source-scanned every row —
+ // 9.6s per call on a 91k-doc segment, one call per
+ // changed group at finalize (#1183).
+ "query": {"bool": {"filter": [
{"term": {"ax_file": &group.content_id}},
{"exists": {"field": field}}
]}}
diff --git a/engine/crates/xerj-engine/src/index.rs b/engine/crates/xerj-engine/src/index.rs
index a0db61c1e..9fa99abcd 100644
--- a/engine/crates/xerj-engine/src/index.rs
+++ b/engine/crates/xerj-engine/src/index.rs
@@ -29003,6 +29003,9 @@ impl Index {
return None;
}
}
+ // No doc-values column, no stats: per-row presence is
+ // resolved from the stored slices in the walk below.
+ ScoredFilterLeaf::SourceExists { .. } => {}
}
}
}
@@ -29298,6 +29301,11 @@ impl Index {
}
};
let constant_plan: bool = !any_ghosts
+ // Source-backed `exists` leaves have no closed-form count —
+ // their per-segment total is only knowable row by row.
+ && !filters
+ .iter()
+ .any(|f| matches!(f, ScoredFilterLeaf::SourceExists { .. }))
&& match plan {
ScoredPlan::Filtered {
filter, must_not, ..
@@ -29555,6 +29563,15 @@ impl Index {
max_inc: *max_inc,
});
}
+ ScoredFilterLeaf::SourceExists { field } => {
+ // Cache-backed stored slices for this segment; the
+ // `?` bails the whole columnar path (brute answers).
+ let slices = self.stored_slices_for(meta.id.as_str(), meta.doc_count)?;
+ fev.push(FilterEval::Source {
+ field: field.clone(),
+ slices,
+ });
+ }
}
}
let doc_count = meta.doc_count as u32;
@@ -51684,6 +51701,14 @@ enum FilterEval<'a> {
min_inc: bool,
max_inc: bool,
},
+ /// `exists` on a column-less (text / semantic_text) field: per-row
+ /// presence from the segment's cached stored slices, using the SAME
+ /// `get_field_value` + `value_present` predicate as the brute scan.
+ /// Owned `Resident` so the eval outlives the segment iteration.
+ Source {
+ field: String,
+ slices: Resident<StoredSlices>,
+ },
}
impl FilterEval<'_> {
#[inline]
@@ -51713,6 +51738,24 @@ impl FilterEval<'_> {
(if *min_inc { v >= *min } else { v > *min })
&& (if *max_inc { v <= *max } else { v < *max })
}
+ FilterEval::Source { field, slices } => {
+ // The brute path's exact `exists` arm (source-scanned):
+ // value present and non-null. Reached only on rows that
+ // passed the cheaper conjuncts ahead of this leaf in the
+ // same row walk, so a `term` + `exists` conjunction pays
+ // one stored-slice parse per TERM survivor, not per row.
+ let Some(&(start, end)) = slices.offsets.get(row as usize) else {
+ return false;
+ };
+ let Some(slice) = slices.bytes.get(start as usize..end as usize) else {
+ return false;
+ };
+ let Ok(doc) = serde_json::from_slice::<Value>(slice) else {
+ return false;
+ };
+ let source = doc.get("_source").unwrap_or(&doc);
+ get_field_value(source, field).is_some_and(|v| value_present(&v))
+ }
}
}
@@ -51755,6 +51798,13 @@ impl FilterEval<'_> {
});
(hi - lo) as u64
}
+ // No closed form — presence is only knowable per row from the
+ // stored source. The `constant_plan` gate excludes any plan
+ // carrying a SourceExists leaf, so this arm is unreachable
+ // from the lane that calls `count()`; a plain walk tallies.
+ FilterEval::Source { .. } => {
+ unreachable!("source-backed exists has no closed-form count")
+ }
}
}
}
@@ -51970,6 +52020,22 @@ enum ScoredFilterLeaf {
min_inc: bool,
max_inc: bool,
},
+ /// `exists` on a field with NO doc-values column (text /
+ /// semantic_text): per-row presence is only observable in the stored
+ /// source. Evaluated from the segment's cached stored slices — the
+ /// SAME `get_field_value` + `value_present` predicate the brute scan
+ /// applies, so the hit set cannot drift — but only reached on rows
+ /// that already passed every cheaper conjunct in the same loop (each
+ /// row walk short-circuits in fev order), which is what turns
+ /// `bool.filter: [term, exists]` from a whole-index source scan into
+ /// a term-column walk plus a handful of source parses. #1183's
+ /// finalize-verify query (`term: ax_file` + `exists: <semantic
+ /// field>`) measured took=9638ms / 0 hits on a 91k-doc segment
+ /// because `exists` in a bool forced the brute path; this leaf makes
+ /// it columnar. Keyword/numeric `exists` does NOT come here — those
+ /// lower to the empty-prefix dictionary range / unbounded window
+ /// above and never touch the source.
+ SourceExists { field: String },
}
/// The exact query shape the scored-family columnar executor serves.
@@ -52373,6 +52439,42 @@ fn scored_fast_plan(
max_inc,
})
}
+ // `exists` in FILTER context — the same lowering the
+ // standalone root shapes use (empty-prefix dictionary range
+ // for keyword, unbounded window for numeric/boolean; null
+ // rows are excluded by `FilterEval`'s null check, matching
+ // `exists` semantics). Fields with no column (text /
+ // semantic_text) become the source-backed leaf: exact via
+ // the same stored-source predicate the brute path applies,
+ // and cheap whenever a column-backed conjunct runs first in
+ // the same filter list. Meta fields keep the brute path —
+ // their `exists` semantics (`_id`/`_index`/… always true,
+ // `_routing` from the doc envelope) are not source-derived.
+ QueryNode::Exists { field } if fs.kw.contains(field) => {
+ Some(ScoredFilterLeaf::KeywordPrefix {
+ field: field.clone(),
+ prefix: String::new(),
+ })
+ }
+ QueryNode::Exists { field } if fs.num.contains(field) || fs.boolean.contains(field) => {
+ Some(ScoredFilterLeaf::NumericWindow {
+ field: field.clone(),
+ min: f64::NEG_INFINITY,
+ max: f64::INFINITY,
+ min_inc: true,
+ max_inc: true,
+ })
+ }
+ QueryNode::Exists { field }
+ if !matches!(
+ field.as_str(),
+ "_id" | "_index" | "_seq_no" | "_version" | "_primary_term" | "_routing"
+ ) =>
+ {
+ Some(ScoredFilterLeaf::SourceExists {
+ field: field.clone(),
+ })
+ }
_ => None,
}
}
diff --git a/engine/crates/xerj-engine/tests/exists_filter_conjunction.rs b/engine/crates/xerj-engine/tests/exists_filter_conjunction.rs
new file mode 100644
index 000000000..cabeaa9c5
--- /dev/null
+++ b/engine/crates/xerj-engine/tests/exists_filter_conjunction.rs
@@ -0,0 +1,394 @@
+//! `exists` inside a filter-context `bool` conjunction must answer from the
+//! columnar filter executor — not by source-scanning every row.
+//!
+//! #1183's finalize-verify issues one `bool: [term: ax_file, exists: <field>]`
+//! count per changed group. In scoring context (`must`) that query fell to
+//! the brute path and source-scanned the whole index per call: measured
+//! took=9638ms for 0 hits on a 91k-doc segment of the standing xerj-search
+//! rebuild. The fix lowers filter-context `exists` to the columnar path —
+//! keyword fields via the empty-prefix dictionary range, numeric/boolean via
+//! the unbounded window, and column-less fields (text / semantic_text) via a
+//! source-backed leaf that runs AFTER the cheap conjuncts in the same row
+//! walk (so the term narrows first).
+//!
+//! Every count below is asserted against a hand-computed expectation from
+//! the seed (not against the brute path), and the scoring-context `must`
+//! variant — still served by the brute path — must report the SAME total:
+//! cross-path agreement is the regression guard for drift between the
+//! columnar leaf and `doc_matches_query`'s `exists` arm.
+
+use serde_json::{json, Value};
+use tempfile::TempDir;
+use xerj_common::config::Config;
+use xerj_common::types::{FieldConfig, FieldType, Schema};
+use xerj_engine::{Engine, Index};
+use xerj_query::parse_request;
+
+fn make_engine(dir: &TempDir) -> Engine {
+ let mut config = Config::default();
+ config.server.data_dir = dir.path().to_str().unwrap().to_string();
+ Engine::new(config).expect("engine::new")
+}
+
+/// 90 docs over three `ax_file` groups, exercising every `exists` edge in
+/// `value_present`: absent key, explicit null, empty string (PRESENT), and
+/// an array with a non-null element (PRESENT). `note` is a second
+/// column-less (text) field with a different presence pattern so a
+/// conjunction can discriminate; `tag` (keyword) and `num` (long) carry
+/// nulls to pin the column-backed lowers.
+///
+/// Flushed: the columnar executor serves fully-flushed data only — an
+/// unflushed population is covered by `memtable_resident_docs_match`.
+async fn seed(name: &str) -> (TempDir, std::sync::Arc<Index>) {
+ let dir = TempDir::new().unwrap();
+ let engine = make_engine(&dir);
+ let mut schema = Schema::empty();
+ schema
+ .fields
+ .push(FieldConfig::new("ax_file", FieldType::Keyword));
+ schema
+ .fields
+ .push(FieldConfig::new("body", FieldType::Text));
+ schema
+ .fields
+ .push(FieldConfig::new("note", FieldType::Text));
+ schema
+ .fields
+ .push(FieldConfig::new("tag", FieldType::Keyword));
+ schema.fields.push(FieldConfig::new("num", FieldType::Long));
+ engine.create_index(name, schema).unwrap();
+ let idx = engine.get_index(name).unwrap();
+
+ let doc = |id: &str,
+ body: Option<Value>,
+ note: Option<Value>,
+ tag: Option<&str>,
+ num: Option<i64>| {
+ let mut v = json!({ "ax_file": if id < "d030" { "f1" } else if id < "d064" { "f2" } else { "f3" } });
+ if let Some(b) = body {
+ v["body"] = b;
+ }
+ if let Some(n) = note {
+ v["note"] = n;
+ }
+ if let Some(t) = tag {
+ v["tag"] = json!(t);
+ }
+ if let Some(n) = num {
+ v["num"] = json!(n);
+ }
+ v
+ };
+
+ // f1: d000..d029 — body everywhere, note nowhere; tag null on odd,
+ // num null on every third doc.
+ for i in 0..30 {
+ idx.index_document(
+ Some(format!("d{i:03}")),
+ doc(
+ &format!("d{i:03}"),
+ Some(json!(format!("body text {i}"))),
+ None,
+ if i % 2 == 0 { Some("a") } else { None },
+ if i % 3 == 0 { None } else { Some(i as i64) },
+ ),
+ )
+ .await
+ .unwrap();
+ }
+ // f2: d030..d063 — the edge-case population.
+ for i in 30..45 {
+ idx.index_document(
+ Some(format!("d{i:03}")),
+ doc(
+ &format!("d{i:03}"),
+ Some(json!(format!("body text {i}"))),
+ Some(json!(format!("note {i}"))),
+ None,
+ None,
+ ),
+ )
+ .await
+ .unwrap();
+ }
+ for i in 45..60 {
+ idx.index_document(
+ Some(format!("d{i:03}")),
+ doc(
+ &format!("d{i:03}"),
+ None,
+ Some(json!(format!("note {i}"))),
+ None,
+ None,
+ ),
+ )
+ .await
+ .unwrap();
+ }
+ idx.index_document(
+ Some("d060".to_string()),
+ doc("d060", Some(json!("")), None, None, None),
+ )
+ .await
+ .unwrap(); // empty string: PRESENT
+ idx.index_document(
+ Some("d061".to_string()),
+ doc(
+ "d061",
+ Some(Value::Null),
+ Some(json!("note 61")),
+ None,
+ None,
+ ),
+ )
+ .await
+ .unwrap(); // explicit null: ABSENT
+ idx.index_document(
+ Some("d062".to_string()),
+ doc("d062", None, None, None, None),
+ )
+ .await
+ .unwrap(); // key omitted: ABSENT
+ idx.index_document(
+ Some("d063".to_string()),
+ doc("d063", Some(json!(["array body"])), None, None, None),
+ )
+ .await
+ .unwrap(); // array w/ non-null element: PRESENT
+ // f3: d064..d089 — no body, note on the first ten only.
+ for i in 64..90 {
+ idx.index_document(
+ Some(format!("d{i:03}")),
+ doc(
+ &format!("d{i:03}"),
+ None,
+ if i < 74 {
+ Some(json!(format!("note {i}")))
+ } else {
+ None
+ },
+ None,
+ None,
+ ),
+ )
+ .await
+ .unwrap();
+ }
+ idx.flush().await.unwrap();
+ (dir, idx)
+}
+
+async fn total(idx: &Index, query: Value, size: usize) -> u64 {
+ let req = parse_request(&json!({"query": query, "size": size, "track_total_hits": true}))
+ .expect("parse_request");
+ let res = idx.search(&req).await.expect("search");
+ res.total.value
+}
+
+/// The production shape (#1183 finalize-verify): term + exists on a
+/// column-less text field, filter context, count-only.
+#[tokio::test]
+async fn term_and_text_exists_count_matches_expectation() {
+ let (_dir, idx) = seed("exists-term-text").await;
+ // f2 body-present: d030..d044 (15) + d060 (empty string) + d063 (array)
+ // = 17; the null (d061) and omitted (d062) bodies count ABSENT.
+ assert_eq!(
+ total(
+ &idx,
+ json!({"bool": {"filter": [
+ {"term": {"ax_file": "f2"}},
+ {"exists": {"field": "body"}}
+ ]}}),
+ 0
+ )
+ .await,
+ 17
+ );
+ // Cross-path agreement: the scoring-context shape still rides the
+ // brute path and must report the same total.
+ assert_eq!(
+ total(
+ &idx,
+ json!({"bool": {"must": [
+ {"term": {"ax_file": "f2"}},
+ {"exists": {"field": "body"}}
+ ]}}),
+ 0
+ )
+ .await,
+ 17
+ );
+ assert_eq!(
+ total(
+ &idx,
+ json!({"bool": {"filter": [
+ {"term": {"ax_file": "f1"}},
+ {"exists": {"field": "body"}}
+ ]}}),
+ 0
+ )
+ .await,
+ 30
+ );
+ assert_eq!(
+ total(
+ &idx,
+ json!({"bool": {"filter": [
+ {"term": {"ax_file": "f3"}},
+ {"exists": {"field": "body"}}
+ ]}}),
+ 0
+ )
+ .await,
+ 0
+ );
+}
+
+/// A second column-less field with a different presence pattern: the leaf
+/// must consult the right field, and `must_not exists` must invert exactly.
+#[tokio::test]
+async fn note_exists_and_must_not_exist_count() {
+ let (_dir, idx) = seed("exists-note").await;
+ // f2 note-present: d030..d059 (30) + d061 = 31 of 34.
+ assert_eq!(
+ total(
+ &idx,
+ json!({"bool": {"filter": [
+ {"term": {"ax_file": "f2"}},
+ {"exists": {"field": "note"}}
+ ]}}),
+ 0
+ )
+ .await,
+ 31
+ );
+ assert_eq!(
+ total(
+ &idx,
+ json!({"bool": {"filter": [
+ {"term": {"ax_file": "f2"}},
+ ], "must_not": [{"exists": {"field": "note"}}]}}),
+ 0
+ )
+ .await,
+ 3
+ );
+ assert_eq!(
+ total(
+ &idx,
+ json!({"bool": {"filter": [
+ {"term": {"ax_file": "f3"}},
+ {"exists": {"field": "note"}}
+ ]}}),
+ 0
+ )
+ .await,
+ 10
+ );
+}
+
+/// Column-backed lowers: `exists` on keyword and long fields with nulls.
+#[tokio::test]
+async fn keyword_and_numeric_exists_in_conjunction() {
+ let (_dir, idx) = seed("exists-columns").await;
+ // f1 tag present on even ids 0..=28 → 15.
+ assert_eq!(
+ total(
+ &idx,
+ json!({"bool": {"filter": [
+ {"term": {"ax_file": "f1"}},
+ {"exists": {"field": "tag"}}
+ ]}}),
+ 0
+ )
+ .await,
+ 15
+ );
+ // f1 num present on every non-multiple of 3 → 20.
+ assert_eq!(
+ total(
+ &idx,
+ json!({"bool": {"filter": [
+ {"term": {"ax_file": "f1"}},
+ {"exists": {"field": "num"}}
+ ]}}),
+ 0
+ )
+ .await,
+ 20
+ );
+}
+
+/// size>0 must return the right ids at score 0.0 (ES filter context).
+#[tokio::test]
+async fn paged_hits_are_the_matching_ids_at_zero_score() {
+ let (_dir, idx) = seed("exists-page").await;
+ let req = parse_request(&json!({
+ "query": {"bool": {"filter": [
+ {"term": {"ax_file": "f2"}},
+ {"exists": {"field": "body"}}
+ ]}},
+ "size": 100,
+ "track_total_hits": true
+ }))
+ .expect("parse_request");
+ let res = idx.search(&req).await.unwrap();
+ assert_eq!(res.total.value, 17);
+ let mut ids: Vec<String> = res.hits.iter().map(|h| h.id.clone()).collect();
+ ids.sort_unstable();
+ let mut expected: Vec<String> = (30..45).map(|i| format!("d{i:03}")).collect();
+ expected.push("d060".to_string());
+ expected.push("d063".to_string());
+ expected.sort_unstable();
+ assert_eq!(ids, expected);
+ assert!(
+ res.hits.iter().all(|h| h.score == 0.0),
+ "filter-context scores must be 0.0, got {:?}",
+ res.hits.iter().map(|h| h.score).collect::<Vec<_>>()
+ );
+}
+
+/// The columnar executor bails on memtable-resident data by design; the
+/// brute path answers instead and must agree on the same edges.
+#[tokio::test]
+async fn memtable_resident_docs_match() {
+ let dir = TempDir::new().unwrap();
+ let engine = make_engine(&dir);
+ let mut schema = Schema::empty();
+ schema
+ .fields
+ .push(FieldConfig::new("ax_file", FieldType::Keyword));
+ schema
+ .fields
+ .push(FieldConfig::new("body", FieldType::Text));
+ engine.create_index("exists-memtable", schema).unwrap();
+ let idx = engine.get_index("exists-memtable").unwrap();
+ idx.index_document(
+ Some("m1".to_string()),
+ json!({"ax_file": "g", "body": "present"}),
+ )
+ .await
+ .unwrap();
+ idx.index_document(
+ Some("m2".to_string()),
+ json!({"ax_file": "g", "body": Value::Null}),
+ )
+ .await
+ .unwrap();
+ idx.index_document(Some("m3".to_string()), json!({"ax_file": "g"}))
+ .await
+ .unwrap();
+ // No flush: memtable-resident.
+ assert_eq!(
+ total(
+ &idx,
+ json!({"bool": {"filter": [
+ {"term": {"ax_file": "g"}},
+ {"exists": {"field": "body"}}
+ ]}}),
+ 0
+ )
+ .await,
+ 1
+ );
+}