fix(engine): terms aggregation ignores script, always returns empty buckets - #50

Summary

terms aggregation required a top-level field param and bailed out to {"buckets": []} immediately when it was absent — it never checked for script, so any script-based terms aggregation silently returned zero buckets regardless of how many documents matched the query. This breaks any Kibana visualization that buckets by a Painless script rather than a plain field — a common pattern (e.g. a "Heat Map" viz bucketing by an hour-of-day script for its Y-axis).

Root cause

let field = match params.get("field").and_then(Value::as_str) {
    Some(f) => f,
    None => return json!({"buckets": []}),
};

This is the very first thing run_terms does — it bails before touching docs at all if field is missing, with no branch anywhere in the function that looks at params.get("script").

The rest of run_terms (ordering, min_doc_count, include/exclude, partitioning, sub-agg computation, sum_other_doc_count) is agnostic to how a bucket's string key was derived — it just needs Vec<String> per doc — so this only required a key-source abstraction slotted into the field-based call sites, reusing the Painless evaluation engine (crate::painless::eval_painless/PainlessCtx) already proven correct elsewhere in this codebase for script_fields (plain search) and top_hits' runtime_mappings.

Fix

Added a small FieldOrScript enum and terms_agg_bucket_keys() helper:

• field present → unchanged behavior (extract_field_values)
• field absent, script present → evaluate the Painless script per-doc via the existing engine, flatten the result the same way a field value would be flattened
• neither present → unchanged {"buckets": []} fallback (correct ES behavior — a terms agg needs one or the other)

All four call sites inside run_terms that previously hardcoded extract_field_values(doc, field) (main counting loop, min_doc_count: 0 background-fill loop, and both bucket-doc-membership closures used for sub-agg computation and final bucket assembly) now go through this abstraction.

Scope note

This fixes the aggregation-dispatch gap specifically — terms was silently ignoring script entirely. It does not add any new Painless language features; a script's own semantics (e.g. date-value accessor methods) are a separate concern and out of scope here. The same "silently requires field, ignores script" pattern exists in most of the other bucket/metric aggregations in this file (avg, sum, min, max, stats, cardinality, histogram, date_histogram, percentiles) — terms was the one hit in practice and is fixed here; the rest are a known follow-up.

Test plan

• cargo build --release -p xerj-api -p xerj-engine -p xerj-server
• cargo fmt --check / cargo clippy --no-deps -- -D warnings — clean
• Full ES-compat YAML conformance suite: 1360 passed, 0 failed, 3 skipped — no regressions
• Manual verification: {"terms": {"script": {"source": "return 5;"}}} now produces a real bucket (key: 5.0, doc_count: N) instead of an unconditional empty array

🤖 Generated with Claude Code