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
//! ES-compatible query DSL parser.
//!
//! Converts raw `serde_json::Value` (from the HTTP request body) into a
//! [`QueryNode`] tree. The parser is intentionally lenient in the same places
//! ES is lenient (e.g. a missing `query` field defaults to `match_all`) and
//! strict — with **readable** error messages — where ES gives cryptic Java
//! stack traces.
//!
//! ## Entry points
//!
//! | Function | Description |
//! |---|---|
//! | [`parse_request`] | Parse a full `{ "query": …, "from": …, … }` body. |
//! | [`parse_query`] | Parse just the `query` object. |
use base64::Engine as _;
use serde_json::Value;
use std::cell::Cell;
use tracing::trace;
use crate::ast::{
BoolOperator, BoostMode, FieldValueFactor, FusionStrategy, Fuzziness, GeoShapeType,
MinShouldMatch, Modifier, MultiMatchType, QueryNode, RandomScore, SavingsMode, ScoreFunction,
ScoreMode, SearchRequest, SourceFilter, TrackTotalHits, WeightedQuery,
};
use crate::dates;
use crate::error::{ParseError, QueryError, Result};
use crate::sort::{SortField, SortMissing, SortMode, SortOrder};
// ── Recursion depth limit ──────────────────────────────────────────────────────
//
// Bool, dis_max, boosting and constant_score recurse into parse_query for every
// nested clause. Without a cap, a `{"bool":{"filter":[{"bool":{"filter":[…]}}]}}`
// payload of arbitrary depth blows the stack — a trivial unauthenticated DOS.
//
// ES uses a default of 20. We allow 64 (Rust frames are small relative to JVM
// frames). The counter is thread-local because parse_query is sync and runs on
// whichever tokio worker handles the request; parallel requests on different
// workers each get their own counter.
const MAX_QUERY_DEPTH: usize = 64;
/// Parse-time ceiling on `from + size`: the largest value ES's
/// `index.max_result_window` can take (a Java `int`). The real limit is the
/// index's `index.max_result_window`, else the node's
/// `limits.max_result_window` (default 10,000), and the engine enforces it
/// before anything is materialised. This bound only keeps the arithmetic
/// sane; it used to be a hardcoded 10,000, which silently overrode a larger
/// per-index setting. Deep pagination should use `search_after`/PIT.
pub const MAX_RESULT_WINDOW: usize = i32::MAX as usize;
// ── Boolean clause limit ──────────────────────────────────────────────────────
//
// Issue #122, second half. `MAX_QUERY_DEPTH` bounds how deeply a query nests;
// nothing bounded how WIDE it is, so a single `bool` could carry an unbounded
// number of clauses. That is not merely a big query: there is no compiled-script
// cache in this engine, so every `script` clause is re-tokenised and re-parsed
// for every document it is evaluated against, and the cost of a `bool` with N
// script clauses over D documents is N x D full script parses. The clause count
// is the only place that product can be bounded before any work starts.
//
// 1,024 is Elasticsearch's documented `indices.query.bool.max_clause_count`
// default, and ES answers `too_many_clauses` above it — so a query this
// rejects is a query that was already rejected by the system being emulated.
const MAX_CLAUSE_COUNT: usize = 1_024;
thread_local! {
static QUERY_DEPTH: Cell<usize> = const { Cell::new(0) };
/// Boolean clauses parsed so far in the current top-level query. Reset by
/// the outermost [`parse_query`] rather than by an RAII guard: the limit
/// is on the whole query's total width, so it must accumulate across
/// sibling `bool`s instead of unwinding with each one.
static CLAUSE_COUNT: Cell<usize> = const { Cell::new(0) };
}
/// Charge one boolean clause against [`MAX_CLAUSE_COUNT`].
fn charge_clause() -> Result<()> {
let exceeded = CLAUSE_COUNT.with(|c| {
let next = c.get() + 1;
c.set(next);
next > MAX_CLAUSE_COUNT
});
if exceeded {
return Err(QueryError::Parse(ParseError::Invalid(format!(
"too_many_clauses: maxClauseCount is set to {MAX_CLAUSE_COUNT}"
))));
}
Ok(())
}
/// RAII guard that increments the thread-local query-depth counter on
/// construction and decrements it on drop. Returns an error if the depth
/// exceeds `MAX_QUERY_DEPTH` so callers can `?` straight through.
struct DepthGuard;
impl DepthGuard {
fn enter() -> Result<Self> {
let exceeded = QUERY_DEPTH.with(|d| {
let next = d.get() + 1;
d.set(next);
next > MAX_QUERY_DEPTH
});
if exceeded {
QUERY_DEPTH.with(|d| d.set(d.get().saturating_sub(1)));
return Err(QueryError::Parse(ParseError::Invalid(format!(
"query nesting exceeds max depth of {MAX_QUERY_DEPTH}"
))));
}
Ok(DepthGuard)
}
}
impl Drop for DepthGuard {
fn drop(&mut self) {
QUERY_DEPTH.with(|d| d.set(d.get().saturating_sub(1)));
}
}
// ── Error helpers ──────────────────────────────────────────────────────────────
/// Construct `Err(QueryError::Parse(ParseError::Invalid(msg)))`.
#[inline(always)]
fn invalid<T>(msg: impl Into<String>) -> Result<T> {
Err(QueryError::Parse(ParseError::Invalid(msg.into())))
}
/// Wrap a `QueryNode` in a `Named` node if `name` is `Some`, otherwise return it as-is.
#[inline(always)]
fn maybe_named(node: QueryNode, name: Option<String>) -> QueryNode {
match name {
Some(n) => QueryNode::Named {
name: n,
query: Box::new(node),
},
None => node,
}
}
/// Construct `Err(QueryError::Parse(ParseError::UnknownQueryType(name)))`.
#[inline(always)]
fn unknown_type<T>(name: impl Into<String>) -> Result<T> {
Err(QueryError::Parse(ParseError::UnknownQueryType(name.into())))
}
// ─────────────────────────────────────────────────────────────────────────────
// Capability manifest — the single source of truth for "what queries exist"
// ─────────────────────────────────────────────────────────────────────────────
//
// Issue #211: hand-maintained lists of supported query types drifted from the
// dispatch table in `parse_query`, in both directions — docs advertised
// `has_child`/`has_parent`, which are rejected with a 400, and omitted a dozen
// types that do run. Every such list now derives from these two constants, and
// `dispatch_table_matches_capability_manifest` (below) fails the build if a
// `parse_query` arm is added or removed without updating them. Docs are checked
// against the same constants by `xerj-engine/tests/docs_capability_lists.rs`.
/// Every query-type name [`parse_query`] dispatches to a real implementation.
///
/// **Acceptance, not fidelity.** A name here means the parser builds a
/// [`QueryNode`] the planner and executor will run; it is not a claim that the
/// semantics match Elasticsearch in every corner. Per-type gaps are tracked in
/// `ROADMAP.md`.
pub const SUPPORTED_QUERY_TYPES: &[&str] = &[
"bool",
"boosting",
"combined_fields",
"constant_score",
"dis_max",
"distance_feature",
"exists",
"function_score",
"fuzzy",
"geo_bounding_box",
"geo_distance",
"geo_polygon",
"geo_shape",
"hybrid",
"ids",
"intervals",
"knn",
"match",
"match_all",
"match_bool_prefix",
"match_none",
"match_phrase",
"match_phrase_prefix",
"more_like_this",
"multi_match",
"nested",
"percolate",
"pinned",
"prefix",
"query_string",
"range",
"rank_feature",
"regexp",
"script",
"script_score",
"semantic",
"simple_query_string",
"span_containing",
"span_first",
"span_near",
"span_not",
"span_or",
"span_term",
"span_within",
"term",
"terms",
"terms_set",
"type",
"wildcard",
"wrapper",
];
/// Query-type names [`parse_query`] recognises and **deliberately rejects**
/// with a 400.
///
/// These are listed separately rather than dropped so the rejection is a
/// documented contract: an ES client sending `has_child` gets a specific
/// "not supported, denormalize the relationship" message instead of the
/// generic unknown-query-type error — and never gets silently wrong hits.
pub const REJECTED_QUERY_TYPES: &[&str] = &["has_child", "has_parent"];
// ─────────────────────────────────────────────────────────────────────────────
// Public entry points
// ─────────────────────────────────────────────────────────────────────────────
/// Parse a complete ES search request body.
///
/// ```json
/// {
/// "query": { "match": { "title": "rust" } },
/// "from": 0,
/// "size": 10,
/// "sort": [{ "date": "desc" }],
/// "_source": ["title", "body"],
/// "aggs": { … }
/// }
/// ```
pub fn parse_request(body: &Value) -> Result<SearchRequest> {
let obj = body.as_object().ok_or_else(|| {
QueryError::Parse(ParseError::Invalid(
"request body must be a JSON object".into(),
))
})?;
let query = match obj.get("query") {
Some(q) => parse_query(q)?,
None => QueryNode::MatchAll,
};
let from = match obj.get("from") {
Some(v) => v.as_u64().ok_or_else(|| {
QueryError::Parse(ParseError::Invalid(
"`from` must be a non-negative integer".into(),
))
})? as usize,
None => 0,
};
let size = match obj.get("size") {
Some(v) => v.as_u64().ok_or_else(|| {
QueryError::Parse(ParseError::Invalid(
"`size` must be a non-negative integer".into(),
))
})? as usize,
None => 10,
};
// The per-index / per-node window is checked by the engine (it needs the
// index settings, which the parser does not have), ahead of every
// allocation sized by `from + size`; see `MAX_RESULT_WINDOW`.
if from.saturating_add(size) > MAX_RESULT_WINDOW {
return invalid(format!(
"from + size must be <= {MAX_RESULT_WINDOW} (got {})",
from.saturating_add(size)
));
}
let sort = match obj.get("sort") {
Some(v) => parse_sort(v)?,
None => Vec::new(),
};
let search_after = match obj.get("search_after") {
Some(Value::Array(arr)) => Some(arr.clone()),
Some(_) => return invalid("`search_after` must be an array"),
None => None,
};
let aggs = obj.get("aggs").or_else(|| obj.get("aggregations")).cloned();
let explain = obj
.get("explain")
.and_then(|v| v.as_bool())
.unwrap_or(false);
let source = match obj.get("_source") {
Some(v) => parse_source_filter(v)?,
None => SourceFilter::default(),
};
let timeout_ms = obj.get("timeout").and_then(parse_timeout);
// Parse optional highlight configuration.
let highlight = obj
.get("highlight")
.and_then(|v| serde_json::from_value(v.clone()).ok());
// Parse track_total_hits: true | false | integer
let track_total_hits = match obj.get("track_total_hits") {
Some(Value::Bool(true)) | None => TrackTotalHits::True,
Some(Value::Bool(false)) => TrackTotalHits::False,
Some(Value::Number(n)) => {
// ES accepts `track_total_hits: -1` as an alias for `true`
// (track the exact total).
if n.as_i64().map(|v| v < 0).unwrap_or(false) {
TrackTotalHits::True
} else {
let limit = n.as_u64().unwrap_or(10_000);
TrackTotalHits::Limit(limit)
}
}
_ => TrackTotalHits::True,
};
// script_fields — opaque `{name: {script: {...}}}`; evaluated per hit
// against the doc source by the ES-compat search handler.
let script_fields = obj.get("script_fields").cloned();
// fields — stored/doc-value fields to return alongside _source.
let parse_field = |value: &Value| {
value.as_str().map(String::from).or_else(|| {
value
.as_object()
.and_then(|object| object.get("field"))
.and_then(Value::as_str)
.map(String::from)
})
};
let fields: Vec<String> = match obj.get("fields") {
Some(Value::Array(arr)) => arr.iter().filter_map(parse_field).collect(),
Some(value) => parse_field(value).into_iter().collect(),
None => Vec::new(),
};
// profile — include timing breakdown
let profile = obj.get("profile").and_then(Value::as_bool).unwrap_or(false);
Ok(SearchRequest {
query,
from,
size,
sort,
search_after,
aggs,
explain,
source,
timeout_ms,
highlight,
track_total_hits,
script_fields,
fields,
profile,
collapse: None,
rescore: Vec::new(),
min_score: None,
leaf_ts_field: None,
// Never parsed off the wire body: the ES-compat `_search` handler
// sets this from `?savings=`.
savings: SavingsMode::Off,
// #1019: ids-only is engine-internal and never arrives from the wire.
ids_only: false,
})
}
/// Parse just the query portion of a search body.
///
/// The `json` value should be the object **value** of the `"query"` key,
/// e.g. `{ "match": { "title": "hello" } }`.
pub fn parse_query(json: &Value) -> Result<QueryNode> {
// Bail out early on excessive nesting. The guard decrements on drop so
// an error return here does not leak the increment to a sibling call.
let _depth = DepthGuard::enter()?;
// Outermost call for this request: start a fresh clause budget. The
// counter cannot unwind with an RAII guard the way depth does — the limit
// is on the query's total width, which is a sum over siblings, not a
// property of the current path.
if QUERY_DEPTH.with(Cell::get) == 1 {
CLAUSE_COUNT.with(|c| c.set(0));
}
let obj = json.as_object().ok_or_else(|| {
QueryError::Parse(ParseError::Invalid("query must be a JSON object".into()))
})?;
if obj.len() != 1 {
if obj.is_empty() {
return Ok(QueryNode::MatchAll);
}
return invalid(format!(
"query object must have exactly one key, found {}: {}",
obj.len(),
obj.keys().cloned().collect::<Vec<_>>().join(", ")
));
}
let (query_type, params) = obj.iter().next().unwrap();
trace!(query_type = %query_type, "parsing query");
match query_type.as_str() {
"match_all" => parse_match_all(params),
"match_none" => Ok(QueryNode::MatchNone),
"match" => parse_match(params),
"match_phrase" => parse_match_phrase(params),
"multi_match" => parse_multi_match(params),
// ES 7.13+ `combined_fields` — treats multiple text fields as a
// single virtual field and runs a match query over their
// concatenation. We map it to multi_match with `type: cross_fields`
// (the closest existing behavior) so the query parses and executes;
// scoring doesn't exactly match ES's term-statistics pooling.
"combined_fields" => parse_combined_fields(params),
"term" => parse_term(params),
"terms" => parse_terms(params),
"range" => parse_range(params),
"prefix" => parse_prefix(params),
"wildcard" => parse_wildcard(params),
"exists" => parse_exists(params),
"ids" => parse_ids(params),
"script" => parse_script(params),
"bool" => parse_bool(params),
"query_string" => parse_query_string(params),
"constant_score" => parse_constant_score(params),
"boosting" => parse_boosting(params),
"dis_max" => parse_dis_max(params),
"knn" => parse_knn(params),
"semantic" => parse_semantic(params),
"hybrid" => parse_hybrid(params),
"fuzzy" => parse_fuzzy(params),
"regexp" => parse_regexp(params),
"match_phrase_prefix" => parse_match_phrase_prefix(params),
"simple_query_string" => parse_simple_query_string(params),
"geo_distance" => parse_geo_distance(params),
"geo_bounding_box" => parse_geo_bounding_box(params),
"function_score" => parse_function_score(params),
// ── Nested / join queries ──────────────────────────────────────────────
"nested" => parse_nested(params),
"has_child" => parse_has_child(params),
"has_parent" => parse_has_parent(params),
"more_like_this" => parse_more_like_this(params),
"percolate" => parse_percolate(params),
"pinned" => parse_pinned(params),
// ── Span queries ───────────────────────────────────────────────────────
"span_term" => parse_span_term(params),
"span_near" => parse_span_near(params),
"span_or" => parse_span_or(params),
"span_not" => parse_span_not(params),
"span_first" => parse_span_first(params),
"span_containing" | "span_within" => parse_span_containing_like(query_type, params),
// ── Geo shape queries ──────────────────────────────────────────────────
"geo_polygon" => parse_geo_polygon(params),
"geo_shape" => parse_geo_shape(params),
// ── Specialised query types ────────────────────────────────────────────
"match_bool_prefix" => parse_match_bool_prefix(params),
"terms_set" => parse_terms_set(params),
"intervals" => parse_intervals(params),
"script_score" => parse_script_score(params),
"distance_feature" => parse_distance_feature(params),
"rank_feature" => parse_rank_feature(params),
// ── Deprecated / pass-through queries ─────────────────────────────────
"type" => Ok(QueryNode::MatchAll), // everything is type _doc in modern ES
"wrapper" => parse_wrapper(params),
unknown => unknown_type(unknown),
}
}
// ─────────────────────────────────────────────────────────────────────────────
// Leaf parsers
// ─────────────────────────────────────────────────────────────────────────────
fn parse_match_all(params: &Value) -> Result<QueryNode> {
if !params.is_object() && !params.is_null() {
return invalid("`match_all` value must be an object");
}
// ES scores `match_all { boost }` as exactly `boost` per hit — the
// same constant-score semantics as `constant_score { match_all }`
// (live-verified vs ES 8.13.4: boost 3.5 → every _score 3.5, boost
// 0.0 → 0.0). Dropping the boost scored every doc 1.0. Only wrap
// when it changes anything so the plain `match_all` keeps its
// dedicated fast paths.
match params.get("boost").and_then(|v| v.as_f64()) {
Some(b) if (b as f32) != 1.0 => Ok(QueryNode::Constant {
score: b as f32,
query: Box::new(QueryNode::MatchAll),
}),
_ => Ok(QueryNode::MatchAll),
}
}
fn parse_match(params: &Value) -> Result<QueryNode> {
let obj = params
.as_object()
.ok_or_else(|| qerr("`match` must be an object"))?;
if obj.len() != 1 {
return invalid("`match` query must have exactly one field");
}
let (field, value) = obj.iter().next().unwrap();
let field = field.clone();
// An empty query string is valid ES syntax that simply has no analyzed
// terms to match — real ES treats it leniently (match_none), not as a
// parse error. Kibana's own SavedObjectsClient `_find` builds exactly
// this for a trailing-`*` search term (`"*".replace(/\*$/, '')` →
// `""`), so without this every `_find?search=*` 400s.
if matches!(value, Value::String(s) if s.is_empty()) {
return Ok(QueryNode::MatchNone);
}
// Shorthand forms: `match: {field: "value"}`, `match: {field: 42}`,
// `match: {field: true}`. ES silently stringifies non-strings.
if let Some(query) = scalar_to_string(value) {
return Ok(QueryNode::Match {
field,
query,
// No `operator` key exists in the shorthand. Log indices resolve
// this to AND (#1504); every other index treats it as OR.
operator: BoolOperator::Omitted,
analyzer: None,
boost: None,
minimum_should_match: None,
lenient: false,
});
}
let vobj = value
.as_object()
.ok_or_else(|| qerr("`match` field value must be a scalar or object"))?;
if matches!(vobj.get("query"), Some(Value::String(s)) if s.is_empty()) {
return Ok(QueryNode::MatchNone);
}
// Inside the object form, `query` can also be a number / bool.
let query = vobj
.get("query")
.and_then(scalar_to_string)
.ok_or_else(|| qerr("`match.query` must be a non-empty scalar"))?;
// Absent key → Omitted, not OR. An explicit "or" stays OR, including on
// a log index whose default is AND (#1504).
let operator = match vobj.get("operator") {
None => BoolOperator::Omitted,
some => parse_bool_operator(some)?,
};
let analyzer = vobj
.get("analyzer")
.and_then(|v| v.as_str())
.map(str::to_string);
let boost = vobj.get("boost").and_then(|v| v.as_f64()).map(|b| b as f32);
let minimum_should_match = vobj
.get("minimum_should_match")
.map(parse_min_should_match)
.transpose()?;
let name = vobj
.get("_name")
.and_then(|v| v.as_str())
.map(str::to_string);
let node = QueryNode::Match {
field,
query,
operator,
analyzer,
boost,
minimum_should_match,
lenient: parse_lenient(vobj.get("lenient")).unwrap_or(false),
};
Ok(maybe_named(node, name))
}
/// Read a clause's `lenient` flag (#1284). ES takes a JSON boolean or the
/// strings `"true"` / `"false"`; `None` means the caller applies its default.
fn parse_lenient(v: Option<&Value>) -> Option<bool> {
match v? {
Value::Bool(b) => Some(*b),
Value::String(s) if s == "true" => Some(true),
Value::String(s) if s == "false" => Some(false),
_ => None,
}
}
/// Whether a field list means "every field", the case where ES defaults
/// `lenient` to true for `multi_match`, `query_string` and
/// `simple_query_string` (#1284). An empty list counts: with no fields those
/// clauses fall back to `index.query.default_field`, whose default is `*`.
/// A narrower pattern (`b*`) does not, and ES stays strict for it.
fn targets_every_field(fields: &[String]) -> bool {
match fields {
[] => true,
[only] => qs_split_boost(only).0 == "*",
_ => false,
}
}
/// Best-effort conversion of a JSON scalar to a string for query
/// shorthand (ES accepts `match: {foo: 42}` same as `match: {foo: "42"}`).
fn scalar_to_string(v: &Value) -> Option<String> {
match v {
Value::String(s) if !s.is_empty() => Some(s.clone()),
Value::Number(n) => Some(n.to_string()),
Value::Bool(b) => Some(b.to_string()),
_ => None,
}
}
fn parse_match_phrase(params: &Value) -> Result<QueryNode> {
let obj = params
.as_object()
.ok_or_else(|| qerr("`match_phrase` must be an object"))?;
if obj.len() != 1 {
return invalid("`match_phrase` query must have exactly one field");
}
let (field, value) = obj.iter().next().unwrap();
let field = field.clone();
// Empty query string → match_none, not a parse error. See `parse_match`.
if matches!(value, Value::String(s) if s.is_empty()) {
return Ok(QueryNode::MatchNone);
}
// Shorthand forms: `match_phrase: {field: "value"}`, `match_phrase:
// {field: 42}`, `match_phrase: {field: true}` — ES silently stringifies
// non-strings, same as `match` (see `scalar_to_string`).
if let Some(query) = scalar_to_string(value) {
return Ok(QueryNode::MatchPhrase {
field,
query,
slop: 0,
analyzer: None,
boost: None,
lenient: false,
});
}
let vobj = value
.as_object()
.ok_or_else(|| qerr("`match_phrase` field value must be a string or object"))?;
if matches!(vobj.get("query"), Some(Value::String(s)) if s.is_empty()) {
return Ok(QueryNode::MatchNone);
}
// Inside the object form, `query` can also be a number / bool — e.g.
// OpenSearch Dashboards filtering on a boolean field sends
// `match_phrase: {field: {query: true}}` verbatim (found empirically,
// this is what a real OSD dashboard filter on a bool field produces).
let query = vobj
.get("query")
.and_then(scalar_to_string)
.ok_or_else(|| qerr("`match_phrase.query` must be a non-empty scalar"))?;
let slop = parse_phrase_slop(vobj.get("slop"), "match_phrase")?;
let analyzer = vobj
.get("analyzer")
.and_then(|v| v.as_str())
.map(str::to_string);
let boost = vobj.get("boost").and_then(|v| v.as_f64()).map(|b| b as f32);
let name = vobj
.get("_name")
.and_then(|v| v.as_str())
.map(str::to_string);
// `match_phrase` has no `lenient` option in ES (it answers `[match_phrase]
// query does not support [lenient]`), so a parsed phrase is always strict.
let node = QueryNode::MatchPhrase {
field,
query,
slop,
analyzer,
boost,
lenient: false,
};
Ok(maybe_named(node, name))
}
/// Coerce a JSON scalar to an integer the way ES's `XContentParser.intValue()`
/// does under its default number policy (`DEFAULT_NUMBER_COERCE_POLICY = true`):
/// an integer is taken as written, a **float is truncated** toward zero, and a
/// numeric **string** is read as a double and then narrowed
/// (`libs/x-content/src/main/java/org/elasticsearch/xcontent/support/AbstractXContentParser.java`:
/// `:70` — "the 3rd party parsers we rely on are known to silently truncate
/// fractions", guarding `ensureNumberConversion` at `:74`, which only raises
/// when `coerce == false`; `:171` `intValue(coerce)`, whose `VALUE_STRING`
/// arm calls `:162` `parseInt`, itself a `Double.parseDouble` narrowed with
/// `(int)`; AGPL, read for semantics only, nothing copied).
///
/// Why it exists: JSON encoders that carry every number as a double emit
/// `"slop": 2.0`, and ES answers that query with slop 2. Reading it with
/// `as_i64()` alone leaves two bad options — a 400 on a request ES answers, or
/// a silent fall back to the default, which is the accept-and-ignore (#204)
/// this parser exists to remove.
///
/// The `as i64` cast saturates on an out-of-range float, so an absurd value
/// lands on the bound and the caller's range check turns it into a 400 rather
/// than a wrapped, silently honoured small number.
fn coerce_es_int(v: &Value) -> Option<i64> {
if let Some(n) = v.as_i64() {
return Some(n);
}
let d = match v {
Value::Number(_) => v.as_f64()?,
Value::String(s) => s.trim().parse::<f64>().ok()?,
_ => return None,
};
d.is_finite().then(|| d.trunc() as i64)
}
/// Parse the `slop` parameter of a phrase-shaped query, identically at each of
/// the three entry points that accept one and lower it to a phrase:
/// `match_phrase`, `match_phrase_prefix`, `multi_match`. Sharing it is the
/// point: the same JSON value must produce the same answer whichever of those
/// three wraps it, or a client gets a 400 from one spelling and a silently
/// different answer from the semantically identical other.
///
/// Deliberately **not** covered: `span_near`, which also takes a `slop` and
/// keeps its own `as_u64().unwrap_or(0)` read (see `parse_span_near`). ES
/// applies no validation there either — `SpanNearQueryBuilder` stores the int
/// unchecked (`.../index/query/SpanNearQueryBuilder.java:62`), so a negative
/// `span_near` slop is a query ES *answers*, and routing it through here would
/// turn a 200 into a 400. XERJ still coerces it to 0 instead of honouring it,
/// which is a real (pre-existing) gap — recorded in `parse_span_near`, not
/// papered over here.
///
/// ES rejects a negative slop from all three phrase builders
/// (`MatchPhraseQueryBuilder.slop` / `MatchPhrasePrefixQueryBuilder.slop:103`
/// / `MultiMatchQueryBuilder.slop:350` all throw "No negative slop allowed";
/// AGPL, read for semantics only). `u32::try_from` rather than `as u32`
/// because a wrapping cast turns an out-of-range slop into a small honoured
/// one — a silently wrong answer, which is worse than a 400.
fn parse_phrase_slop(v: Option<&Value>, ctx: &str) -> Result<u32> {
match v {
None | Some(Value::Null) => Ok(0),
Some(v) => match coerce_es_int(v) {
Some(n) if n < 0 => invalid(format!("`{ctx}.slop` must not be negative")),
Some(n) => u32::try_from(n).map_err(|_| qerr(format!("`{ctx}.slop` is out of range"))),
None => invalid(format!("`{ctx}.slop` must be a number")),
},
}
}
/// Parse `max_expansions`, with the same refusal-to-ignore as
/// [`parse_phrase_slop`]: a value XERJ cannot read is a 400, never a silent
/// fall back to the default of 50.
///
/// The floor differs between the two entry points, and that asymmetry is ES's
/// rather than an oversight here: `MultiMatchQueryBuilder.maxExpansions`
/// throws on `<= 0` (`.../index/query/MultiMatchQueryBuilder.java:389`) while
/// `MatchPhrasePrefixQueryBuilder.maxExpansions` throws only on `< 0`
/// (`.../index/query/MatchPhrasePrefixQueryBuilder.java:118`, "No negative
/// maxExpansions allowed"). So `0` is a 400 on `multi_match` and an accepted
/// (expand-nothing) value on `match_phrase_prefix`; `allow_zero` carries that
/// distinction instead of us inventing one ES does not have.
fn parse_max_expansions(v: Option<&Value>, ctx: &str, allow_zero: bool) -> Result<u32> {
match v {
None | Some(Value::Null) => Ok(DEFAULT_MAX_EXPANSIONS),
Some(v) => match coerce_es_int(v) {
Some(n) if n < 0 => invalid(format!("`{ctx}.max_expansions` must not be negative")),
Some(0) if !allow_zero => invalid(format!("`{ctx}.max_expansions` must be positive")),
Some(n) => u32::try_from(n)
.map_err(|_| qerr(format!("`{ctx}.max_expansions` is out of range"))),
None => invalid(format!("`{ctx}.max_expansions` must be a number")),
},
}
}
/// ES's `FuzzyQuery.defaultMaxExpansions`, which both phrase-prefix builders
/// default to.
const DEFAULT_MAX_EXPANSIONS: u32 = 50;
/// ES `combined_fields` query — introduced in 7.13, treats N text fields as a
/// single virtual field for term-frequency scoring. Our approximation routes
/// it to `multi_match` with `type: "cross_fields"`, which is the closest
/// existing behavior. Accepts the same parameters ES does (query, fields,
/// operator, minimum_should_match, zero_terms_query).
fn parse_combined_fields(params: &Value) -> Result<QueryNode> {
let obj = params
.as_object()
.ok_or_else(|| qerr("`combined_fields` must be an object"))?;
let mut rewritten = obj.clone();
rewritten.insert(
"type".to_string(),
Value::String("cross_fields".to_string()),
);
parse_multi_match(&Value::Object(rewritten))
}
fn parse_multi_match(params: &Value) -> Result<QueryNode> {
let obj = params
.as_object()
.ok_or_else(|| qerr("`multi_match` must be an object"))?;
let query = string_field(obj, "query")?;
let fields = obj
.get("fields")
.and_then(|v| v.as_array())
.ok_or_else(|| qerr("`multi_match.fields` must be an array"))?
.iter()
.map(|v| {
v.as_str()
.ok_or_else(|| qerr("`multi_match.fields` must contain strings"))
.map(str::to_string)
})
.collect::<Result<Vec<_>>>()?;
if fields.is_empty() {
return invalid("`multi_match.fields` must not be empty");
}
// #1284: explicit `lenient`, else ES's default: lenient only when the
// clause targets every field (`["*"]`).
let lenient = parse_lenient(obj.get("lenient")).unwrap_or_else(|| targets_every_field(&fields));
let type_str = obj
.get("type")
.and_then(|v| v.as_str())
.unwrap_or("best_fields");
// `slop` / `max_expansions` are the phrase parameters of `multi_match`.
// They used to be dropped here, so `{"type":"phrase","slop":2}` was
// accepted and silently evaluated as slop 0 (issue #230) — parse them
// and reject the values ES rejects instead of quietly mis-answering.
// ES: negative slop and non-positive max_expansions are 400s, and
// `slop` is not allowed with `type: bool_prefix`.
let slop: u32 = parse_phrase_slop(obj.get("slop"), "multi_match")?;
let max_expansions: u32 =
parse_max_expansions(obj.get("max_expansions"), "multi_match", false)?;
if slop != 0 && type_str == "bool_prefix" {
// ES's own wording — `310_match_bool_prefix.yml` catches this exact
// regex. The suite's runner only checks that the call is allowed to
// fail, so this arm passed while XERJ silently ignored `slop`.
return invalid("[slop] not allowed for type [bool_prefix]");
}
// `slop` with `type: phrase_prefix` is ACCEPTED and HONOURED, because ES
// honours it: `MultiMatchQueryBuilder` rejects slop only for
// `bool_prefix` (…/index/query/MultiMatchQueryBuilder.java:673) and
// `TextFieldMapper.createPhrasePrefixQuery` calls
// `MultiPhrasePrefixQuery.setSlop(slop)` (…/index/mapper/
// TextFieldMapper.java:2019, `setSlop` at :2028, reached from the
// `phrasePrefixQuery` entry at :1269 — AGPL, read for semantics only).
// Both XERJ
// evaluators now carry it: `PhrasePrefixQuery.slop` on the segment side
// and the sloppy prefix walk in the stored-doc scan. Refusing it here
// would have been a wire-compat break on a query ES answers, and would
// have left the semantically identical single-field
// `{"match_phrase_prefix": {"f": {"query": …, "slop": N}}}` — which
// `parse_match_phrase_prefix` accepts — answering a different query.
//
// `slop` on the FIELD-CENTRIC types (best_fields / most_fields /
// cross_fields) is accepted and unused, which is also what ES does:
// those types lower to a BOOLEAN match query, and only the PHRASE and
// PHRASE_PREFIX types lower to a phrase query that reads slop
// (`MultiMatchQueryBuilder.Type`, elasticsearch/server/src/main/java/
// org/elasticsearch/index/query/MultiMatchQueryBuilder.java:91 — AGPL,
// read for semantics only). Same answer as ES, so there is nothing to
// fail loudly about.
// bool_prefix: rewrite to a Bool::should over per-field match_bool_prefix
// clauses. Tokens except the last become Match queries, the last becomes
// a Prefix query — matching ES `match_bool_prefix` semantics across all
// supplied fields.
if type_str == "bool_prefix" {
let analyzer_opt = obj
.get("analyzer")
.and_then(|v| v.as_str())
.map(str::to_string);
let analyzer_lowercases = !matches!(
analyzer_opt.as_deref(),
Some("whitespace") | Some("keyword")
);
let operator_and = matches!(
obj.get("operator")
.and_then(Value::as_str)
.map(|s| s.to_ascii_lowercase())
.as_deref(),
Some("and")
);
let mm_ms = obj
.get("minimum_should_match")
.and_then(|v| parse_min_should_match(v).ok());
let fuzziness_opt = obj.get("fuzziness").map(|v| match v {
Value::String(s) if s.eq_ignore_ascii_case("auto") => crate::ast::Fuzziness::Auto,
Value::String(s) => s
.parse::<u32>()
.ok()
.map(crate::ast::Fuzziness::Fixed)
.unwrap_or(crate::ast::Fuzziness::Auto),
Value::Number(n) => crate::ast::Fuzziness::Fixed(n.as_u64().unwrap_or(0) as u32),
_ => crate::ast::Fuzziness::Auto,
});
// #848: `match` accepts `prefix_length` alongside `fuzziness`.
let prefix_length = parse_prefix_length(obj);
let raw_tokens: Vec<String> = if analyzer_opt.as_deref() == Some("keyword") {
vec![query.to_string()]
} else {
query.split_whitespace().map(str::to_string).collect()
};
let tokens: Vec<String> = raw_tokens
.into_iter()
.map(|t| {
if analyzer_lowercases {
t.to_lowercase()
} else {
t
}
})
.collect();
if tokens.is_empty() {
return Ok(QueryNode::MatchAll);
}
let boost = obj.get("boost").and_then(|v| v.as_f64()).map(|b| b as f32);
let mut should: Vec<QueryNode> = Vec::new();
for raw_field in &fields {
// Strip any ^boost suffix (e.g. "title^2").
let (field, fb): (&str, Option<f32>) = match raw_field.rfind('^') {
Some(idx) => (&raw_field[..idx], raw_field[idx + 1..].parse::<f32>().ok()),
None => (raw_field.as_str(), None),
};
if tokens.len() == 1 {
let prefix = QueryNode::Prefix {
field: field.to_string(),
value: tokens[0].clone(),
boost: fb,
constant_score: false,
case_insensitive: false,
};
should.push(prefix);
continue;
}
let last = tokens.len() - 1;
let build_leaf = |tok: &str| -> QueryNode {
if let Some(fz) = fuzziness_opt {
QueryNode::Fuzzy {
field: field.to_string(),
value: tok.to_string(),
fuzziness: fz,
case_insensitive: false,
prefix_length,
}
} else {
QueryNode::Match {
field: field.to_string(),
query: tok.to_string(),
operator: BoolOperator::Or,
boost: None,
analyzer: analyzer_opt.clone(),
minimum_should_match: None,
lenient,
}
}
};
let mut inner_clauses: Vec<QueryNode> =
tokens[..last].iter().map(|t| build_leaf(t)).collect();
inner_clauses.push(QueryNode::Prefix {
field: field.to_string(),
value: tokens[last].clone(),
boost: None,
constant_score: false,
case_insensitive: false,
});
let (im, is, imm) = if operator_and {
(inner_clauses, vec![], None)
} else {
(vec![], inner_clauses, mm_ms.clone())
};
let inner_bool = QueryNode::Bool {
must: im,
should: is,
filter: vec![],
must_not: vec![],
minimum_should_match: imm,
};
let field_clause = if let Some(b) = fb {
QueryNode::Boosted {
boost: b,
query: Box::new(inner_bool),
}
} else {
inner_bool
};
should.push(field_clause);
}
return Ok(QueryNode::Bool {
must: vec![],
should,
filter: vec![],
must_not: vec![],
minimum_should_match: None,
})
.map(|n| match boost {
Some(b) => QueryNode::Boosted {
query: Box::new(n),
boost: b,
},
None => n,
});
}
let match_type = match type_str {
"best_fields" => MultiMatchType::BestFields,
"most_fields" => MultiMatchType::MostFields,
"cross_fields" => MultiMatchType::CrossFields,
"phrase" => MultiMatchType::Phrase,
"phrase_prefix" => MultiMatchType::PhrasePrefix,
other => return invalid(format!("unknown multi_match type `{other}`")),
};
let operator = parse_bool_operator(obj.get("operator")).ok();
let analyzer = obj
.get("analyzer")
.and_then(|v| v.as_str())
.map(str::to_string);
let boost = obj.get("boost").and_then(|v| v.as_f64()).map(|b| b as f32);
Ok(QueryNode::MultiMatch {
fields,
query,
match_type,
operator,
analyzer,
boost,
slop,
max_expansions,
lenient,
})
}
fn parse_term(params: &Value) -> Result<QueryNode> {
let obj = params
.as_object()
.ok_or_else(|| qerr("`term` must be an object"))?;
if obj.len() != 1 {
return invalid("`term` query must have exactly one field");
}
let (field, raw) = obj.iter().next().unwrap();
let field = field.clone();
if let Some(inner) = raw.as_object() {
if let Some(value) = inner.get("value") {
let boost = inner
.get("boost")
.and_then(|v| v.as_f64())
.map(|b| b as f32);
let name = inner
.get("_name")
.and_then(|v| v.as_str())
.map(str::to_string);
let case_insensitive = inner
.get("case_insensitive")
.and_then(Value::as_bool)
.unwrap_or(false);
// `term` with `case_insensitive:true` is semantically an
// exact-match against the lowercased value. Our Wildcard
// matcher already lowercases both sides before comparing and
// treats a pattern with no `*` / `?` as an exact match, so
// routing through Wildcard gives correct semantics without a
// new QueryNode variant.
if case_insensitive {
let val_str = match value {
Value::String(s) => s.clone(),
other => other.to_string().trim_matches('"').to_string(),
};
let node = QueryNode::Wildcard {
field,
value: val_str,
boost,
// KNOWN DIFF (live-verified vs ES 8.13.4): ES lowers
// `term{case_insensitive:true}` to a case-insensitive
// automaton query with the CONSTANT_SCORE rewrite
// (max_score 1.0), while this keeps BM25 (1.2821425).
// `constant_score: true` here is NOT safe yet: it
// admits the shape to the columnar KeywordWildcard
// leaf, whose dictionary narrowing is CASE-SENSITIVE —
// a mixed-case value then returns 0 hits (hit-set
// regression ≫ score diff). Fixing the score requires
// threading `case_insensitive` through
// QueryNode::Wildcard into the columnar/FST arms.
constant_score: false,
case_insensitive: true,
};
return Ok(maybe_named(node, name));
}
let node = QueryNode::Term {
field,
value: value.clone(),
boost,
};
return Ok(maybe_named(node, name));
}
}
Ok(QueryNode::Term {
field,
value: raw.clone(),
boost: None,
})
}
fn parse_terms(params: &Value) -> Result<QueryNode> {
let obj = params
.as_object()
.ok_or_else(|| qerr("`terms` must be an object"))?;
let field_entries: Vec<_> = obj.iter().filter(|(k, _)| k.as_str() != "boost").collect();
if field_entries.len() != 1 {
return invalid("`terms` query must have exactly one field");
}
let (field, raw) = field_entries[0];
let field = field.clone();
// Terms lookup: {"terms": {"category": {"index": "other", "id": "1", "path": "categories"}}}
//
// These are RESOLVED before parsing: the HTTP layer's
// `resolve_terms_lookups` fetches the source doc and substitutes the
// concrete value array, so a lookup object should not reach this parser on
// a supported endpoint. Reaching here means an endpoint parsed the query
// WITHOUT resolving first. Previously that returned `MatchNone` (empty
// results) with only a `warn` — a silent wrong answer: `_count` returned 0
// for a filter `_search` counted correctly. Fail loudly so the gap is
// visible instead of silently miscounting; the real fix is to resolve at
// the endpoint, as `_count` now does.
if raw.is_object() {
return invalid(format!(
"terms lookup on `{field}` reached the query parser unresolved — \
the calling endpoint did not resolve `{{index, id, path}}` before \
parsing. It is supported on `_search`/`_count`; an endpoint that \
hits this needs a `resolve_terms_lookups` step."
));
}
let values = raw
.as_array()
.ok_or_else(|| qerr("`terms` values must be an array"))?
.clone();
let boost = obj.get("boost").and_then(|v| v.as_f64()).map(|b| b as f32);
Ok(QueryNode::Terms {
field,
values,
boost,
})
}
/// The format string ES reports in `failed to parse date field` errors when
/// no explicit `format` was given.
const DEFAULT_DATE_FORMAT: &str = "strict_date_optional_time||epoch_millis";
/// Map a [`dates::DateResolveError`] to the exact ES error message. `fmt` is
/// the explicit `format` parameter, if any.
fn date_resolve_err(e: dates::DateResolveError, fmt: Option<&str>, value: &str) -> QueryError {
use dates::DateResolveError::*;
let msg = match e {
UnknownPatternLetter(c) => format!(
"Invalid format: [{}]: Unknown pattern letter: {c}",
fmt.unwrap_or_default()
),
UnparseableValue(v) => {
let f = fmt.unwrap_or(DEFAULT_DATE_FORMAT);
format!(
"failed to parse date field [{v}] with format [{f}]: \
[failed to parse date field [{v}] with format [{f}]]"
)
}
BadDateMath(m) => {
let _ = value; // value context already inside the math substring
format!("operator not supported for date math [{m}]")
}
UnknownTimeZone(tz) => format!("Unknown time-zone ID: {tz}"),
};
QueryError::Parse(ParseError::Invalid(msg))
}
/// Resolve one range bound per ES date semantics (rounding, `format`,
/// date math). `round_up` is true for `lte`/`gt` bounds. Non-date-shaped
/// values under the default format pass through unchanged so keyword and
/// numeric ranges keep their comparator semantics.
fn resolve_range_bound(
v: Value,
round_up: bool,
formats: Option<&[dates::DateFmt]>,
fmt_raw: Option<&str>,
tz: Option<&dates::TimeZone>,
) -> Result<Value> {
match &v {
Value::String(s) => match dates::resolve_date_bound_str_in(s, round_up, formats, tz) {
Ok(Some(iso)) => Ok(Value::String(iso)),
Ok(None) => Ok(v),
Err(e) => Err(date_resolve_err(e, fmt_raw, s)),
},
Value::Number(n) => match formats {
// ES stringifies numbers under an explicit date format
// (`gte: 1500, format: "uuuu"` parses "1500" as a year).
Some(fmts) => match dates::resolve_date_bound_num_in(n, round_up, fmts, tz) {
Ok(Some(iso)) => Ok(Value::String(iso)),
Ok(None) => Ok(v),
Err(e) => Err(date_resolve_err(e, fmt_raw, &n.to_string())),
},
// Default format: numbers are epoch-millis instants — the
// engine's numeric comparator already handles them exactly.
None => Ok(v),
},
_ => Ok(v),
}
}
fn parse_range(params: &Value) -> Result<QueryNode> {
let obj = params
.as_object()
.ok_or_else(|| qerr("`range` must be an object"))?;
if obj.len() != 1 {
return invalid("`range` query must have exactly one field");
}
let (field, raw) = obj.iter().next().unwrap();
let field = field.clone();
let inner = raw
.as_object()
.ok_or_else(|| qerr("`range` field value must be an object"))?;
let mut gte = inner.get("gte").cloned();
let mut gt = inner.get("gt").cloned();
let mut lte = inner.get("lte").cloned();
let mut lt = inner.get("lt").cloned();
let boost = inner
.get("boost")
.and_then(|v| v.as_f64())
.map(|b| b as f32);
// ES date bound resolution — date math (`now-24h`, `2026-01-01||+1M/d`),
// partial-date round-up/round-down fills (`lte: "2026-02"` covers through
// 2026-02-01T23:59:59.999), and the `format` parameter (`uuuu`,
// `dd/MM/yyyy`, `epoch_millis`, …). Bounds resolve to canonical ISO
// instants here so every downstream comparator (JSON-scan, doc-values
// prefilter, memtable) sees the same concrete value. An invalid
// `format` or a value that fails an explicit format is a hard 400,
// matching live ES 8.13.4.
let fmt_raw = inner.get("format").and_then(|v| v.as_str());
let formats = match fmt_raw {
Some(f) => Some(dates::compile_formats(f).map_err(|e| date_resolve_err(e, fmt_raw, ""))?),
None => None,
};
// `time_zone` applies to bounds without their own offset and to date
// math rounding; an unknown zone is a 400, as in ES.
let tz = match inner.get("time_zone").and_then(|v| v.as_str()) {
Some(raw) => {
Some(dates::TimeZone::parse(raw).map_err(|e| date_resolve_err(e, fmt_raw, raw))?)
}
None => None,
};
let tz = tz.as_ref();
let fmts = formats.as_deref();
// Round-up bounds: `lte` includes its whole covered interval, `gt`
// excludes its whole covered interval. `gte`/`lt` round down.
if let Some(v) = gte.take() {
gte = Some(resolve_range_bound(v, false, fmts, fmt_raw, tz)?);
}
if let Some(v) = gt.take() {
gt = Some(resolve_range_bound(v, true, fmts, fmt_raw, tz)?);
}
if let Some(v) = lte.take() {
lte = Some(resolve_range_bound(v, true, fmts, fmt_raw, tz)?);
}
if let Some(v) = lt.take() {
lt = Some(resolve_range_bound(v, false, fmts, fmt_raw, tz)?);
}
if gte.is_none() && gt.is_none() && lte.is_none() && lt.is_none() {
return invalid("`range` query must have at least one bound (gte, gt, lte, lt)");
}
Ok(QueryNode::Range {
field,
gte,
gt,
lte,
lt,
boost,
lenient: false,
})
}
fn parse_prefix(params: &Value) -> Result<QueryNode> {
let obj = params
.as_object()
.ok_or_else(|| qerr("`prefix` must be an object"))?;
if obj.len() != 1 {
return invalid("`prefix` query must have exactly one field");
}
let (field, raw) = obj.iter().next().unwrap();
let field = field.clone();
if let Some(value) = raw.as_str() {
return Ok(QueryNode::Prefix {
field,
value: value.to_string(),
boost: None,
constant_score: true,
case_insensitive: false,
});
}
let inner = raw
.as_object()
.ok_or_else(|| qerr("`prefix` field value must be a string or object"))?;
let value = string_field(inner, "value")?;
let boost = inner
.get("boost")
.and_then(|v| v.as_f64())
.map(|b| b as f32);
// #681: honor `_name` on the expanded form, like `parse_term`, so a named
// prefix clause surfaces in `matched_queries`.
let name = inner
.get("_name")
.and_then(|v| v.as_str())
.map(str::to_string);
Ok(maybe_named(
QueryNode::Prefix {
field,
value,
boost,
constant_score: true,
case_insensitive: inner
.get("case_insensitive")
.and_then(|v| v.as_bool())
.unwrap_or(false),
},
name,
))
}
fn parse_wildcard(params: &Value) -> Result<QueryNode> {
let obj = params
.as_object()
.ok_or_else(|| qerr("`wildcard` must be an object"))?;
if obj.len() != 1 {
return invalid("`wildcard` query must have exactly one field");
}
let (field, raw) = obj.iter().next().unwrap();
let field = field.clone();
if let Some(value) = raw.as_str() {
return Ok(QueryNode::Wildcard {
field,
value: value.to_string(),
boost: None,
constant_score: true,
case_insensitive: false,
});
}
let inner = raw
.as_object()
.ok_or_else(|| qerr("`wildcard` field value must be a string or object"))?;
let value = string_field(inner, "value")?;
let boost = inner
.get("boost")
.and_then(|v| v.as_f64())
.map(|b| b as f32);
// #681: honor `_name` on the expanded form (like `parse_term`).
let name = inner
.get("_name")
.and_then(|v| v.as_str())
.map(str::to_string);
Ok(maybe_named(
QueryNode::Wildcard {
field,
value,
boost,
constant_score: true,
case_insensitive: inner
.get("case_insensitive")
.and_then(|v| v.as_bool())
.unwrap_or(false),
},
name,
))
}
fn parse_exists(params: &Value) -> Result<QueryNode> {
let obj = params
.as_object()
.ok_or_else(|| qerr("`exists` must be an object"))?;
let field = string_field(obj, "field")?;
Ok(QueryNode::Exists { field })
}
fn parse_ids(params: &Value) -> Result<QueryNode> {
let obj = params
.as_object()
.ok_or_else(|| qerr("`ids` must be an object"))?;
let values = obj
.get("values")
.and_then(|v| v.as_array())
.ok_or_else(|| qerr("`ids.values` must be an array"))?
.iter()
.map(|v| match v {
Value::String(s) => Ok(s.clone()),
Value::Number(n) => Ok(n.to_string()),
_ => Err(qerr("`ids.values` must contain strings or numbers")),
})
.collect::<Result<Vec<_>>>()?;
let node = QueryNode::Ids { values };
// `ids.boost` IS the hit score: ES scores an ids query as the constant
// `boost` (default 1.0) — live-verified on 8.13.4: boost 2.0 / 0.37 /
// 0.0 all come back verbatim as `_score`. Carried as a `Boosted`
// wrapper (whose scorer arm already yields the constant `boost` on
// match) instead of a new AST field, so match semantics are untouched.
// Was silently dropped (always scored 1.0).
if let Some(boost) = obj.get("boost").and_then(|v| v.as_f64()) {
let boost = boost as f32;
if boost != 1.0 {
return Ok(QueryNode::Boosted {
boost,
query: Box::new(node),
});
}
}
Ok(node)
}
fn parse_script(params: &Value) -> Result<QueryNode> {
let obj = params
.as_object()
.ok_or_else(|| qerr("`script` must be an object"))?;
let script = obj
.get("script")
.and_then(Value::as_object)
.ok_or_else(|| qerr("`script.script` is required"))?;
let source = script
.get("source")
.and_then(Value::as_str)
.ok_or_else(|| qerr("`script.script.source` is required"))?
.to_string();
let params = script.get("params").cloned();
Ok(QueryNode::Script { source, params })
}
fn parse_query_string(params: &Value) -> Result<QueryNode> {
let obj = params
.as_object()
.ok_or_else(|| qerr("`query_string` must be an object"))?;
let query = string_field(obj, "query")?;
// Defense-in-depth: bound the raw query string length before tokenizing.
// The depth guard in `parse_qs_unary`'s `LParen` arm caps paren nesting to
// `MAX_QUERY_DEPTH`, but a pathological non-paren query (e.g. millions of
// juxtaposed terms) can still blow up the token stream. 64 KiB is far
// above any realistic Lucene query string (ES effectively limits this too)
// and well within the 100 MiB request body cap.
const MAX_QUERY_STRING_LEN: usize = 65_536;
if query.len() > MAX_QUERY_STRING_LEN {
return Err(qerr(format!(
"query_string.query length {} exceeds max of {} characters",
query.len(),
MAX_QUERY_STRING_LEN
)));
}
let mut default_field = obj
.get("default_field")
.and_then(|v| v.as_str())
.map(str::to_string);
// `fields` was accepted and ignored: the key never reached this parser, so
// `query_string {"query":"x","fields":["title"]}` searched every field —
// and, once `index: false` became a real rejection, disagreed with
// `{"default_field":"title"}`, which is the same request written the other
// way. It is now read and used, the way `simple_query_string` already used
// its own `fields` list: an unqualified clause is searched over exactly
// these fields (a `^boost` suffix is honoured), while a `field:value`
// clause inside the string keeps naming its own field, as in ES.
let fields: Vec<String> = obj
.get("fields")
.and_then(Value::as_array)
.map(|arr| {
arr.iter()
.filter_map(Value::as_str)
.map(str::to_string)
.collect()
})
.unwrap_or_default();
let default_operator = parse_bool_operator(obj.get("default_operator")).ok();
let boost = obj.get("boost").and_then(|v| v.as_f64()).map(|b| b as f32);
// #1284: explicit `lenient`, else ES's default, which is lenient only when
// the clause's field set is every field. That is why `bytes:abc` with no
// `default_field` is a 200 on ES even though the clause names `bytes`.
let lenient =
parse_lenient(obj.get("lenient")).unwrap_or_else(|| match default_field.as_deref() {
Some(df) if fields.is_empty() => df == "*",
_ => targets_every_field(&fields),
});
// Try to lower the query string into a Bool tree so downstream matchers
// can honor `field:value` + OR/AND syntax. Fall back to the opaque
// QueryString node if lowering isn't possible (the FTS path still
// tokenizes it) — but malformed range syntax is a hard parse error,
// never a silent term-match fallback.
if let Some(lowered) = try_lower_query_string(
&query,
QsFields {
default_field: default_field.as_deref(),
fields: &fields,
lenient,
},
default_operator,
)? {
return Ok(match boost {
Some(b) if b != 1.0 => QueryNode::Boosted {
boost: b,
query: Box::new(lowered),
},
_ => lowered,
});
}
// Lowering declined (a string this tokenizer cannot handle, e.g. an
// unterminated quote): the opaque node hands the whole string to the FTS
// path. A one-element `fields` list means exactly what `default_field`
// means, so it is carried across rather than dropped. A multi-element list
// has no representation on this node — that residue is stated as a known
// gap in the CHANGELOG rather than papered over.
if default_field.is_none() && fields.len() == 1 {
default_field = Some(qs_split_boost(&fields[0]).0);
}
Ok(QueryNode::QueryString {
query,
default_field,
default_operator,
boost,
})
}
/// Split a `fields` entry into its field name and optional `^boost`.
///
/// `"title^3"` → `("title", Some(3.0))`, `"title"` → `("title", None)`. A
/// malformed suffix (`"title^x"`) keeps the whole spec as the name, which is
/// what ES's field-spec parser does with an unparseable boost.
fn qs_split_boost(spec: &str) -> (String, Option<f32>) {
match spec.rsplit_once('^') {
Some((name, b)) if !name.is_empty() => match b.parse::<f32>() {
Ok(b) if b.is_finite() => (name.to_string(), Some(b)),
_ => (spec.to_string(), None),
},
_ => (spec.to_string(), None),
}
}
/// Where a clause that named no field of its own is searched.
///
/// `query_string` has two ways to say this and ES treats them as the same
/// thing: `default_field` (one field) and `fields` (a list, `^boost` allowed).
/// An empty `fields` with no `default_field` keeps the historical `"*"`
/// placeholder, which downstream means the field-less scan.
#[derive(Clone, Copy)]
struct QsFields<'a> {
default_field: Option<&'a str>,
fields: &'a [String],
/// The clause's effective `lenient` (#1284), stamped on every leaf the
/// string lowers to, field-qualified ones included: ES decides leniency
/// once per `query_string`, not per clause.
lenient: bool,
}
impl QsFields<'_> {
/// The (field, boost) targets for an unqualified clause.
fn targets(&self) -> Vec<(String, Option<f32>)> {
if self.fields.is_empty() {
return vec![(self.default_field.unwrap_or("*").to_string(), None)];
}
self.fields.iter().map(|s| qs_split_boost(s)).collect()
}
/// Whether an unqualified *range* has a concrete field to land on. A
/// range needs one real field name; `"*"` is not one.
fn has_concrete_target(&self) -> bool {
if self.fields.is_empty() {
return matches!(self.default_field, Some(df) if !df.is_empty() && df != "*");
}
self.fields
.iter()
.any(|s| !s.is_empty() && !qs_split_boost(s).0.contains('*'))
}
}
/// The (field, boost) targets one query-string clause resolves to.
///
/// `explicit` is the `field:` prefix the clause carried, if any: ES keeps an
/// explicitly named field whatever `fields` / `default_field` say, and only an
/// unqualified clause fans out over them.
fn qs_targets(explicit: &str, ctx: QsFields<'_>) -> Vec<(String, Option<f32>)> {
if explicit.is_empty() {
ctx.targets()
} else {
vec![(explicit.to_string(), None)]
}
}
/// Combine the per-field copies of one unqualified clause.
///
/// One target stays a bare leaf (the shape every existing query_string test
/// pins); several become a `dis_max`, which is how ES combines a
/// `query_string` over multiple fields — best field wins, no tie-breaker.
fn qs_combine(mut nodes: Vec<QueryNode>) -> Option<QueryNode> {
match nodes.len() {
0 => None,
1 => nodes.pop(),
_ => Some(QueryNode::DisMax {
queries: nodes,
tie_breaker: 0.0,
}),
}
}
/// Lower a Lucene-style query string into a QueryNode::Bool tree.
///
/// Supports:
/// - `field:value` → Match on that field
/// - `value` → Match on `default_field` / each entry of `fields` (a `dis_max`
/// when there is more than one), else the `"*"` field-less placeholder
/// - `A OR B` → Bool.should
/// - `A AND B` → Bool.must
/// - `+A` must, `-A` must_not
/// - parentheses for grouping
/// - quoted phrases `"foo bar"` → MatchPhrase
/// - range syntax: `field:>N`, `field:>=N`, `field:<N`, `field:<=N`,
/// `field:[A TO B]` (inclusive), `field:{A TO B}` (exclusive), mixed
/// `[A TO B}` forms, and `*` as an open end → Range
///
/// Returns `Ok(None)` for anything unrecognized (caller falls back to the
/// legacy opaque-QueryString path) and `Err` for malformed range syntax —
/// ranges must never silently degrade to a term match.
fn try_lower_query_string(
q: &str,
ctx: QsFields<'_>,
default_op: Option<BoolOperator>,
) -> Result<Option<QueryNode>> {
let Some(tokens) = tokenize_query_string(q)? else {
return Ok(None);
};
if tokens.is_empty() {
return Ok(None);
}
// Range clauses must target a concrete field: resolve unqualified
// ranges against default_field / fields up-front so `>10` with no usable
// target errors instead of degrading to a term match.
// An unqualified range inside `field:( … )` lands on that field (#1298),
// so track which open parens belong to a field group.
let mut has_range = false;
let mut groups: Vec<bool> = Vec::new();
let mut pending_field_group = false;
for t in &tokens {
match t {
QsTok::FieldGroup(_) => pending_field_group = true,
QsTok::LParen => groups.push(std::mem::take(&mut pending_field_group)),
QsTok::RParen => {
groups.pop();
}
_ => {}
}
if let QsTok::Range { field, .. } = t {
has_range = true;
let in_field_group = groups.iter().any(|g| *g);
if field.is_empty() && !in_field_group && !ctx.has_concrete_target() {
return Err(qerr(
"query_string range requires an explicit field (e.g. `price:>10`) or a non-wildcard default_field",
));
}
}
}
let mut pos = 0;
let parsed = parse_qs_or(&tokens, &mut pos, ctx, default_op);
match parsed {
Some(node) if pos == tokens.len() => Ok(Some(node)),
_ if has_range => Err(qerr(format!(
"failed to parse query_string with range syntax: `{q}`"
))),
_ => Ok(None),
}
}
#[derive(Debug, Clone)]
// `Range` (a field + four `Option<Value>` bounds) dwarfs the unit
// operator variants; QsTok is a short-lived per-parse token buffer, so
// boxing it would cost more indirection than the transient size saves.
#[allow(clippy::large_enum_variant)]
enum QsTok {
Term(String, String), // (field, value) — field empty if unqualified
Phrase(String, String), // (field, value)
Range {
// field empty if unqualified
field: String,
gt: Option<Value>,
gte: Option<Value>,
lt: Option<Value>,
lte: Option<Value>,
},
/// `field:` directly before a `(`: the group that follows is scoped to
/// `field` (#1298). Always immediately followed by `LParen`.
FieldGroup(String),
Or,
And,
Not,
Must,
LParen,
RParen,
}
/// Parse a range bound value from a Lucene query_string range expression.
/// Numbers become JSON numbers (so the Range matcher compares numerically)
/// and everything else stays a string — date math / partial-date resolution
/// happens in the callers (`qs_parse_bracket_range` / `qs_parse_cmp_range`),
/// which know whether the bound rounds up or down. Surrounding quotes are
/// stripped; `*` / empty → open end.
fn qs_range_bound(raw: &str) -> Option<Value> {
let mut t = raw.trim();
if t.len() >= 2 && t.starts_with('"') && t.ends_with('"') {
t = &t[1..t.len() - 1];
}
if t.is_empty() || t == "*" {
return None;
}
if let Ok(n) = t.parse::<i64>() {
return Some(Value::from(n));
}
if let Ok(f) = t.parse::<f64>() {
if f.is_finite() {
return Some(Value::from(f));
}
}
Some(Value::String(t.to_string()))
}
/// Apply ES date semantics (rounding + date math, default format) to one
/// query_string range bound.
fn qs_resolve_bound(v: Option<Value>, round_up: bool) -> Result<Option<Value>> {
match v {
Some(b) => Ok(Some(resolve_range_bound(b, round_up, None, None, None)?)),
None => Ok(None),
}
}
/// Parse a bracket range (`[A TO B]` / `{A TO B}` / mixed) starting at byte
/// offset `open` in `q` (pointing at the opening bracket). Returns the token
/// and the byte offset just past the closing bracket.
fn qs_parse_bracket_range(q: &str, field: &str, open: usize) -> Result<(QsTok, usize)> {
let bytes = q.as_bytes();
let inclusive_lo = bytes[open] == b'[';
let mut j = open + 1;
while j < bytes.len() && bytes[j] != b']' && bytes[j] != b'}' {
j += 1;
}
if j >= bytes.len() {
return Err(qerr(format!(
"unterminated range in query_string: `{}`",
&q[open..]
)));
}
let inclusive_hi = bytes[j] == b']';
let inner = &q[open + 1..j];
let parts: Vec<&str> = inner.split_whitespace().collect();
if parts.len() != 3 || !parts[1].eq_ignore_ascii_case("TO") {
return Err(qerr(format!(
"malformed range in query_string: expected `[<lower> TO <upper>]`, got `{}`",
&q[open..=j]
)));
}
let lo = qs_range_bound(parts[0]);
let hi = qs_range_bound(parts[2]);
if lo.is_none() && hi.is_none() {
return Err(qerr(
"query_string range must have at least one non-`*` bound",
));
}
let (mut gt, mut gte, mut lt, mut lte) = (None, None, None, None);
// ES rounding: exclusive lower (`gt`) and inclusive upper (`lte`) round
// up; the other two round down.
if inclusive_lo {
gte = qs_resolve_bound(lo, false)?;
} else {
gt = qs_resolve_bound(lo, true)?;
}
if inclusive_hi {
lte = qs_resolve_bound(hi, true)?;
} else {
lt = qs_resolve_bound(hi, false)?;
}
Ok((
QsTok::Range {
field: field.to_string(),
gt,
gte,
lt,
lte,
},
j + 1,
))
}
/// Parse a comparison range (`>N`, `>=N`, `<N`, `<=N`). `rest` is the text
/// after the `field:` prefix within the scanned token; `i` is the byte offset
/// in `q` where the token scanner stopped — the scanner breaks on `-`/`+`,
/// which are value characters here (negative numbers, dates like
/// `2020-01-01`), so the value is extended from the raw string. Returns the
/// token and the byte offset just past the value.
fn qs_parse_cmp_range(q: &str, field: &str, rest: &str, mut i: usize) -> Result<(QsTok, usize)> {
let bytes = q.as_bytes();
let (op, mut val) = if let Some(v) = rest.strip_prefix(">=") {
(">=", v.to_string())
} else if let Some(v) = rest.strip_prefix("<=") {
("<=", v.to_string())
} else if let Some(v) = rest.strip_prefix('>') {
(">", v.to_string())
} else {
("<", rest[1..].to_string())
};
while i < bytes.len() {
let c = bytes[i] as char;
// ASCII-only: this returns `i` to `tokenize_query_string`, which
// resumes scanning there and slices `&q[..]` from it. Stopping on a
// Latin-1-looking continuation byte (0xA0) would hand back an offset in
// the middle of a character and panic the caller's slice — see the
// invariant documented on `tokenize_query_string`.
if c.is_ascii_whitespace() || c == '(' || c == ')' {
break;
}
val.push(c);
i += 1;
}
let bound = qs_range_bound(&val).ok_or_else(|| {
qerr(format!(
"query_string range `{field}:{op}` is missing a value"
))
})?;
let (mut gt, mut gte, mut lt, mut lte) = (None, None, None, None);
// ES rounding: `>` and `<=` round the bound up, `>=` and `<` round down.
match op {
">" => gt = Some(resolve_range_bound(bound, true, None, None, None)?),
">=" => gte = Some(resolve_range_bound(bound, false, None, None, None)?),
"<" => lt = Some(resolve_range_bound(bound, false, None, None, None)?),
_ => lte = Some(resolve_range_bound(bound, true, None, None, None)?),
}
Ok((
QsTok::Range {
field: field.to_string(),
gt,
gte,
lt,
lte,
},
i,
))
}
/// Tokenize a Lucene query string. `Ok(None)` means "can't tokenize — fall
/// back to the opaque QueryString path"; `Err` is a hard parse error
/// (malformed range syntax must not degrade to a term match).
/// Tokenise a Lucene `query_string`.
///
/// SAFETY-OF-SLICING INVARIANT: this scanner walks BYTES — `bytes[i] as char`
/// reinterprets each byte as Latin-1 — but slices `&q[start..i]` as a `&str`.
/// That is only sound if every position it can stop at is a character
/// boundary, which is why every delimiter test below is `is_ascii_*`: the bytes
/// of a multi-byte UTF-8 character are all >= 0x80, so an ASCII test can never
/// match one, and the scan can never stop inside a character.
///
/// It used to test `is_whitespace()`, which is true for Latin-1 NBSP (0xA0) —
/// a *continuation byte*. `query_string: "…_٠…"` (U+0660, encoded D9 A0) broke
/// the token scan between the two bytes and panicked on the slice. The release
/// profile sets `panic = "abort"`, so that was not a 400 on an unauthenticated
/// `?q=`, it was the process. Found by the `query_string` fuzz target (#207).
///
/// Nothing is lost by the narrowing: the only non-ASCII bytes `is_whitespace()`
/// accepted were 0x85 and 0xA0, and both are continuation bytes, never a
/// standalone character in valid UTF-8. Real Unicode whitespace (U+3000 and
/// friends) was already token content here.
fn tokenize_query_string(q: &str) -> Result<Option<Vec<QsTok>>> {
let bytes = q.as_bytes();
let mut out: Vec<QsTok> = Vec::new();
let mut i = 0;
while i < bytes.len() {
let c = bytes[i] as char;
if c.is_ascii_whitespace() {
i += 1;
continue;
}
if c == '(' {
out.push(QsTok::LParen);
i += 1;
continue;
}
if c == ')' {
out.push(QsTok::RParen);
i += 1;
continue;
}
if c == '+' {
out.push(QsTok::Must);
i += 1;
continue;
}
if c == '-' {
out.push(QsTok::Not);
i += 1;
continue;
}
// Quoted phrase — optional `field:"value"` prefix handled below.
if c == '"' {
let start = i + 1;
let mut j = start;
while j < bytes.len() && bytes[j] as char != '"' {
j += 1;
}
if j >= bytes.len() {
return Ok(None);
}
let val = q[start..j].to_string();
out.push(QsTok::Phrase(String::new(), val));
i = j + 1;
continue;
}
// Unqualified bracket range on the default field: `[A TO B]` / `{A TO B}`.
if c == '[' || c == '{' {
let (tok, next) = qs_parse_bracket_range(q, "", i)?;
out.push(tok);
i = next;
continue;
}
// Bare token (possibly field:value or field:"value").
//
// NOTE: `+` / `-` are Lucene unary operators ONLY at the start of a
// clause (handled by the top-of-loop checks above, which can only
// fire at a fresh scan position). INSIDE a bare token they are
// literal characters — `model:claude-haiku-4-5` is ONE term, not
// `model:claude NOT haiku NOT 4 NOT 5`. Breaking on mid-token `-`
// shredded hyphenated keyword values and made e.g.
// `query_string: "model:claude-haiku-4-5 AND status:ok"` match a
// garbage clause tree instead of the two field terms.
let start = i;
while i < bytes.len() {
let ch = bytes[i] as char;
// ASCII-only, per the slicing invariant on this function.
if ch.is_ascii_whitespace() || ch == '(' || ch == ')' {
break;
}
i += 1;
}
let tok = &q[start..i];
// Keywords OR / AND / NOT (case-insensitive, must stand alone).
match tok {
"OR" | "or" | "||" => {
out.push(QsTok::Or);
continue;
}
"AND" | "and" | "&&" => {
out.push(QsTok::And);
continue;
}
"NOT" | "not" | "!" => {
out.push(QsTok::Not);
continue;
}
_ => {}
}
// Lucene query_string unescapes `\X` → `X` for any char X;
// common cases are `\/`, `\+`, `\-`, `\(`, etc. Unescape here so
// the downstream matcher compares against the literal value
// rather than a value-with-stray-backslash.
fn unescape_qs(s: &str) -> String {
let mut out = String::with_capacity(s.len());
let mut chars = s.chars();
while let Some(c) = chars.next() {
if c == '\\' {
if let Some(nxt) = chars.next() {
out.push(nxt);
}
} else {
out.push(c);
}
}
out
}
// field:value or field:"value"
if let Some(colon) = tok.find(':') {
let field = &tok[..colon];
let rest = &tok[colon + 1..];
if let Some(after_quote) = rest.strip_prefix('"') {
// Consume continuation until matching quote (may have been split).
let mut buf = after_quote.to_string();
if buf.ends_with('"') {
buf.pop();
out.push(QsTok::Phrase(field.to_string(), buf));
} else {
// Rejoin from original string.
let mut j = i;
while j < bytes.len() && bytes[j] as char != '"' {
j += 1;
}
if j >= bytes.len() {
return Ok(None);
}
let whole = format!("{} {}", buf, &q[i..j]);
out.push(QsTok::Phrase(field.to_string(), whole));
i = j + 1;
}
} else if rest.starts_with('[') || rest.starts_with('{') {
// field:[A TO B] / field:{A TO B} — the bare-token scan stops
// at whitespace, so re-scan the raw string from the bracket.
let (rtok, next) = qs_parse_bracket_range(q, field, start + colon + 1)?;
out.push(rtok);
i = next;
} else if rest.starts_with('>') || rest.starts_with('<') {
// field:>N / field:>=N / field:<N / field:<=N
let (rtok, next) = qs_parse_cmp_range(q, field, rest, i)?;
out.push(rtok);
i = next;
} else if rest.is_empty()
&& q[i..]
.trim_start_matches(|c: char| c.is_ascii_whitespace())
.starts_with('(')
{
// `field:(a OR b)` (also `field: (…)`): the bare-token scan
// stopped at the `(`, leaving `field:` with no value. Lucene
// scopes the whole group to `field`; before #1298 this became
// an empty-valued term and the group searched every field.
out.push(QsTok::FieldGroup(field.to_string()));
while bytes[i].is_ascii_whitespace() {
i += 1;
}
} else {
out.push(QsTok::Term(field.to_string(), unescape_qs(rest)));
}
} else if tok.starts_with('>') || tok.starts_with('<') {
// Unqualified comparison range on the default field: `>N`, `<=N`, …
let (rtok, next) = qs_parse_cmp_range(q, "", tok, i)?;
out.push(rtok);
i = next;
} else {
out.push(QsTok::Term(String::new(), unescape_qs(tok)));
}
}
Ok(Some(out))
}
/// How one clause of a query-string boolean takes part in it.
#[derive(Clone, Copy, PartialEq)]
enum QsOccur {
Must,
Should,
MustNot,
}
/// The conjunction written before a clause.
#[derive(Clone, Copy, PartialEq)]
enum QsConj {
None,
And,
Or,
}
/// Parse one boolean level of a query string: clauses up to the end of the
/// input or the closing `)` of the current group.
///
/// Every clause of one level lands in ONE boolean, with an occur decided the
/// way Lucene's classic query parser decides it (`QueryParserBase.addClause`,
/// Apache-2.0; approach only, nothing copied), which is what ES 8.13.4 runs:
///
/// - `AND` before a clause makes the clause before it required too, unless
/// that one is prohibited;
/// - with `default_operator: AND`, `OR` before a clause makes the clause
/// before it optional, unless it is prohibited;
/// - `-` / `NOT` make a clause prohibited (MUST_NOT) whatever the operator;
/// - otherwise, under `OR` a clause is required only with `+` or after
/// `AND`; under `AND` every clause not introduced by `OR` is required.
///
/// So `kiwi OR lime AND plum` is `kiwi +lime +plum`, not
/// `kiwi OR (lime AND plum)`. A prohibited clause excludes from the whole
/// level: before #1299, `alpha -beta` built `alpha OR (NOT beta)`, whose
/// pure-negative branch matched every document without `beta`.
fn parse_qs_or(
toks: &[QsTok],
pos: &mut usize,
ctx: QsFields<'_>,
default_op: Option<BoolOperator>,
) -> Option<QueryNode> {
let default_and = matches!(default_op, Some(BoolOperator::And));
let mut clauses: Vec<(QsOccur, QueryNode)> = Vec::new();
while *pos < toks.len() && !matches!(toks[*pos], QsTok::RParen) {
let mut conj = QsConj::None;
while let Some(t) = toks.get(*pos) {
match t {
QsTok::And => conj = QsConj::And,
QsTok::Or => conj = QsConj::Or,
_ => break,
}
*pos += 1;
}
let (mut req_mod, mut not_mod) = (false, false);
while let Some(t) = toks.get(*pos) {
match t {
QsTok::Must => req_mod = true,
QsTok::Not => not_mod = true,
_ => break,
}
*pos += 1;
}
// A dangling operator (`kiwi AND`, `kiwi -`) has no clause to apply
// to: decline, and the caller falls back to the opaque node.
// `default_op` is threaded so a `field:( … )` group inside a clause
// (#1298) keeps the operator in effect.
let node = parse_qs_unary(toks, pos, ctx, default_op)?;
if let Some(prev) = clauses.last_mut() {
if prev.0 != QsOccur::MustNot {
if conj == QsConj::And {
prev.0 = QsOccur::Must;
} else if conj == QsConj::Or && default_and {
prev.0 = QsOccur::Should;
}
}
}
let required = if default_and {
!not_mod && conj != QsConj::Or
} else {
req_mod || (conj == QsConj::And && !not_mod)
};
let occur = if not_mod {
QsOccur::MustNot
} else if required {
QsOccur::Must
} else {
QsOccur::Should
};
clauses.push((occur, node));
}
if clauses.len() == 1 && clauses[0].0 != QsOccur::MustNot {
return clauses.pop().map(|(_, n)| n);
}
if clauses.is_empty() {
return None;
}
let (mut must, mut should, mut must_not) = (Vec::new(), Vec::new(), Vec::new());
for (occur, node) in clauses {
match occur {
QsOccur::Must => must.push(node),
QsOccur::Should => should.push(node),
QsOccur::MustNot => must_not.push(node),
}
}
// With a required clause, the optional ones only add score (Lucene and
// ES `bool`); with none, at least one of them must match.
let minimum_should_match =
(must.is_empty() && !should.is_empty()).then_some(MinShouldMatch::Fixed(1));
Some(QueryNode::Bool {
must,
should,
must_not,
filter: vec![],
minimum_should_match,
})
}
fn parse_qs_unary(
toks: &[QsTok],
pos: &mut usize,
ctx: QsFields<'_>,
default_op: Option<BoolOperator>,
) -> Option<QueryNode> {
if *pos >= toks.len() {
return None;
}
match toks[*pos].clone() {
QsTok::FieldGroup(field) => {
// `field:( … )` (#1298): parse the group as if `field` were the
// only default field, so every unqualified clause inside it
// (terms, phrases, wildcards, ranges, nested groups) targets
// `field`. A clause inside that names its own field keeps it,
// as in ES. The tokenizer always emits `LParen` next.
*pos += 1;
if !matches!(toks.get(*pos), Some(QsTok::LParen)) {
return None;
}
let scoped = QsFields {
default_field: Some(&field),
fields: &[],
// Leniency is decided once per `query_string` (#1284), so the
// scoped group inherits the parent clause's setting.
lenient: ctx.lenient,
};
parse_qs_unary(toks, pos, scoped, default_op)
}
QsTok::LParen => {
*pos += 1;
// Bound paren-nesting depth. The shared thread-local `QUERY_DEPTH`
// is already at 1 from the outer `parse_query` call that dispatched
// to `parse_query_string` → `try_lower_query_string`. Each `LParen`
// recurses `parse_qs_or → parse_qs_and → parse_qs_unary`, so without
// this guard a ~100 k-paren query string overflows the tokio worker
// stack (default 2 MiB) and aborts the process with SIGSEGV — not
// catchable by `catch_unwind`. On overflow we return `None`, which
// `try_lower_query_string` turns into a graceful fallback to the
// opaque `QueryNode::QueryString` path (iterative tokenizer, no
// recursion). The guard decrements on drop when this arm returns.
let _depth_guard = DepthGuard::enter().ok()?;
// `default_operator` applies inside a group too: on ES 8.13.4
// `(alpha beta)` with `AND` needs both terms. Passing `None`
// here made every group implicitly OR.
let n = parse_qs_or(toks, pos, ctx, default_op)?;
if *pos >= toks.len() || !matches!(toks[*pos], QsTok::RParen) {
return None;
}
*pos += 1;
Some(n)
}
QsTok::Term(field, value) => {
*pos += 1;
// A clause that named its own field keeps it; one that did not is
// searched over every target `default_field` / `fields` supplies,
// combined by `qs_combine`.
let targets = qs_targets(&field, ctx);
// A bare term containing `*` or `?` is a Lucene wildcard —
// emit a Wildcard query so `q=shor*` / `q=te?t` match text
// tokens with the expected substitution semantics.
//
// ES lowercases wildcard/prefix terms in `query_string` (the field's
// search analyzer normalizes them) — e.g. `q=field:BA*` matches the
// indexed lowercased token `bar`. The raw `wildcard` query does NOT
// analyze its pattern (case-sensitive), so this lowering lives HERE
// in the query_string path only. Harmless for keyword fields, whose
// FST-wildcard route case-folds both sides regardless.
if value.contains('*') || value.contains('?') {
// ES's query_string parser produces a WildcardQuery (or
// PrefixQuery for a trailing `*`) with the default
// CONSTANT_SCORE rewrite — every match scores a flat 1.0
// (× boost), no BM25 — exactly like the standalone
// `wildcard` / `prefix` queries (4c69c05). Live-verified
// vs ES 8.13.4: `model:claude-*` → max_score 1.0,
// `model:claude-* AND status:ok` → 1.0 + BM25(status:ok).
// `constant_score: true` also admits the keyword shape to
// the columnar Filtered plan (seq-ascending → ES tie order).
let lowered = value.to_lowercase();
return qs_combine(
targets
.into_iter()
.map(|(f, boost)| QueryNode::Wildcard {
field: f,
value: lowered.clone(),
boost,
constant_score: true,
case_insensitive: true,
})
.collect(),
);
}
qs_combine(
targets
.into_iter()
.map(|(f, boost)| QueryNode::Match {
field: f,
query: value.clone(),
operator: BoolOperator::Or,
analyzer: None,
boost,
minimum_should_match: None,
lenient: ctx.lenient,
})
.collect(),
)
}
QsTok::Phrase(field, value) => {
*pos += 1;
qs_combine(
qs_targets(&field, ctx)
.into_iter()
.map(|(f, boost)| QueryNode::MatchPhrase {
field: f,
query: value.clone(),
slop: 0,
analyzer: None,
boost,
lenient: ctx.lenient,
})
.collect(),
)
}
QsTok::Range {
field,
gt,
gte,
lt,
lte,
} => {
*pos += 1;
// Unqualified ranges with no usable target were already rejected
// in try_lower_query_string. A pattern entry in `fields` has no
// meaning for a range, so those targets are dropped here rather
// than turned into a `Range` on the literal field name `"*"`.
let targets: Vec<(String, Option<f32>)> = qs_targets(&field, ctx)
.into_iter()
.filter(|(f, _)| !field.is_empty() || !f.contains('*'))
.collect();
qs_combine(
targets
.into_iter()
.map(|(f, boost)| QueryNode::Range {
field: f,
gte: gte.clone(),
gt: gt.clone(),
lte: lte.clone(),
lt: lt.clone(),
boost,
lenient: ctx.lenient,
})
.collect(),
)
}
_ => None,
}
}
fn parse_fuzzy(params: &Value) -> Result<QueryNode> {
let obj = params
.as_object()
.ok_or_else(|| qerr("`fuzzy` must be an object"))?;
if obj.len() != 1 {
return invalid("`fuzzy` query must have exactly one field");
}
let (field, raw) = obj.iter().next().unwrap();
let field = field.clone();
// Shorthand: {"fuzzy": {"name": "prodct"}}
if let Some(value) = raw.as_str() {
return Ok(QueryNode::Fuzzy {
field,
value: value.to_string(),
fuzziness: Fuzziness::Auto,
case_insensitive: false,
prefix_length: 0,
});
}
let inner = raw
.as_object()
.ok_or_else(|| qerr("`fuzzy` field value must be a string or object"))?;
let value = string_field(inner, "value")?;
let fuzziness = match inner.get("fuzziness") {
Some(Value::String(s)) if s.to_uppercase() == "AUTO" => Fuzziness::Auto,
Some(Value::String(s)) => {
let n = s.parse::<u32>().map_err(|_| {
qerr(format!(
"`fuzzy.fuzziness` must be 'AUTO' or an integer, got '{s}'"
))
})?;
Fuzziness::Fixed(n)
}
Some(Value::Number(n)) => {
let n = n
.as_u64()
.ok_or_else(|| qerr("`fuzzy.fuzziness` must be a non-negative integer"))?
as u32;
Fuzziness::Fixed(n)
}
None => Fuzziness::Auto,
_ => return invalid("`fuzzy.fuzziness` must be 'AUTO' or an integer"),
};
let case_insensitive = inner
.get("case_insensitive")
.and_then(|v| v.as_bool())
.unwrap_or(false);
let prefix_length = parse_prefix_length(inner);
Ok(QueryNode::Fuzzy {
field,
value,
fuzziness,
case_insensitive,
prefix_length,
})
}
/// #848: read ES `prefix_length` off a fuzzy/match parameter object. Accepts a
/// non-negative number or its string spelling; defaults to `0` (no constraint).
fn parse_prefix_length(obj: &serde_json::Map<String, Value>) -> usize {
match obj.get("prefix_length") {
Some(Value::Number(n)) => n.as_u64().unwrap_or(0) as usize,
Some(Value::String(s)) => s.parse::<usize>().unwrap_or(0),
_ => 0,
}
}
fn parse_regexp(params: &Value) -> Result<QueryNode> {
let obj = params
.as_object()
.ok_or_else(|| qerr("`regexp` must be an object"))?;
if obj.len() != 1 {
return invalid("`regexp` query must have exactly one field");
}
let (field, raw) = obj.iter().next().unwrap();
let field = field.clone();
if let Some(pattern) = raw.as_str() {
return Ok(QueryNode::Regexp {
field,
pattern: pattern.to_string(),
case_insensitive: false,
});
}
let inner = raw
.as_object()
.ok_or_else(|| qerr("`regexp` field value must be a string or object"))?;
let pattern = string_field(inner, "value")?;
let case_insensitive = inner
.get("case_insensitive")
.and_then(|v| v.as_bool())
.unwrap_or(false);
Ok(QueryNode::Regexp {
field,
pattern,
case_insensitive,
})
}
fn parse_match_phrase_prefix(params: &Value) -> Result<QueryNode> {
let obj = params
.as_object()
.ok_or_else(|| qerr("`match_phrase_prefix` must be an object"))?;
if obj.len() != 1 {
return invalid("`match_phrase_prefix` query must have exactly one field");
}
let (field, raw) = obj.iter().next().unwrap();
let field = field.clone();
// Empty query string → match_none, not a parse error. See `parse_match`.
// This is exactly what Kibana's own SavedObjectsClient `_find` builds
// for a trailing-`*` search term.
if matches!(raw, Value::String(s) if s.is_empty()) {
return Ok(QueryNode::MatchNone);
}
// Shorthand forms: `match_phrase_prefix: {field: "value"}`, `{field:
// 42}`, `{field: true}` — ES silently stringifies non-strings, same as
// `match` (see `scalar_to_string`).
if let Some(query) = scalar_to_string(raw) {
return Ok(QueryNode::MatchPhrasePrefix {
field,
query,
max_expansions: 50,
slop: 0,
});
}
let inner = raw
.as_object()
.ok_or_else(|| qerr("`match_phrase_prefix` field value must be a string or object"))?;
if matches!(inner.get("query"), Some(Value::String(s)) if s.is_empty()) {
return Ok(QueryNode::MatchNone);
}
let query = inner
.get("query")
.and_then(scalar_to_string)
.ok_or_else(|| qerr("`match_phrase_prefix.query` must be a non-empty scalar"))?;
// `max_expansions` used to be read with `as_u64().unwrap_or(50)`, so
// `-1`, `"7"` and `7.0` all silently became 50 — the same accept-and-ignore
// (#204) as the dropped `slop` below, one line apart. It is now the shared
// parse: a value we cannot read is a 400, and `0` stays accepted because
// ES accepts it *here* (it rejects it on `multi_match`; the asymmetry is
// ES's own, see `parse_max_expansions`).
let max_expansions = parse_max_expansions(
inner.get("max_expansions"),
"match_phrase_prefix",
/* allow_zero */ true,
)?;
// `slop` used to be read nowhere here, so
// `{"match_phrase_prefix": {"f": {"query": …, "slop": 2}}}` was accepted
// and answered as slop 0 — accept-and-ignore (#204 class), and a silent
// disagreement with the `multi_match` form of the same query. ES parses
// and honours it (`MatchPhrasePrefixQueryBuilder.fromXContent` →
// `MatchQueryParser.setPhraseSlop`), and both XERJ evaluators now carry
// it: `PhrasePrefixQuery.slop` on segments, the sloppy prefix walk in
// the stored-doc scan.
let slop = parse_phrase_slop(inner.get("slop"), "match_phrase_prefix")?;
Ok(QueryNode::MatchPhrasePrefix {
field,
query,
max_expansions,
slop,
})
}
#[derive(Debug, Clone, PartialEq)]
enum SqsTok {
Term(String),
Phrase(String),
And, // `+`
Or, // `|`
Not, // `-`
LParen, // `(`
RParen, // `)`
}
fn unescape_sqs(s: &str) -> String {
let mut out = String::with_capacity(s.len());
let mut chars = s.chars();
while let Some(c) = chars.next() {
if c == '\\' {
if let Some(nxt) = chars.next() {
out.push(nxt);
}
} else {
out.push(c);
}
}
out
}
fn tokenize_simple_query_string(q: &str) -> Vec<SqsTok> {
let bytes = q.as_bytes();
let mut out: Vec<SqsTok> = Vec::new();
let mut i = 0;
while i < bytes.len() {
let c = bytes[i] as char;
if c.is_ascii_whitespace() {
i += 1;
continue;
}
if c == '(' {
out.push(SqsTok::LParen);
i += 1;
continue;
}
if c == ')' {
out.push(SqsTok::RParen);
i += 1;
continue;
}
if c == '|' {
i += 1;
if i < bytes.len() && bytes[i] as char == '|' {
i += 1;
}
out.push(SqsTok::Or);
continue;
}
if c == '+' {
out.push(SqsTok::And);
i += 1;
continue;
}
if c == '-' {
out.push(SqsTok::Not);
i += 1;
continue;
}
if c == '"' {
let start = i + 1;
let mut j = start;
while j < bytes.len() {
if bytes[j] as char == '\\' && j + 1 < bytes.len() {
j += 2;
} else if bytes[j] as char == '"' {
break;
} else {
j += 1;
}
}
let phrase = unescape_sqs(&q[start..j]);
if !phrase.is_empty() {
out.push(SqsTok::Phrase(phrase));
}
if j < bytes.len() && bytes[j] as char == '"' {
i = j + 1;
} else {
i = j;
}
continue;
}
// Bare term: read until whitespace, '(', ')', '|', or '"'
// NOTE: '+' or '-' inside a term (e.g. "c++", "node-fetch", "2024-05-01")
// is part of the term, so we do not stop on '+' or '-' mid-term.
let start = i;
while i < bytes.len() {
let ch = bytes[i] as char;
if ch.is_ascii_whitespace() || ch == '(' || ch == ')' || ch == '|' || ch == '"' {
break;
}
if ch == '\\' && i + 1 < bytes.len() {
i += 2;
continue;
}
i += 1;
}
let tok = unescape_sqs(&q[start..i]);
if !tok.is_empty() {
out.push(SqsTok::Term(tok));
}
}
out
}
fn parse_sqs_unary(
toks: &[SqsTok],
pos: &mut usize,
fields: &[String],
lenient: bool,
default_and: bool,
) -> Option<QueryNode> {
while *pos < toks.len() {
match &toks[*pos] {
SqsTok::LParen => {
*pos += 1;
let _depth_guard = DepthGuard::enter().ok()?;
let inner = parse_sqs_level(toks, pos, fields, lenient, default_and);
if *pos < toks.len() && matches!(toks[*pos], SqsTok::RParen) {
*pos += 1;
}
return inner;
}
SqsTok::RParen => {
*pos += 1;
}
SqsTok::Term(term) => {
*pos += 1;
return Some(make_simple_query_node(term, false, fields, lenient));
}
SqsTok::Phrase(phrase) => {
*pos += 1;
return Some(make_simple_query_node(phrase, true, fields, lenient));
}
_ => return None,
}
}
None
}
fn parse_sqs_level(
toks: &[SqsTok],
pos: &mut usize,
fields: &[String],
lenient: bool,
default_and: bool,
) -> Option<QueryNode> {
let mut clauses: Vec<(QsOccur, QueryNode)> = Vec::new();
while *pos < toks.len() && !matches!(toks[*pos], SqsTok::RParen) {
let mut conj = QsConj::None;
let mut req_mod = false;
let mut not_mod = false;
while let Some(t) = toks.get(*pos) {
match t {
SqsTok::And => {
if clauses.is_empty() || conj != QsConj::None {
req_mod = true;
} else {
conj = QsConj::And;
}
}
SqsTok::Or => {
conj = QsConj::Or;
}
SqsTok::Not => {
not_mod = true;
}
_ => break,
}
*pos += 1;
}
if *pos >= toks.len() || matches!(toks[*pos], SqsTok::RParen) {
break;
}
let Some(node) = parse_sqs_unary(toks, pos, fields, lenient, default_and) else {
continue;
};
if let Some(prev) = clauses.last_mut() {
if prev.0 != QsOccur::MustNot {
if conj == QsConj::And {
prev.0 = QsOccur::Must;
} else if conj == QsConj::Or && default_and {
prev.0 = QsOccur::Should;
}
}
}
let required = if default_and {
!not_mod && conj != QsConj::Or
} else {
req_mod || (conj == QsConj::And && !not_mod)
};
let occur = if not_mod {
QsOccur::MustNot
} else if required {
QsOccur::Must
} else {
QsOccur::Should
};
clauses.push((occur, node));
}
if clauses.is_empty() {
return None;
}
let (mut must, mut should, mut must_not) = (Vec::new(), Vec::new(), Vec::new());
for (occur, node) in clauses {
match occur {
QsOccur::Must => must.push(node),
QsOccur::Should => should.push(node),
QsOccur::MustNot => must_not.push(node),
}
}
let minimum_should_match =
(must.is_empty() && !should.is_empty()).then_some(MinShouldMatch::Fixed(1));
Some(QueryNode::Bool {
must,
should,
must_not,
filter: Vec::new(),
minimum_should_match,
})
}
fn parse_simple_query_string(params: &Value) -> Result<QueryNode> {
let obj = params
.as_object()
.ok_or_else(|| qerr("`simple_query_string` must be an object"))?;
let query = string_field(obj, "query")?;
let fields: Vec<String> = obj
.get("fields")
.and_then(Value::as_array)
.map(|arr| {
arr.iter()
.filter_map(Value::as_str)
.map(str::to_string)
.collect()
})
.unwrap_or_default();
// ES default_operator: "or" (default) means tokens go into `should`
// with `minimum_should_match`; "and" puts them all into `must`.
let default_operator = obj
.get("default_operator")
.and_then(Value::as_str)
.unwrap_or("or")
.to_lowercase();
let default_and = default_operator == "and";
let mm: Option<MinShouldMatch> = obj
.get("minimum_should_match")
.and_then(|v| parse_min_should_match(v).ok());
// #1284: same default as `multi_match` / `query_string`.
let lenient = parse_lenient(obj.get("lenient")).unwrap_or_else(|| targets_every_field(&fields));
let toks = tokenize_simple_query_string(&query);
let mut pos = 0;
let parsed = parse_sqs_level(&toks, &mut pos, &fields, lenient, default_and);
let node = match parsed {
Some(QueryNode::Bool {
must,
should,
must_not,
filter,
minimum_should_match: auto_mm,
}) => {
let final_mm = if mm.is_some() { mm } else { auto_mm };
QueryNode::Bool {
must,
should,
must_not,
filter,
minimum_should_match: final_mm,
}
}
Some(other) => other,
None => make_simple_query_node(&query, false, &fields, lenient),
};
Ok(node)
}
/// Build a Match, MatchPhrase, or MultiMatch node for a term in a simple_query_string.
fn make_simple_query_node(
term: &str,
is_phrase: bool,
fields: &[String],
lenient: bool,
) -> QueryNode {
if is_phrase {
if fields.len() == 1 {
QueryNode::MatchPhrase {
field: fields[0].clone(),
query: term.to_string(),
slop: 0,
analyzer: None,
boost: None,
lenient,
}
} else if fields.is_empty() {
QueryNode::QueryString {
query: format!("\"{}\"", term),
default_field: None,
default_operator: None,
boost: None,
}
} else {
QueryNode::MultiMatch {
fields: fields.to_vec(),
query: term.to_string(),
match_type: crate::ast::MultiMatchType::Phrase,
operator: None,
analyzer: None,
boost: None,
slop: 0,
max_expansions: 50,
lenient,
}
}
} else if targets_every_field(fields) {
// No fields, or the bare `"*"` pattern (#2427). ES reads `["*"]` as
// "every searchable field" — it is also what an absent `fields`
// falls back to (`index.query.default_field` defaults to `*`) — so
// both spellings lower to the same field-less placeholder, which the
// engine projects onto every mapped text field of each segment's
// inverted index.
//
// `["*"]` used to lower to `Match { field: "*" }` instead. No FTS
// projection exists for a literal `"*"` field, so that node forced
// the per-document stored-section scan on EVERY segment: on the
// 1 GB autoindex gate one 5-hit query walked ~1.2M stored docs in
// pg-docs and ran into the 30 s request deadline (raw-surface p95
// 30.1 s). A `"*^2"` boost has no field to attach to on this node
// and is dropped, as it is for the phrase placeholder below.
//
// Quoted phrases keep their own arm above: the field-less
// placeholder is bag-of-words on the FTS path, so routing a phrase
// through it would loosen phrase matching.
QueryNode::QueryString {
query: term.to_string(),
default_field: None,
default_operator: None,
boost: None,
}
} else if fields.len() == 1 {
QueryNode::Match {
field: fields[0].clone(),
query: term.to_string(),
operator: BoolOperator::Or,
analyzer: None,
boost: None,
minimum_should_match: None,
lenient,
}
} else {
QueryNode::MultiMatch {
fields: fields.to_vec(),
query: term.to_string(),
match_type: crate::ast::MultiMatchType::BestFields,
operator: None,
analyzer: None,
boost: None,
slop: 0,
max_expansions: 50,
lenient,
}
}
}
/// Parse a `geo_distance` query.
///
/// ES format:
/// ```json
/// {
/// "geo_distance": {
/// "distance": "10km",
/// "location": { "lat": 40.7, "lon": -74.0 }
/// }
/// }
/// ```
///
/// The field name is inferred as the key that is not `"distance"`.
fn parse_geo_distance(params: &Value) -> Result<QueryNode> {
let obj = params
.as_object()
.ok_or_else(|| qerr("`geo_distance` must be an object"))?;
// Parse the distance string (e.g. "10km", "5mi").
let distance_str = obj
.get("distance")
.and_then(|v| v.as_str())
.ok_or_else(|| qerr("`geo_distance` requires a `distance` field"))?;
let distance_km = parse_distance_km(distance_str)?;
// Find the field key (the one that is not "distance").
let field_entry = obj
.iter()
.find(|(k, _)| k.as_str() != "distance")
.ok_or_else(|| qerr("`geo_distance` requires a geo_point field"))?;
let field = field_entry.0.clone();
let location = field_entry.1;
let (lat, lon) = parse_lat_lon(location)?;
Ok(QueryNode::GeoDistance {
field,
lat,
lon,
distance_km,
})
}
/// Parse a `geo_bounding_box` query.
///
/// ES format:
/// ```json
/// {
/// "geo_bounding_box": {
/// "location": {
/// "top_left": { "lat": 40.8, "lon": -74.0 },
/// "bottom_right": { "lat": 40.7, "lon": -73.9 }
/// }
/// }
/// }
/// ```
fn parse_geo_bounding_box(params: &Value) -> Result<QueryNode> {
let obj = params
.as_object()
.ok_or_else(|| qerr("`geo_bounding_box` must be an object"))?;
// Find the field key (anything that is not a known option key).
let known_keys = ["_name", "validation_method", "ignore_unmapped"];
let field_entry = obj
.iter()
.find(|(k, _)| !known_keys.contains(&k.as_str()))
.ok_or_else(|| qerr("`geo_bounding_box` requires a geo_point field"))?;
let field = field_entry.0.clone();
let bounds = field_entry.1;
let bounds_obj = bounds
.as_object()
.ok_or_else(|| qerr("`geo_bounding_box` field value must be an object"))?;
let tl_val = bounds_obj
.get("top_left")
.ok_or_else(|| qerr("`geo_bounding_box` requires `top_left`"))?;
let br_val = bounds_obj
.get("bottom_right")
.ok_or_else(|| qerr("`geo_bounding_box` requires `bottom_right`"))?;
let top_left = parse_lat_lon(tl_val)?;
let bottom_right = parse_lat_lon(br_val)?;
Ok(QueryNode::GeoBoundingBox {
field,
top_left,
bottom_right,
})
}
/// Parse a distance string like "10km", "5mi", "100m" into kilometres.
fn parse_distance_km(s: &str) -> Result<f64> {
let s = s.trim();
if let Some(km) = s.strip_suffix("km") {
km.trim()
.parse::<f64>()
.map_err(|_| qerr(format!("invalid distance: `{s}`")))
} else if let Some(mi) = s.strip_suffix("mi") {
mi.trim()
.parse::<f64>()
.map(|m| m * 1.60934)
.map_err(|_| qerr(format!("invalid distance: `{s}`")))
} else if let Some(m) = s.strip_suffix('m') {
m.trim()
.parse::<f64>()
.map(|m| m / 1000.0)
.map_err(|_| qerr(format!("invalid distance: `{s}`")))
} else {
// Bare number interpreted as kilometres.
s.parse::<f64>()
.map_err(|_| qerr(format!("invalid distance: `{s}`")))
}
}
/// Parse a lat/lon value from various ES formats:
/// - `{ "lat": 40.7, "lon": -74.0 }`
/// - `[lon, lat]` (GeoJSON order)
/// - `"40.7,-74.0"` (lat,lon string)
fn parse_lat_lon(value: &Value) -> Result<(f64, f64)> {
match value {
Value::Object(obj) => {
let lat = obj
.get("lat")
.and_then(|v| v.as_f64())
.ok_or_else(|| qerr("geo_point object requires `lat` as a number"))?;
let lon = obj
.get("lon")
.and_then(|v| v.as_f64())
.ok_or_else(|| qerr("geo_point object requires `lon` as a number"))?;
Ok((lat, lon))
}
Value::Array(arr) if arr.len() == 2 => {
// GeoJSON order: [lon, lat]
let lon = arr[0]
.as_f64()
.ok_or_else(|| qerr("geo_point array element must be a number"))?;
let lat = arr[1]
.as_f64()
.ok_or_else(|| qerr("geo_point array element must be a number"))?;
Ok((lat, lon))
}
Value::String(s) => {
// "lat,lon" string
let parts: Vec<&str> = s.splitn(2, ',').collect();
if parts.len() != 2 {
return invalid(format!("geo_point string must be `lat,lon`, got `{s}`"));
}
let lat = parts[0]
.trim()
.parse::<f64>()
.map_err(|_| qerr(format!("invalid lat in `{s}`")))?;
let lon = parts[1]
.trim()
.parse::<f64>()
.map_err(|_| qerr(format!("invalid lon in `{s}`")))?;
Ok((lat, lon))
}
_ => invalid("geo_point must be an object {lat,lon}, array [lon,lat], or 'lat,lon' string"),
}
}
// ─────────────────────────────────────────────────────────────────────────────
// Compound parsers
// ─────────────────────────────────────────────────────────────────────────────
fn parse_bool(params: &Value) -> Result<QueryNode> {
let obj = params
.as_object()
.ok_or_else(|| qerr("`bool` must be an object"))?;
let must = parse_clause_list(obj, "must")?;
let should = parse_clause_list(obj, "should")?;
let must_not = parse_clause_list(obj, "must_not")?;
let filter = parse_clause_list(obj, "filter")?;
// A `boost` on a compound clause must PROPAGATE into the leaf
// weights (Lucene multiplies the parent boost into each child's
// weight — weights compose multiplicatively down the tree).
// Previously dropped silently. The `Boosted` wrapper carries it;
// every matching/filter path peels the wrapper, and the scored
// paths compose it into the leaves.
let boost = obj
.get("boost")
.and_then(|v| v.as_f64())
.map(|b| b as f32)
.filter(|b| *b != 1.0);
// #681: honor `_name` on a bool clause (a top-level sibling of
// must/should/must_not/filter), so a named bool surfaces in
// matched_queries when it matches. `parse_bool` ignores unknown keys, so
// this was silently dropped before.
let name = obj
.get("_name")
.and_then(|v| v.as_str())
.map(str::to_string);
if must.is_empty() && should.is_empty() && must_not.is_empty() && filter.is_empty() {
// Empty bool == match_all; with a boost, ES scores it `boost`
// per hit (constant-score semantics), like `match_all{boost}`.
return Ok(maybe_named(
match boost {
Some(b) => QueryNode::Constant {
score: b,
query: Box::new(QueryNode::MatchAll),
},
None => QueryNode::MatchAll,
},
name,
));
}
let minimum_should_match = obj
.get("minimum_should_match")
.map(parse_min_should_match)
.transpose()?;
let node = QueryNode::Bool {
must,
should,
must_not,
filter,
minimum_should_match,
};
let node = match boost {
Some(b) => QueryNode::Boosted {
boost: b,
query: Box::new(node),
},
None => node,
};
Ok(maybe_named(node, name))
}
fn parse_constant_score(params: &Value) -> Result<QueryNode> {
let obj = params
.as_object()
.ok_or_else(|| qerr("`constant_score` must be an object"))?;
let filter_val = obj
.get("filter")
.ok_or_else(|| qerr("`constant_score` requires a `filter` clause"))?;
let query = parse_query(filter_val)?;
// Keep the Constant wrapper: ES scores every `constant_score` hit as
// exactly `boost` (default 1.0) — flattening returned the INNER query's
// score instead (live-diverged vs ES 8.13.4: constant_score(term,
// boost=2.5) scored 1.693… where ES returns 2.5 per hit). The fast
// paths the old flatten protected (is_doc_scan_query,
// try_doc_values_query, try_shortcut_count, query_node_to_fts,
// doc_matches_query, query_node_to_agg_filter) all peel
// `QueryNode::Constant` today, and the scored-family columnar path
// serves the keyword-filter shape bit-exactly.
let boost = obj.get("boost").and_then(|v| v.as_f64()).unwrap_or(1.0) as f32;
Ok(QueryNode::Constant {
score: boost,
query: Box::new(query),
})
}
fn parse_boosting(params: &Value) -> Result<QueryNode> {
let obj = params
.as_object()
.ok_or_else(|| qerr("`boosting` must be an object"))?;
let positive_val = obj
.get("positive")
.ok_or_else(|| qerr("`boosting` requires a `positive` clause"))?;
let negative_val = obj
.get("negative")
.ok_or_else(|| qerr("`boosting` requires a `negative` clause"))?;
let positive = parse_query(positive_val)?;
let negative = parse_query(negative_val)?;
let negative_boost = obj
.get("negative_boost")
.and_then(|v| v.as_f64())
.unwrap_or(0.1) as f32;
Ok(QueryNode::Boosting {
positive: Box::new(positive),
negative: Box::new(negative),
negative_boost,
})
}
fn parse_dis_max(params: &Value) -> Result<QueryNode> {
let obj = params
.as_object()
.ok_or_else(|| qerr("`dis_max` must be an object"))?;
let queries_val = obj
.get("queries")
.and_then(|v| v.as_array())
.ok_or_else(|| qerr("`dis_max.queries` must be an array"))?;
let queries = queries_val
.iter()
.enumerate()
.map(|(i, v)| {
// `dis_max.queries` is a clause list by any other name: each entry
// is scored against every document, so it multiplies per-document
// work exactly as a `bool` clause does.
charge_clause()?;
parse_query(v).map_err(|e| {
crate::error::QueryError::Parse(crate::error::ParseError::Invalid(format!(
"`dis_max.queries[{i}]`: {e}"
)))
})
})
.collect::<Result<Vec<_>>>()?;
if queries.is_empty() {
return invalid("`dis_max.queries` must not be empty");
}
let tie_breaker = obj
.get("tie_breaker")
.and_then(|v| v.as_f64())
.unwrap_or(0.0) as f32;
let node = QueryNode::DisMax {
queries,
tie_breaker,
};
// Compound-clause boost — same propagation contract as `bool` (see
// `parse_bool`): wrap, don't drop.
Ok(match obj.get("boost").and_then(|v| v.as_f64()) {
Some(b) if (b as f32) != 1.0 => QueryNode::Boosted {
boost: b as f32,
query: Box::new(node),
},
_ => node,
})
}
fn parse_knn(params: &Value) -> Result<QueryNode> {
let obj = params
.as_object()
.ok_or_else(|| qerr("`knn` must be an object"))?;
let field = string_field(obj, "field")?;
let num_candidates = obj
.get("num_candidates")
.and_then(|v| v.as_u64())
.map(|n| n as usize);
// `k` derivation is unchanged: explicit `k`, else `num_candidates`, else 10.
let k = obj
.get("k")
.and_then(|v| v.as_u64())
.map(|n| n as usize)
.or(num_candidates)
.unwrap_or(10);
let vector = obj
.get("query_vector")
.or_else(|| obj.get("vector"))
.and_then(|v| v.as_array())
.ok_or_else(|| qerr("`knn` requires `query_vector` (or `vector`) as a float array"))?
.iter()
.map(|v| {
v.as_f64()
.ok_or_else(|| qerr("`knn.query_vector` must contain numbers"))
.map(|f| f as f32)
})
.collect::<Result<Vec<f32>>>()?;
// ES accepts `filter` as a single query object OR an array of queries
// (implicitly ANDed, exactly like `bool.filter`).
let filter = match obj.get("filter") {
None => None,
Some(Value::Array(arr)) => {
// Implicitly ANDed, so this is `bool.filter` spelled differently
// and is charged the same way.
let parsed: Vec<QueryNode> = arr
.iter()
.map(|v| {
charge_clause()?;
parse_query(v)
})
.collect::<Result<_>>()?;
match parsed.len() {
0 => None,
1 => Some(Box::new(parsed.into_iter().next().unwrap())),
_ => Some(Box::new(QueryNode::Bool {
must: Vec::new(),
should: Vec::new(),
filter: parsed,
must_not: Vec::new(),
minimum_should_match: None,
})),
}
}
Some(single) => Some(Box::new(parse_query(single)?)),
};
let boost = obj.get("boost").and_then(|v| v.as_f64()).map(|b| b as f32);
// ES `knn.similarity` — raw-metric similarity cutoff (docs below it
// are not matches). Kept raw here; the executor converts it into the
// equivalent transformed-score threshold per the field's metric.
let similarity = obj
.get("similarity")
.and_then(|v| v.as_f64())
.map(|s| s as f32);
Ok(QueryNode::Knn {
field,
vector,
k,
num_candidates,
filter,
boost,
similarity,
})
}
fn parse_semantic(params: &Value) -> Result<QueryNode> {
let obj = params
.as_object()
.ok_or_else(|| qerr("`semantic` must be an object"))?;
let field = string_field(obj, "field")?;
let text = string_field(obj, "query")?;
let k = obj.get("k").and_then(|v| v.as_u64()).unwrap_or(10) as usize;
let filter = obj
.get("filter")
.map(parse_query)
.transpose()?
.map(Box::new);
let boost = obj.get("boost").and_then(|v| v.as_f64()).map(|b| b as f32);
Ok(QueryNode::SemanticSearch {
field,
text,
k,
filter,
boost,
})
}
fn parse_hybrid(params: &Value) -> Result<QueryNode> {
let obj = params
.as_object()
.ok_or_else(|| qerr("`hybrid` must be an object"))?;
let queries_val = obj
.get("queries")
.and_then(|v| v.as_array())
.ok_or_else(|| qerr("`hybrid.queries` must be an array"))?;
let queries = queries_val
.iter()
.enumerate()
.map(|(i, v)| {
let entry = v.as_object().ok_or_else(|| {
qerr(format!(
"`hybrid.queries[{i}]` must be an object {{\"query\": <clause>, \"weight\": <number>}}"
))
})?;
let q_val = entry.get("query").ok_or_else(|| {
qerr(format!(
"`hybrid.queries[{i}]` missing `query`; each item is {{\"query\": <clause>, \"weight\": <number>}} (weight defaults to 1)"
))
})?;
let query = parse_query(q_val)?;
let weight = entry.get("weight").and_then(|v| v.as_f64()).unwrap_or(1.0) as f32;
Ok(WeightedQuery { query, weight })
})
.collect::<Result<Vec<_>>>()?;
if queries.is_empty() {
return invalid("`hybrid.queries` must not be empty");
}
let fusion = match obj.get("fusion") {
Some(Value::String(s)) => match s.as_str() {
"rrf" => FusionStrategy::Rrf { k: 60 },
"linear" => FusionStrategy::Linear,
// Learned fusion is not implemented — fail loud rather than
// silently substituting RRF (which would misrepresent the
// ranking the caller asked for). AST variant kept for future.
"learned" => {
return invalid("hybrid fusion learned is not yet supported; use rrf or linear")
}
other => return invalid(format!("unknown hybrid fusion strategy `{other}`")),
},
Some(Value::Object(m)) => {
let t = m.get("type").and_then(|v| v.as_str()).unwrap_or("rrf");
match t {
"rrf" => {
let k = m.get("k").and_then(|v| v.as_u64()).unwrap_or(60) as u32;
FusionStrategy::Rrf { k }
}
"linear" => FusionStrategy::Linear,
// Learned fusion is not implemented — fail loud (see above).
"learned" => {
return invalid("hybrid fusion learned is not yet supported; use rrf or linear")
}
other => return invalid(format!("unknown hybrid fusion strategy `{other}`")),
}
}
None => FusionStrategy::default(),
_ => return invalid("`hybrid.fusion` must be a string or object"),
};
Ok(QueryNode::Hybrid { queries, fusion })
}
/// Parse a `function_score` query.
///
/// ```json
/// {
/// "function_score": {
/// "query": { "match_all": {} },
/// "functions": [
/// { "filter": { "term": { "status": "published" } },
/// "field_value_factor": { "field": "popularity", "factor": 1.5, "modifier": "log1p" } },
/// { "weight": 2.0, "filter": { "term": { "featured": true } } }
/// ],
/// "score_mode": "sum",
/// "boost_mode": "multiply",
/// "max_boost": 10.0
/// }
/// }
/// ```
fn parse_function_score(params: &Value) -> Result<QueryNode> {
let obj = params
.as_object()
.ok_or_else(|| qerr("`function_score` must be an object"))?;
let name = obj
.get("_name")
.and_then(|v| v.as_str())
.map(str::to_string);
// Inner query (defaults to match_all).
let query = match obj.get("query") {
Some(q) => parse_query(q)?,
None => QueryNode::MatchAll,
};
// Parse functions array.
let functions: Vec<ScoreFunction> = match obj.get("functions") {
Some(Value::Array(arr)) => arr
.iter()
.map(parse_score_function)
.collect::<Result<Vec<_>>>()?,
Some(_) => return invalid("`function_score.functions` must be an array"),
None => {
// Shorthand: a single function can be specified inline.
let f = parse_score_function_inline(obj)?;
if f.weight.is_none() && f.field_value_factor.is_none() && f.random_score.is_none() {
Vec::new()
} else {
vec![f]
}
}
};
let score_mode = match obj
.get("score_mode")
.and_then(Value::as_str)
.unwrap_or("multiply")
{
"multiply" => ScoreMode::Multiply,
"sum" => ScoreMode::Sum,
"avg" => ScoreMode::Avg,
"first" => ScoreMode::First,
"max" => ScoreMode::Max,
"min" => ScoreMode::Min,
other => return invalid(format!("unknown score_mode `{other}`")),
};
let boost_mode = match obj
.get("boost_mode")
.and_then(Value::as_str)
.unwrap_or("multiply")
{
"multiply" => BoostMode::Multiply,
"replace" => BoostMode::Replace,
"sum" => BoostMode::Sum,
"avg" => BoostMode::Avg,
"max" => BoostMode::Max,
"min" => BoostMode::Min,
other => return invalid(format!("unknown boost_mode `{other}`")),
};
let max_boost = obj
.get("max_boost")
.and_then(|v| v.as_f64())
.map(|b| b as f32);
let mut node = QueryNode::FunctionScore {
query: Box::new(query),
functions,
score_mode,
boost_mode,
max_boost,
};
// `function_score.boost` multiplies the BASE query score BEFORE the
// boost_mode combine (Lucene propagates the boost into the subquery
// weight; `_explain` shows `*:*^3.0` = 3.0 as the base branch).
// Live-verified on ES 8.13.4: `{boost:3, fvf(rank=5)}` scores 15
// (multiply), 8 (sum), 4 (avg), 5 (max), 3 (min), and 5 (replace —
// the boost has NO effect when the base is discarded). The engine's
// `peel_function_score_boosted` recovers this wrapper's boost and
// applies it to the base with exactly those semantics. Was silently
// dropped.
if let Some(boost) = obj.get("boost").and_then(|v| v.as_f64()) {
let boost = boost as f32;
if boost != 1.0 {
node = QueryNode::Boosted {
boost,
query: Box::new(node),
};
}
}
Ok(maybe_named(node, name))
}
/// Parse one entry in the `functions` array.
fn parse_score_function(v: &Value) -> Result<ScoreFunction> {
let obj = v
.as_object()
.ok_or_else(|| qerr("each entry in `functions` must be an object"))?;
parse_score_function_inline(obj)
}
/// Parse score function fields from an existing object map.
fn parse_score_function_inline(obj: &serde_json::Map<String, Value>) -> Result<ScoreFunction> {
let filter = obj
.get("filter")
.map(parse_query)
.transpose()?
.map(Box::new);
let weight = obj.get("weight").and_then(|v| v.as_f64()).map(|w| w as f32);
let field_value_factor = match obj.get("field_value_factor") {
Some(fvf_val) => {
let fvf = fvf_val
.as_object()
.ok_or_else(|| qerr("`field_value_factor` must be an object"))?;
let field = fvf
.get("field")
.and_then(Value::as_str)
.ok_or_else(|| qerr("`field_value_factor.field` is required"))?
.to_string();
let factor = fvf.get("factor").and_then(|v| v.as_f64()).unwrap_or(1.0) as f32;
let modifier = match fvf
.get("modifier")
.and_then(Value::as_str)
.unwrap_or("none")
{
"none" => Modifier::None,
"log" => Modifier::Log,
"log1p" => Modifier::Log1p,
"log2p" => Modifier::Log2p,
"ln" => Modifier::Ln,
"ln1p" => Modifier::Ln1p,
"ln2p" => Modifier::Ln2p,
"square" => Modifier::Square,
"sqrt" => Modifier::Sqrt,
"reciprocal" => Modifier::Reciprocal,
other => return invalid(format!("unknown modifier `{other}`")),
};
let missing = fvf.get("missing").and_then(|v| v.as_f64());
Some(FieldValueFactor {
field,
factor,
modifier,
missing,
})
}
None => None,
};
let random_score = match obj.get("random_score") {
Some(rs_val) => {
let seed = rs_val.get("seed").and_then(|v| v.as_u64());
let field = rs_val
.get("field")
.and_then(Value::as_str)
.map(str::to_string);
Some(RandomScore { seed, field })
}
None => None,
};
// script_score within a function: literal numeric source goes into
// the fast-path `script_score` field; richer Painless source goes
// into `script_source` and is evaluated at score time.
let script_obj = obj.get("script_score").and_then(|ss| ss.get("script"));
let script_source_str = script_obj
.and_then(|s| s.get("source"))
.and_then(Value::as_str)
.map(String::from);
let script_params = script_obj.and_then(|s| s.get("params").cloned());
let literal_score = script_source_str
.as_ref()
.and_then(|s| s.trim().parse::<f32>().ok());
let (script_score, script_source) = if let Some(n) = literal_score {
(Some(n), None)
} else {
(None, script_source_str)
};
let name = obj.get("_name").and_then(Value::as_str).map(String::from);
Ok(ScoreFunction {
filter: filter.map(|b| *b),
weight,
field_value_factor,
random_score,
script_score,
script_source,
script_params,
name,
distance_feature: None,
rank_feature: None,
})
}
// ─────────────────────────────────────────────────────────────────────────────
// Sort parsing
// ─────────────────────────────────────────────────────────────────────────────
fn parse_sort(value: &Value) -> Result<Vec<SortField>> {
match value {
Value::String(s) => Ok(vec![parse_sort_field_str(s)]),
Value::Array(arr) => arr.iter().map(parse_sort_entry).collect(),
_ => invalid("`sort` must be a string or array"),
}
}
fn parse_sort_entry(value: &Value) -> Result<SortField> {
match value {
Value::String(s) => Ok(parse_sort_field_str(s)),
Value::Object(obj) => {
if obj.len() != 1 {
return invalid("each sort entry must have exactly one field");
}
let (field, spec) = obj.iter().next().unwrap();
parse_sort_field_spec(field, spec)
}
_ => invalid("sort entry must be a string or object"),
}
}
fn parse_sort_field_str(s: &str) -> SortField {
match s {
"_score" => SortField {
field: "_score".to_string(),
order: SortOrder::Desc,
mode: SortMode::default(),
missing: SortMissing::default(),
format: None,
unmapped_type: None,
numeric_type: None,
},
"_doc" => SortField {
field: "_doc".to_string(),
order: SortOrder::Asc,
mode: SortMode::default(),
missing: SortMissing::default(),
format: None,
unmapped_type: None,
numeric_type: None,
},
other => SortField {
field: other.to_string(),
order: SortOrder::Asc,
mode: SortMode::default(),
missing: SortMissing::default(),
format: None,
unmapped_type: None,
numeric_type: None,
},
}
}
fn parse_sort_field_spec(field: &str, spec: &Value) -> Result<SortField> {
if let Some(order_str) = spec.as_str() {
let order = parse_sort_order(order_str)?;
return Ok(SortField {
field: field.to_string(),
order,
mode: SortMode::default(),
missing: SortMissing::default(),
format: None,
unmapped_type: None,
numeric_type: None,
});
}
let obj = spec
.as_object()
.ok_or_else(|| qerr("sort field spec must be a string or object"))?;
let order = match obj.get("order").and_then(|v| v.as_str()) {
Some(s) => parse_sort_order(s)?,
None => SortOrder::Asc,
};
let mode = match obj.get("mode").and_then(|v| v.as_str()) {
Some("min") => SortMode::Min,
Some("max") => SortMode::Max,
Some("avg") => SortMode::Avg,
Some("sum") => SortMode::Sum,
Some("median") => SortMode::Median,
None => SortMode::default(),
Some(other) => return invalid(format!("unknown sort mode `{other}`")),
};
let missing = match obj.get("missing").and_then(|v| v.as_str()) {
Some("_last") | None => SortMissing::Last,
Some("_first") => SortMissing::First,
Some(other) => SortMissing::Value(Value::String(other.to_string())),
};
let format = obj.get("format").and_then(|v| v.as_str()).map(String::from);
let unmapped_type = obj
.get("unmapped_type")
.and_then(|v| v.as_str())
.map(String::from);
// ES `numeric_type` (#889): force the epoch scale this sort's values are
// produced on, so a field mapped `date` in one index and `date_nanos` in
// another compares on one scale instead of as raw longs.
let numeric_type = obj
.get("numeric_type")
.and_then(|v| v.as_str())
.map(|s| s.to_ascii_lowercase());
Ok(SortField {
field: field.to_string(),
order,
mode,
missing,
format,
unmapped_type,
numeric_type,
})
}
fn parse_sort_order(s: &str) -> Result<SortOrder> {
match s {
"asc" => Ok(SortOrder::Asc),
"desc" => Ok(SortOrder::Desc),
other => invalid(format!(
"unknown sort order `{other}` (expected `asc` or `desc`)"
)),
}
}
// ─────────────────────────────────────────────────────────────────────────────
// Source filter parsing
// ─────────────────────────────────────────────────────────────────────────────
fn parse_source_filter(value: &Value) -> Result<SourceFilter> {
match value {
Value::Bool(b) => Ok(SourceFilter::Enabled(*b)),
Value::String(s) => Ok(SourceFilter::Includes(vec![s.clone()])),
Value::Array(arr) => {
let fields = arr
.iter()
.map(|v| {
v.as_str()
.ok_or_else(|| qerr("`_source` array must contain strings"))
.map(str::to_string)
})
.collect::<Result<Vec<_>>>()?;
Ok(SourceFilter::Includes(fields))
}
Value::Object(obj) => {
let includes = parse_string_list(obj.get("includes"))?;
let excludes = parse_string_list(obj.get("excludes"))?;
Ok(SourceFilter::Fields { includes, excludes })
}
_ => invalid("`_source` must be a bool, string, array, or object"),
}
}
fn parse_string_list(value: Option<&Value>) -> Result<Vec<String>> {
match value {
None => Ok(vec![]),
Some(Value::String(s)) => Ok(vec![s.clone()]),
Some(Value::Array(arr)) => arr
.iter()
.map(|v| {
v.as_str()
.ok_or_else(|| qerr("field list must contain strings"))
.map(str::to_string)
})
.collect(),
_ => invalid("field list must be a string or array of strings"),
}
}
// ─────────────────────────────────────────────────────────────────────────────
// Helpers
// ─────────────────────────────────────────────────────────────────────────────
/// Construct a `QueryError` for use with `ok_or_else`.
#[inline(always)]
fn qerr(msg: impl Into<String>) -> QueryError {
QueryError::Parse(ParseError::Invalid(msg.into()))
}
/// Parse a `minimum_should_match` value.
fn parse_min_should_match(v: &Value) -> Result<MinShouldMatch> {
match v {
// #846: a negative JSON integer (`-1`) is "all but N", not an error.
Value::Number(n) => {
if let Some(i) = n.as_u64() {
Ok(MinShouldMatch::Fixed(i as u32))
} else if let Some(neg) = n.as_i64().filter(|x| *x < 0) {
Ok(MinShouldMatch::Negative(neg.unsigned_abs() as u32))
} else {
Err(qerr("`minimum_should_match` must be an integer"))
}
}
Value::String(s) => parse_min_should_match_str(s.trim()),
_ => invalid("`minimum_should_match` must be a number or string"),
}
}
/// Parse the string spelling of `minimum_should_match`: a plain or negative
/// integer, a plain or negative percentage, or a `pivot<spec [pivot<spec ...]`
/// combination (#846). Combination specs recurse (their `spec` is any of the
/// non-combination forms).
fn parse_min_should_match_str(s: &str) -> Result<MinShouldMatch> {
let s = s.trim();
// Combination: whitespace-separated `pivot<spec` conditions.
if s.contains('<') {
let mut conds = Vec::new();
for tok in s.split_whitespace() {
let (pivot, spec) = tok.split_once('<').ok_or_else(|| {
qerr(format!("invalid `minimum_should_match` combination: `{s}`"))
})?;
let pivot: u32 = pivot
.trim()
.parse()
.map_err(|_| qerr(format!("invalid `minimum_should_match` pivot in `{tok}`")))?;
let spec = parse_min_should_match_str(spec.trim())?;
conds.push(crate::ast::CombCond {
pivot,
spec: Box::new(spec),
});
}
return Ok(MinShouldMatch::Combination(conds));
}
// Percentage, possibly negative.
if let Some(pct) = s.strip_suffix('%') {
let pct = pct.trim();
if let Some(neg) = pct.strip_prefix('-') {
let p: u32 = neg
.trim()
.parse()
.map_err(|_| qerr(format!("invalid `minimum_should_match` percentage: `{s}`")))?;
return Ok(MinShouldMatch::NegativePercentage(p));
}
let p: u32 = pct
.parse()
.map_err(|_| qerr(format!("invalid `minimum_should_match` percentage: `{s}`")))?;
return Ok(MinShouldMatch::Percentage(p));
}
// Plain integer, possibly negative.
if let Some(neg) = s.strip_prefix('-') {
let k: u32 = neg
.trim()
.parse()
.map_err(|_| qerr(format!("invalid `minimum_should_match` value: `{s}`")))?;
return Ok(MinShouldMatch::Negative(k));
}
let n: u32 = s
.parse()
.map_err(|_| qerr(format!("invalid `minimum_should_match` value: `{s}`")))?;
Ok(MinShouldMatch::Fixed(n))
}
fn parse_bool_operator(v: Option<&Value>) -> Result<BoolOperator> {
match v {
None => Ok(BoolOperator::Or),
Some(Value::String(s)) => match s.to_uppercase().as_str() {
"AND" => Ok(BoolOperator::And),
"OR" => Ok(BoolOperator::Or),
other => invalid(format!(
"unknown boolean operator `{other}` (expected AND or OR)"
)),
},
_ => invalid("`operator` must be a string"),
}
}
/// Parse a bool clause list. ES allows a single object or an array.
///
/// Every clause is charged against [`MAX_CLAUSE_COUNT`] *before* it is parsed,
/// so an oversized list is refused after 1,024 clauses rather than after all
/// of them.
fn parse_clause_list(obj: &serde_json::Map<String, Value>, key: &str) -> Result<Vec<QueryNode>> {
match obj.get(key) {
None => Ok(vec![]),
Some(Value::Array(arr)) => arr
.iter()
.map(|clause| {
charge_clause()?;
parse_query(clause)
})
.collect(),
Some(single) => {
charge_clause()?;
Ok(vec![parse_query(single)?])
}
}
}
fn string_field(obj: &serde_json::Map<String, Value>, key: &str) -> Result<String> {
obj.get(key)
.and_then(|v| v.as_str())
.map(str::to_string)
.ok_or_else(|| qerr(format!("`{key}` must be a non-empty string")))
}
/// Parse ES timeout strings like "1s", "100ms", "2m".
fn parse_timeout(v: &Value) -> Option<u64> {
let s = v.as_str()?;
if let Some(ms) = s.strip_suffix("ms") {
ms.parse().ok()
} else if let Some(s_str) = s.strip_suffix('s') {
s_str.parse::<u64>().ok().map(|n| n * 1_000)
} else if let Some(m) = s.strip_suffix('m') {
m.parse::<u64>().ok().map(|n| n * 60_000)
} else {
s.parse().ok()
}
}
// ─────────────────────────────────────────────────────────────────────────────
// New query type parsers
// ─────────────────────────────────────────────────────────────────────────────
/// Parse a `nested` query.
///
/// ```json
/// {
/// "nested": {
/// "path": "comments",
/// "query": { "match": { "comments.text": "great" } },
/// "score_mode": "avg"
/// }
/// }
/// ```
fn parse_nested(params: &Value) -> Result<QueryNode> {
let obj = params
.as_object()
.ok_or_else(|| qerr("`nested` must be an object"))?;
let path = string_field(obj, "path")?;
let query_val = obj
.get("query")
.ok_or_else(|| qerr("`nested` requires a `query` clause"))?;
let query = parse_query(query_val)?;
let score_mode = obj
.get("score_mode")
.and_then(|v| v.as_str())
.map(str::to_string);
Ok(QueryNode::Nested {
path,
query: Box::new(query),
score_mode,
})
}
/// Parse a `more_like_this` query.
///
/// ```json
/// {
/// "more_like_this": {
/// "fields": ["title", "body"],
/// "like": ["a very interesting document"],
/// "min_term_freq": 1,
/// "max_query_terms": 12
/// }
/// }
/// ```
fn parse_more_like_this(params: &Value) -> Result<QueryNode> {
let obj = params
.as_object()
.ok_or_else(|| qerr("`more_like_this` must be an object"))?;
let fields: Vec<String> = obj
.get("fields")
.and_then(|v| v.as_array())
.map(|arr| {
arr.iter()
.filter_map(|v| v.as_str().map(str::to_string))
.collect()
})
.unwrap_or_default();
// `like` can be a string, an array of strings, or an array of mixed
// strings / {"_index":…,"_id":…} objects (we only use text strings).
let like: Vec<String> = match obj.get("like") {
Some(Value::String(s)) => vec![s.clone()],
Some(Value::Array(arr)) => arr
.iter()
.filter_map(|v| match v {
Value::String(s) => Some(s.clone()),
Value::Object(o) => o.get("doc").and_then(|d| {
// Inline document: extract text from all string fields.
if let Some(doc_obj) = d.as_object() {
let text: Vec<String> = doc_obj
.values()
.filter_map(|v| v.as_str().map(str::to_string))
.collect();
if text.is_empty() {
None
} else {
Some(text.join(" "))
}
} else {
None
}
}),
_ => None,
})
.collect(),
_ => return invalid("`more_like_this.like` must be a string or array"),
};
if like.is_empty() {
return invalid("`more_like_this.like` must contain at least one text string");
}
let min_term_freq = obj
.get("min_term_freq")
.and_then(|v| v.as_u64())
.unwrap_or(2) as u32;
let max_query_terms = obj
.get("max_query_terms")
.and_then(|v| v.as_u64())
.unwrap_or(25) as u32;
// Rewrite `more_like_this` into a `bool.should` of `match` clauses — one
// per (field × like-text) — exactly as Elasticsearch lowers MLT to a
// disjunction of term queries over the analyzed like-text. This routes MLT
// through the postings + scored path instead of an O(N) per-doc substring
// scan, and produces BM25 scores bit-identical to ES (a keyword-field MLT
// reduces to the same `term` query ES emits) instead of the old flat 1.0.
// `match` handles both keyword (exact-token) and analyzed-text fields, so
// no schema lookup is needed here. When `fields` is unspecified we cannot
// build the disjunction, so we fall back to the legacy MoreLikeThis node
// (which scans all string fields on the brute path).
if !fields.is_empty() {
// Bound the cross-product. `fields.len() × like.len()` QueryNode entries
// are pre-allocated below; without a cap a ~200 KB body with 10 000
// fields × 10 000 like-texts forces a 10^8-entry Vec (~10 GiB) and
// aborts the process on OOM. ES effectively bounds MLT `fields` to a
// handful; we enforce hard limits and reject oversized requests
// with a 400-style parse error instead of allocating.
const MAX_MLT_FIELDS: usize = 64;
const MAX_MLT_LIKE: usize = 1_024;
const MAX_MLT_CROSS_PRODUCT: usize = 4_096;
if fields.len() > MAX_MLT_FIELDS {
return invalid(format!(
"`more_like_this.fields` has {} entries; max is {}",
fields.len(),
MAX_MLT_FIELDS
));
}
if like.len() > MAX_MLT_LIKE {
return invalid(format!(
"`more_like_this.like` has {} entries; max is {}",
like.len(),
MAX_MLT_LIKE
));
}
let cross = fields.len().saturating_mul(like.len());
if cross > MAX_MLT_CROSS_PRODUCT {
return invalid(format!(
"`more_like_this` cross-product ({} fields × {} like = {}) exceeds max of {}",
fields.len(),
like.len(),
cross,
MAX_MLT_CROSS_PRODUCT
));
}
let mut should: Vec<QueryNode> = Vec::with_capacity(cross);
for field in &fields {
for text in &like {
should.push(QueryNode::Match {
field: field.clone(),
query: text.clone(),
operator: BoolOperator::Or,
analyzer: None,
boost: None,
minimum_should_match: None,
// ES refuses a numeric `more_like_this` field with a
// different error (`only supports text/keyword fields`);
// #1284's type check is not that refusal, so stay out.
lenient: true,
});
}
}
// Bool with only `should` clauses defaults to "≥1 should must match",
// matching ES's MLT default (`minimum_should_match: "30%"` still lands
// at 1 for a single interesting term; we keep the engine default here).
return Ok(QueryNode::Bool {
must: vec![],
should,
must_not: vec![],
filter: vec![],
minimum_should_match: None,
});
}
Ok(QueryNode::MoreLikeThis {
fields,
like,
min_term_freq,
max_query_terms,
})
}
/// Parse a `pinned` query.
///
/// ```json
/// {
/// "pinned": {
/// "ids": ["1", "2"],
/// "organic": { "match": { "title": "search" } }
/// }
/// }
/// ```
/// Parse a `percolate` query.
///
/// Only the inline-document form is supported:
/// ```json
/// { "field": "query", "document": { … } }
/// { "field": "query", "documents": [ { … }, … ] }
/// ```
/// The index/id fetch form (`{ "field": "query", "index": "...", "id": "..." }`)
/// is rejected with a 400 rather than silently returning nothing.
fn parse_percolate(params: &Value) -> Result<QueryNode> {
let obj = params
.as_object()
.ok_or_else(|| qerr("`percolate` must be an object"))?;
let field = string_field(obj, "field")?;
let documents: Vec<Value> = if let Some(doc) = obj.get("document") {
if !doc.is_object() {
return invalid("`percolate.document` must be an object");
}
vec![doc.clone()]
} else if let Some(docs) = obj.get("documents") {
let arr = docs
.as_array()
.ok_or_else(|| qerr("`percolate.documents` must be an array"))?;
if arr.iter().any(|d| !d.is_object()) {
return invalid("`percolate.documents` must contain only objects");
}
arr.clone()
} else {
return invalid(
"`percolate` requires an inline `document` or `documents`; the \
index/id document-fetch form is not supported",
);
};
if documents.is_empty() {
return invalid("`percolate` requires at least one document");
}
Ok(QueryNode::Percolate { field, documents })
}
fn parse_pinned(params: &Value) -> Result<QueryNode> {
let obj = params
.as_object()
.ok_or_else(|| qerr("`pinned` must be an object"))?;
let ids: Vec<String> = obj
.get("ids")
.and_then(|v| v.as_array())
.ok_or_else(|| qerr("`pinned` requires an `ids` array"))?
.iter()
.map(|v| match v {
Value::String(s) => Ok(s.clone()),
Value::Number(n) => Ok(n.to_string()),
_ => Err(qerr("`pinned.ids` must contain strings or numbers")),
})
.collect::<Result<Vec<_>>>()?;
let organic_val = obj
.get("organic")
.ok_or_else(|| qerr("`pinned` requires an `organic` query"))?;
let organic = parse_query(organic_val)?;
Ok(QueryNode::Pinned {
ids,
organic: Box::new(organic),
})
}
/// Parse a `wrapper` query — base64-encodes a query JSON string.
///
/// ```json
/// { "wrapper": { "query": "eyJtYXRjaF9hbGwiOiB7fX0=" } }
/// ```
fn parse_wrapper(params: &Value) -> Result<QueryNode> {
let obj = params
.as_object()
.ok_or_else(|| qerr("`wrapper` must be an object"))?;
let encoded = obj
.get("query")
.and_then(|v| v.as_str())
.ok_or_else(|| qerr("`wrapper.query` must be a base64-encoded query string"))?;
let decoded_bytes = base64::engine::general_purpose::STANDARD
.decode(encoded)
.map_err(|_| qerr("`wrapper.query` is not valid base64"))?;
let decoded_str = std::str::from_utf8(&decoded_bytes)
.map_err(|_| qerr("`wrapper.query` base64 payload is not valid UTF-8"))?;
let inner_json: Value = serde_json::from_str(decoded_str)
.map_err(|_| qerr("`wrapper.query` base64 payload is not valid JSON"))?;
// The decoded JSON may be a full query object {"match": {…}} or a
// SearchRequest-style envelope {"query": {…}}. Try both.
if let Some(q) = inner_json.as_object().and_then(|o| o.get("query")) {
parse_query(q)
} else {
parse_query(&inner_json)
}
}
/// Parse a `span_term` query.
///
/// Accepts:
/// - `{"span_term": {"field": "value"}}` — shorthand string form
/// - `{"span_term": {"field": {"value": "text"}}}` — long form
fn parse_span_term(params: &Value) -> Result<QueryNode> {
let obj = params
.as_object()
.ok_or_else(|| qerr("`span_term` must be an object"))?;
if obj.len() != 1 {
return invalid("`span_term` query must have exactly one field");
}
let (field, raw) = obj.iter().next().unwrap();
let field = field.clone();
let value = if let Some(s) = raw.as_str() {
s.to_string()
} else if let Some(inner) = raw.as_object() {
if let Some(v) = inner.get("value").and_then(|v| v.as_str()) {
v.to_string()
} else {
return invalid("`span_term` object form requires a `value` string");
}
} else {
return invalid("`span_term` field value must be a string or object");
};
Ok(QueryNode::SpanTerm { field, value })
}
/// Parse a `span_near` query.
///
/// `{"span_near": {"clauses": [...], "slop": 5, "in_order": true}}`
fn parse_span_near(params: &Value) -> Result<QueryNode> {
let obj = params
.as_object()
.ok_or_else(|| qerr("`span_near` must be an object"))?;
let clauses = parse_span_clauses(obj, "span_near")?;
if clauses.is_empty() {
return Ok(QueryNode::MatchNone);
}
// KNOWN GAP (pre-existing, deliberately not changed by #230): this read
// accepts anything and silently substitutes 0 — `slop: -1`, `slop: 2.0`
// and `slop: "2"` all answer as slop 0. It is NOT routed through
// `parse_phrase_slop`, and the phrase work in #230 does not cover it.
//
// It is left alone rather than "fixed" because ES applies no validation
// here either: `SpanNearQueryBuilder` takes the int unchecked
// (`.../index/query/SpanNearQueryBuilder.java:62`, no negative test)
// while every phrase builder throws on a negative slop. So a negative
// `span_near` slop is a query ES answers, and rejecting it would be a
// wire-compat break on a request that works today. Closing it properly
// means honouring the value (float coercion via `coerce_es_int`, and a
// decision about what a negative span slop should match), which is a
// span-query change, not a phrase one.
let slop = obj.get("slop").and_then(|v| v.as_u64()).unwrap_or(0) as u32;
let in_order = obj
.get("in_order")
.and_then(|v| v.as_bool())
.unwrap_or(false);
Ok(QueryNode::SpanNear {
clauses,
slop,
in_order,
})
}
/// Parse a `span_or` query.
///
/// `{"span_or": {"clauses": [...]}}`
fn parse_span_or(params: &Value) -> Result<QueryNode> {
let obj = params
.as_object()
.ok_or_else(|| qerr("`span_or` must be an object"))?;
let clauses = parse_span_clauses(obj, "span_or")?;
if clauses.is_empty() {
return Ok(QueryNode::MatchNone);
}
Ok(QueryNode::SpanOr { clauses })
}
/// Parse the `clauses` array shared by `span_near` and `span_or`.
///
/// Both used to collect with `filter_map(|v| parse_query(v).ok())`, which
/// discards a clause the parser refused and keeps going. That is how a *limit*
/// becomes a correctness bug rather than an error: [`MAX_CLAUSE_COUNT`] is a
/// parse error, so a `span_or` whose first clause is an over-wide `bool` used
/// to answer 200 OK with that clause silently missing — a different query than
/// the one asked for, scored against and returned as if it were the answer. A
/// query that is refused is a query the caller can fix; a query that is
/// quietly rewritten is not. Every clause error propagates.
///
/// Clauses are charged against [`MAX_CLAUSE_COUNT`] here for the same reason
/// they are in `bool`: width is what multiplies per-document work, and a span
/// clause list is as wide as a `should` list.
fn parse_span_clauses(obj: &serde_json::Map<String, Value>, _what: &str) -> Result<Vec<QueryNode>> {
let Some(arr) = obj.get("clauses").and_then(|v| v.as_array()) else {
return Ok(Vec::new());
};
// The clause CAP is fatal — a `MAX_CLAUSE_COUNT` trip must refuse, not
// silently drop (that was the #122 defect: `filter_map(..ok())` turned an
// over-cap span into a different query). The cap can trip in TWO places:
// `charge_clause()` for the span's own clauses, and INSIDE `parse_query`
// when a clause is itself a wide `bool` — both must propagate.
//
// But an ordinary parse error for a clause type this engine does not
// implement (`span_multi`) or a malformed clause stays LENIENT and is
// dropped, because that is the pre-#122 behaviour ES-compat conformance
// depends on: `search/190_index_prefix_search` sends a `span_near` holding
// a `span_multi` and expects the search to run, not to 400. So: propagate
// ONLY the cap error; drop every other parse failure.
let mut out = Vec::with_capacity(arr.len());
for v in arr {
charge_clause()?;
match parse_query(v) {
Ok(node) => out.push(node),
Err(e) if e.to_string().contains("too_many_clauses") => return Err(e),
Err(_) => { /* unsupported/malformed clause: dropped, as before */ }
}
}
Ok(out)
}
/// Parse a `span_not` query.
///
/// `{"span_not": {"include": {...}, "exclude": {...}}}`
fn parse_span_not(params: &Value) -> Result<QueryNode> {
let obj = params
.as_object()
.ok_or_else(|| qerr("`span_not` must be an object"))?;
let include = obj
.get("include")
.ok_or_else(|| qerr("`span_not` requires an `include` clause"))
.and_then(parse_query)?;
let exclude = obj
.get("exclude")
.ok_or_else(|| qerr("`span_not` requires an `exclude` clause"))
.and_then(parse_query)?;
Ok(QueryNode::SpanNot {
include: Box::new(include),
exclude: Box::new(exclude),
})
}
/// Parse a `span_first` query.
///
/// `{"span_first": {"match": {...}, "end": 3}}`
fn parse_span_first(params: &Value) -> Result<QueryNode> {
let obj = params
.as_object()
.ok_or_else(|| qerr("`span_first` must be an object"))?;
let match_query = obj
.get("match")
.ok_or_else(|| qerr("`span_first` requires a `match` clause"))
.and_then(parse_query)?;
let end = obj.get("end").and_then(|v| v.as_u64()).unwrap_or(1) as u32;
Ok(QueryNode::SpanFirst {
match_query: Box::new(match_query),
end,
})
}
/// Parse `span_containing` / `span_within`. Both take a `little` and a `big`
/// span clause; the difference is only which span must enclose the other,
/// which is captured by the returned variant.
fn parse_span_containing_like(query_type: &str, params: &Value) -> Result<QueryNode> {
let obj = params
.as_object()
.ok_or_else(|| qerr(format!("`{}` must be an object", query_type)))?;
let little = obj
.get("little")
.ok_or_else(|| qerr(format!("`{}` requires a `little` clause", query_type)))
.and_then(parse_query)?;
let big = obj
.get("big")
.ok_or_else(|| qerr(format!("`{}` requires a `big` clause", query_type)))
.and_then(parse_query)?;
let little = Box::new(little);
let big = Box::new(big);
Ok(match query_type {
"span_within" => QueryNode::SpanWithin { little, big },
// "span_containing"
_ => QueryNode::SpanContaining { little, big },
})
}
/// Parse a `has_child` query.
///
/// `{"has_child": {"type": "answer", "query": {...}, "score_mode": "avg"}}`
///
/// Parent-child joins are NOT supported. XERJ is single-type per index
/// and never materializes the parent/child join structure, so both the
/// planner and executor branches for `HasChild` would silently fall back
/// to running the inner query on flat docs (wrong results). We fail loud
/// (400) at parse time instead — the `QueryNode::HasChild` AST variant is
/// therefore never built, and the downstream branches are unreachable.
fn parse_has_child(_params: &Value) -> Result<QueryNode> {
invalid(
"parent-child join queries (has_child/has_parent) are not supported; \
index as a single flat type or denormalize the relationship",
)
}
/// Parse a `has_parent` query.
///
/// `{"has_parent": {"parent_type": "question", "query": {...}, "score": true}}`
///
/// See `parse_has_child`: parent-child joins are unsupported and rejected
/// with a 400 at parse time, so the `QueryNode::HasParent` variant is
/// never constructed.
fn parse_has_parent(_params: &Value) -> Result<QueryNode> {
invalid(
"parent-child join queries (has_child/has_parent) are not supported; \
index as a single flat type or denormalize the relationship",
)
}
/// Parse a `geo_polygon` query.
///
/// `{"geo_polygon": {"location": {"points": [{"lat":40,"lon":-74}, ...]}}}`
fn parse_geo_polygon(params: &Value) -> Result<QueryNode> {
let obj = params
.as_object()
.ok_or_else(|| qerr("`geo_polygon` must be an object"))?;
// Find the field name (the first key that isn't "boost"/"_name").
let (field, field_params) = obj
.iter()
.find(|(k, _)| k.as_str() != "boost" && k.as_str() != "_name")
.ok_or_else(|| qerr("`geo_polygon` must specify a field"))?;
let field = field.clone();
let points_arr = field_params
.get("points")
.and_then(|v| v.as_array())
.ok_or_else(|| qerr("`geo_polygon` field must have a `points` array"))?;
let points = points_arr
.iter()
.map(parse_lat_lon_obj)
.collect::<Result<Vec<_>>>()?;
Ok(QueryNode::GeoPolygon { field, points })
}
/// Parse a geo point from a JSON object like `{"lat": 40, "lon": -74}`.
fn parse_lat_lon_obj(v: &Value) -> Result<(f64, f64)> {
let obj = v
.as_object()
.ok_or_else(|| qerr("geo point must be an object {lat, lon}"))?;
let lat = obj
.get("lat")
.and_then(|x| x.as_f64())
.ok_or_else(|| qerr("geo point missing `lat`"))?;
let lon = obj
.get("lon")
.and_then(|x| x.as_f64())
.ok_or_else(|| qerr("geo point missing `lon`"))?;
Ok((lat, lon))
}
/// Parse a `geo_shape` query.
///
/// `{"geo_shape": {"location": {"shape": {"type": "envelope", "coordinates": [[lon,lat],[lon,lat]]}}}}`
fn parse_geo_shape(params: &Value) -> Result<QueryNode> {
let obj = params
.as_object()
.ok_or_else(|| qerr("`geo_shape` must be an object"))?;
let (field, field_params) = obj
.iter()
.find(|(k, _)| {
k.as_str() != "boost" && k.as_str() != "_name" && k.as_str() != "ignore_unmapped"
})
.ok_or_else(|| qerr("`geo_shape` must specify a field"))?;
let field = field.clone();
// The shape may be under "shape" or "indexed_shape" key; we only support "shape".
let shape_val = field_params
.get("shape")
.ok_or_else(|| qerr("`geo_shape` field must have a `shape` object"))?;
let shape_type = shape_val
.get("type")
.and_then(|v| v.as_str())
.unwrap_or("")
.to_lowercase();
let shape = match shape_type.as_str() {
"point" => {
// coordinates: [lon, lat]
let coords = shape_val
.get("coordinates")
.and_then(|v| v.as_array())
.ok_or_else(|| qerr("`geo_shape` point needs `coordinates`"))?;
let lon = coords.first().and_then(|v| v.as_f64()).unwrap_or(0.0);
let lat = coords.get(1).and_then(|v| v.as_f64()).unwrap_or(0.0);
GeoShapeType::Point { lat, lon }
}
"envelope" => {
// coordinates: [[top_left_lon, top_left_lat], [bottom_right_lon, bottom_right_lat]]
let coords = shape_val
.get("coordinates")
.and_then(|v| v.as_array())
.ok_or_else(|| qerr("`geo_shape` envelope needs `coordinates`"))?;
let tl = coords
.first()
.and_then(|v| v.as_array())
.ok_or_else(|| qerr("`geo_shape` envelope top-left missing"))?;
let br = coords
.get(1)
.and_then(|v| v.as_array())
.ok_or_else(|| qerr("`geo_shape` envelope bottom-right missing"))?;
let tl_lon = tl.first().and_then(|v| v.as_f64()).unwrap_or(0.0);
let tl_lat = tl.get(1).and_then(|v| v.as_f64()).unwrap_or(0.0);
let br_lon = br.first().and_then(|v| v.as_f64()).unwrap_or(0.0);
let br_lat = br.get(1).and_then(|v| v.as_f64()).unwrap_or(0.0);
GeoShapeType::Envelope {
top_left: (tl_lat, tl_lon),
bottom_right: (br_lat, br_lon),
}
}
"polygon" => {
// coordinates: [[[lon, lat], ...]] (outer ring only)
let rings = shape_val
.get("coordinates")
.and_then(|v| v.as_array())
.ok_or_else(|| qerr("`geo_shape` polygon needs `coordinates`"))?;
let outer = rings
.first()
.and_then(|v| v.as_array())
.ok_or_else(|| qerr("`geo_shape` polygon outer ring missing"))?;
let points = outer
.iter()
.filter_map(|p| {
let arr = p.as_array()?;
let lon = arr.first()?.as_f64()?;
let lat = arr.get(1)?.as_f64()?;
Some((lat, lon))
})
.collect();
GeoShapeType::Polygon { points }
}
"circle" => {
// coordinates: [lon, lat], radius: "10km" or number
let coords = shape_val
.get("coordinates")
.and_then(|v| v.as_array())
.ok_or_else(|| qerr("`geo_shape` circle needs `coordinates`"))?;
let lon = coords.first().and_then(|v| v.as_f64()).unwrap_or(0.0);
let lat = coords.get(1).and_then(|v| v.as_f64()).unwrap_or(0.0);
let radius_km = parse_distance_to_km(
shape_val
.get("radius")
.ok_or_else(|| qerr("`geo_shape` circle needs `radius`"))?,
)?;
GeoShapeType::Circle {
center: (lat, lon),
radius_km,
}
}
other => return invalid(format!("unsupported geo_shape type `{}`", other)),
};
Ok(QueryNode::GeoShape { field, shape })
}
/// Parse a distance value to kilometres. Accepts "10km", "5mi", or a bare number (metres).
fn parse_distance_to_km(v: &Value) -> Result<f64> {
if let Some(n) = v.as_f64() {
return Ok(n / 1000.0); // assume metres
}
if let Some(s) = v.as_str() {
let s = s.trim().to_lowercase();
if let Some(stripped) = s.strip_suffix("km") {
return stripped
.trim()
.parse::<f64>()
.map_err(|_| qerr("invalid distance km"));
}
if let Some(stripped) = s.strip_suffix("mi") {
let miles: f64 = stripped
.trim()
.parse()
.map_err(|_| qerr("invalid distance mi"))?;
return Ok(miles * 1.60934);
}
if let Some(stripped) = s.strip_suffix('m') {
let metres: f64 = stripped
.trim()
.parse()
.map_err(|_| qerr("invalid distance m"))?;
return Ok(metres / 1000.0);
}
if let Ok(n) = s.parse::<f64>() {
return Ok(n / 1000.0);
}
}
invalid("unrecognised distance format")
}
// ─────────────────────────────────────────────────────────────────────────────
// Gap 2: Additional ES query type parsers
// ─────────────────────────────────────────────────────────────────────────────
/// `match_bool_prefix` — tokenise the query string; the last token becomes a
/// `prefix` query and all preceding tokens become `term` queries, combined in a
/// `bool { should: [...] }`.
///
/// ES docs: <https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-match-bool-prefix-query.html>
fn parse_match_bool_prefix(params: &Value) -> Result<QueryNode> {
let obj = params
.as_object()
.ok_or_else(|| qerr("`match_bool_prefix` must be an object"))?;
if obj.len() != 1 {
return invalid("`match_bool_prefix` query must have exactly one field");
}
let (field, raw) = obj.iter().next().unwrap();
let field = field.clone();
// Long-form accepts the same options as `match` + `operator` + mm.
let (query_str, mm, operator_and, analyzer, fuzziness, prefix_length) =
if let Some(s) = raw.as_str() {
(s.to_string(), None, false, None, None, 0usize)
} else {
let inner = raw.as_object().ok_or_else(|| {
qerr("`match_bool_prefix` field value must be a string or object")
})?;
let q = string_field(inner, "query")?;
// #846: go through the shared `minimum_should_match` parser so
// negative / negative-% / combination specs reach the evaluator
// from this site too. It used to inline a number/percentage-only
// subset, which silently dropped every other spec to `None` (=
// plain OR) instead of honouring it.
let mm_val = inner
.get("minimum_should_match")
.and_then(|v| parse_min_should_match(v).ok());
let op_and = matches!(
inner
.get("operator")
.and_then(Value::as_str)
.map(|s| s.to_ascii_lowercase())
.as_deref(),
Some("and")
);
let analyzer = inner
.get("analyzer")
.and_then(Value::as_str)
.map(str::to_string);
let fuzziness = inner.get("fuzziness").map(|v| match v {
Value::String(s) if s.eq_ignore_ascii_case("auto") => crate::ast::Fuzziness::Auto,
Value::String(s) => s
.parse::<u32>()
.ok()
.map(crate::ast::Fuzziness::Fixed)
.unwrap_or(crate::ast::Fuzziness::Auto),
Value::Number(n) => crate::ast::Fuzziness::Fixed(n.as_u64().unwrap_or(0) as u32),
_ => crate::ast::Fuzziness::Auto,
});
let prefix_length = parse_prefix_length(inner);
(q, mm_val, op_and, analyzer, fuzziness, prefix_length)
};
// Analyzer semantics: "whitespace" preserves case, "keyword" treats
// input as single token, default/standard lowercases. We approximate
// by case-folding unless the requested analyzer is case-preserving.
let analyzer_lowercases = !matches!(analyzer.as_deref(), Some("whitespace") | Some("keyword"));
let fold = |t: &str| -> String {
if analyzer_lowercases {
t.to_lowercase()
} else {
t.to_string()
}
};
let raw_tokens: Vec<String> = if analyzer.as_deref() == Some("keyword") {
vec![query_str.clone()]
} else {
query_str.split_whitespace().map(str::to_string).collect()
};
if raw_tokens.is_empty() {
return Ok(QueryNode::MatchAll);
}
if raw_tokens.len() == 1 {
// Single token: the whole match_bool_prefix collapses to one
// standalone prefix clause, which ES rewrites to ConstantScore
// (flat 1.0, no BM25) exactly like a top-level `prefix` query —
// the same MultiTermQuery rewrite 4c69c05 threaded through
// parse_prefix/parse_wildcard; this site was missed (live: xerj
// max_score 2.5210621 vs ES 1.0). Multi-token keeps BM25 (the
// trailing prefix is one clause among scored Match clauses).
return Ok(QueryNode::Prefix {
field,
value: fold(&raw_tokens[0]),
boost: None,
constant_score: true,
case_insensitive: false,
});
}
let last_idx = raw_tokens.len() - 1;
let build_leaf = |tok: &str| -> QueryNode {
let folded = fold(tok);
if let Some(fz) = fuzziness {
QueryNode::Fuzzy {
field: field.clone(),
value: folded,
fuzziness: fz,
case_insensitive: true,
prefix_length,
}
} else {
QueryNode::Match {
field: field.clone(),
query: folded,
operator: BoolOperator::Or,
boost: None,
analyzer: analyzer.clone(),
minimum_should_match: None,
// `match_bool_prefix` has no `lenient` option in ES.
lenient: false,
}
}
};
let mut clauses: Vec<QueryNode> = raw_tokens[..last_idx]
.iter()
.map(|t| build_leaf(t))
.collect();
clauses.push(QueryNode::Prefix {
field: field.clone(),
value: fold(&raw_tokens[last_idx]),
boost: None,
constant_score: false,
// `match_bool_prefix` lowers to an internal prefix over ANALYZED
// tokens — no user-facing `case_insensitive` option to thread.
case_insensitive: false,
});
// operator:and → every clause must match; otherwise should + mm.
let (must, should, mm_final) = if operator_and {
(clauses, vec![], None)
} else {
(vec![], clauses, mm)
};
Ok(QueryNode::Bool {
must,
should,
filter: vec![],
must_not: vec![],
minimum_should_match: mm_final,
})
}
/// `terms_set` — like `terms` but with a per-query `minimum_should_match`.
/// Parsed as `Bool { should: [term1, term2, ...], minimum_should_match: N }`.
///
/// ES docs: <https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-terms-set-query.html>
fn parse_terms_set(params: &Value) -> Result<QueryNode> {
let obj = params
.as_object()
.ok_or_else(|| qerr("`terms_set` must be an object"))?;
let field_entries: Vec<_> = obj.iter().filter(|(k, _)| k.as_str() != "boost").collect();
if field_entries.len() != 1 {
return invalid("`terms_set` query must have exactly one field entry");
}
let (field, raw) = field_entries[0];
let field = field.clone();
let inner = raw
.as_object()
.ok_or_else(|| qerr("`terms_set` field value must be an object"))?;
let terms = inner
.get("terms")
.and_then(Value::as_array)
.ok_or_else(|| qerr("`terms_set.terms` must be an array"))?
.clone();
// `minimum_should_match_field` reads the per-doc required count from a
// numeric field; `minimum_should_match_script` computes it from a
// Painless script. Fall back to a literal `minimum_should_match`.
let minimum_should_match = if let Some(field_name) = inner
.get("minimum_should_match_field")
.and_then(Value::as_str)
{
Some(crate::ast::MinShouldMatch::Field(field_name.to_string()))
} else if let Some(script) = inner.get("minimum_should_match_script") {
let source = script
.get("source")
.and_then(Value::as_str)
.ok_or_else(|| qerr("`terms_set.minimum_should_match_script` requires a `source`"))?
.to_string();
let params = script.get("params").cloned();
Some(crate::ast::MinShouldMatch::Script { source, params })
} else {
inner
.get("minimum_should_match")
.map(parse_min_should_match)
.and_then(|r| r.ok())
};
let should: Vec<QueryNode> = terms
.iter()
.map(|v| QueryNode::Term {
field: field.clone(),
value: v.clone(),
boost: None,
})
.collect();
Ok(QueryNode::Bool {
must: vec![],
should,
filter: vec![],
must_not: vec![],
minimum_should_match,
})
}
/// `intervals` — position-aware match query. xerj does not implement a full
/// interval automaton; we translate each rule to the closest Bool/Match/Phrase
/// equivalent.
///
/// * `match`: `ordered: true` → `match_phrase` with slop from `max_gaps`
/// (unset → large, effectively ordered-anywhere).
/// `ordered: false` (default) → `match` with operator AND
/// (all query tokens must be present; we do not model gap bounds here).
/// * `prefix`: → `prefix` query.
/// * `wildcard`: → `wildcard` query.
/// * `all_of` / `any_of`: → bool { must / should }.
///
/// ES docs: <https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-intervals-query.html>
fn parse_intervals(params: &Value) -> Result<QueryNode> {
let obj = params
.as_object()
.ok_or_else(|| qerr("`intervals` must be an object"))?;
if obj.len() != 1 {
return invalid("`intervals` query must have exactly one field");
}
let (field, raw) = obj.iter().next().unwrap();
// Emit a specialised `Intervals` node — the executor evaluates the
// rule (match/all_of/any_of/prefix/wildcard/fuzzy, with optional
// filter:) against the field's tokenised positions at query time.
Ok(QueryNode::Intervals {
field: field.clone(),
rule: raw.clone(),
})
}
/// `script_score` — wrap the inner query and apply a Painless script
/// to compute each matched doc's score. The script's returned value
/// REPLACES the BM25 score (boost_mode: Replace).
///
/// ES docs: <https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-script-score-query.html>
fn parse_script_score(params: &Value) -> Result<QueryNode> {
let obj = params
.as_object()
.ok_or_else(|| qerr("`script_score` must be an object"))?;
let inner_query_val = obj
.get("query")
.ok_or_else(|| qerr("`script_score.query` is required"))?;
let inner = parse_query(inner_query_val)?;
// Pull out the script source + params if present.
let script = obj.get("script").and_then(|s| s.as_object());
let source = script.and_then(|s| s.get("source").and_then(|v| v.as_str()).map(String::from));
let s_params = script.and_then(|s| s.get("params").cloned());
// If the script is just a numeric literal (e.g. `"3"`), shortcut
// into the existing literal-score fast path.
let literal_score = source.as_ref().and_then(|s| s.trim().parse::<f32>().ok());
let func = ScoreFunction {
filter: None,
weight: None,
field_value_factor: None,
random_score: None,
script_score: literal_score,
script_source: if literal_score.is_some() {
None
} else {
source
},
script_params: s_params,
name: None,
distance_feature: None,
rank_feature: None,
};
Ok(QueryNode::FunctionScore {
query: Box::new(inner),
functions: vec![func],
score_mode: crate::ast::ScoreMode::Multiply,
// `script_score` replaces the inner query score with the script's
// returned value (the script can incorporate `_score` if it
// wants to combine with the inner score).
boost_mode: crate::ast::BoostMode::Replace,
max_boost: None,
})
}
/// `distance_feature` — date/geo distance proximity scoring. xerj converts
/// this to a `function_score` with a `field_value_factor` on the target field
/// so the query still filters correctly (the proximity score boost is not
/// computed exactly but the field is at least scored).
///
/// ES docs: <https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-distance-feature-query.html>
fn parse_distance_feature(params: &Value) -> Result<QueryNode> {
let obj = params
.as_object()
.ok_or_else(|| qerr("`distance_feature` must be an object"))?;
let field = string_field(obj, "field")?;
let boost = obj.get("boost").and_then(|v| v.as_f64()).map(|b| b as f32);
let pivot = string_field(obj, "pivot")?;
let origin = obj
.get("origin")
.cloned()
.ok_or_else(|| qerr("`distance_feature.origin` is required"))?;
let df = crate::ast::DistanceFeature {
field: field.clone(),
pivot,
origin,
};
Ok(QueryNode::FunctionScore {
// Hybrid: the inner query returns every doc that has the field
// (so the function_score runs on the full candidate set) and
// `boost_mode: replace` substitutes the distance score.
query: Box::new(QueryNode::Exists { field }),
functions: vec![ScoreFunction {
filter: None,
weight: boost,
field_value_factor: None,
random_score: None,
script_score: None,
script_source: None,
script_params: None,
name: None,
distance_feature: Some(df),
rank_feature: None,
}],
score_mode: ScoreMode::Multiply,
boost_mode: BoostMode::Replace,
max_boost: None,
})
}
/// `rank_feature` — logarithmic proximity scoring on a numeric field.
/// Converted to a `function_score` with a `field_value_factor` and `log1p`
/// modifier so the field is scored proportionally to its value.
///
/// ES docs: <https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-rank-feature-query.html>
fn parse_rank_feature(params: &Value) -> Result<QueryNode> {
use crate::ast::{RankFeature, RankFeatureFn};
let obj = params
.as_object()
.ok_or_else(|| qerr("`rank_feature` must be an object"))?;
let field = string_field(obj, "field")?;
let boost = obj.get("boost").and_then(|v| v.as_f64()).map(|b| b as f32);
// Detect which of the four ES functions is requested. Default to
// `saturation` (with the field's default pivot) when none is given.
let function = if let Some(sat) = obj.get("saturation") {
let pivot = sat.get("pivot").and_then(|v| v.as_f64());
RankFeatureFn::Saturation { pivot }
} else if let Some(log) = obj.get("log") {
let scaling_factor = log
.get("scaling_factor")
.and_then(|v| v.as_f64())
.ok_or_else(|| qerr("`rank_feature.log` requires a `scaling_factor`"))?;
RankFeatureFn::Log { scaling_factor }
} else if let Some(sig) = obj.get("sigmoid") {
let pivot = sig
.get("pivot")
.and_then(|v| v.as_f64())
.ok_or_else(|| qerr("`rank_feature.sigmoid` requires a `pivot`"))?;
let exponent = sig
.get("exponent")
.and_then(|v| v.as_f64())
.ok_or_else(|| qerr("`rank_feature.sigmoid` requires an `exponent`"))?;
RankFeatureFn::Sigmoid { pivot, exponent }
} else if obj.contains_key("linear") {
RankFeatureFn::Linear
} else {
RankFeatureFn::Saturation { pivot: None }
};
let rank_feature = RankFeature {
field: field.clone(),
function,
};
Ok(QueryNode::FunctionScore {
// The inner Exists query supplies the candidate set (all docs that
// have the rank_feature field); `boost_mode: replace` substitutes
// the feature's own score for the query score.
query: Box::new(QueryNode::Exists { field }),
functions: vec![ScoreFunction {
filter: None,
weight: boost,
field_value_factor: None,
random_score: None,
script_score: None,
script_source: None,
script_params: None,
name: None,
distance_feature: None,
rank_feature: Some(rank_feature),
}],
score_mode: ScoreMode::Multiply,
boost_mode: BoostMode::Replace,
max_boost: None,
})
}
// ─────────────────────────────────────────────────────────────────────────────
// Tests
// ─────────────────────────────────────────────────────────────────────────────
#[cfg(test)]
mod tests {
use super::*;
use serde_json::json;
fn q(j: serde_json::Value) -> QueryNode {
parse_query(&j).expect("parse failed")
}
/// The window is the engine's to enforce (per-index setting, then the node
/// limit); the parser only bounds the arithmetic at the setting's largest
/// value. A hardcoded 10,000 here overruled `index.max_result_window`.
#[test]
fn parser_leaves_the_result_window_to_the_index() {
let r = parse_request(&json!({ "from": 20_000, "size": 10 }))
.expect("from 20,000 is legal for an index whose window allows it");
assert_eq!((r.from, r.size), (20_000, 10));
assert!(parse_request(&json!({ "from": i32::MAX as u64, "size": 1 })).is_err());
}
// ── #846: minimum_should_match negative / combination specs ───────────────
#[test]
fn msm_parses_negative_and_combination_specs() {
use crate::ast::CombCond;
let p = |v: serde_json::Value| parse_min_should_match(&v).expect("parse msm");
// Negative integer (number AND string spellings) — before #846 the
// number errored ("must be non-negative") and the string dropped to
// Fixed-parse failure; both are now Negative(N) = all-but-N.
assert_eq!(p(json!(-1)), MinShouldMatch::Negative(1));
assert_eq!(p(json!("-2")), MinShouldMatch::Negative(2));
// Plain forms unchanged.
assert_eq!(p(json!(3)), MinShouldMatch::Fixed(3));
assert_eq!(p(json!("75%")), MinShouldMatch::Percentage(75));
// Negative percentage — distinct from Percentage (they round differently).
assert_eq!(p(json!("-25%")), MinShouldMatch::NegativePercentage(25));
// Combination — single and multiple conditions.
assert_eq!(
p(json!("3<90%")),
MinShouldMatch::Combination(vec![CombCond {
pivot: 3,
spec: Box::new(MinShouldMatch::Percentage(90)),
}])
);
assert_eq!(
p(json!("2<-25% 9<-3")),
MinShouldMatch::Combination(vec![
CombCond {
pivot: 2,
spec: Box::new(MinShouldMatch::NegativePercentage(25)),
},
CombCond {
pivot: 9,
spec: Box::new(MinShouldMatch::Negative(3)),
},
])
);
}
#[test]
fn msm_required_resolves_es_semantics() {
// Negative: required = n - N (floored at 0).
assert_eq!(MinShouldMatch::Negative(1).required(4), Some(3));
assert_eq!(MinShouldMatch::Negative(9).required(4), Some(0));
// Negative percentage: required = n - floor(n*P/100); differs from the
// same-looking Percentage on non-divisible counts.
assert_eq!(MinShouldMatch::NegativePercentage(25).required(5), Some(4));
assert_eq!(MinShouldMatch::Percentage(75).required(5), Some(3));
// Combination: n <= every pivot ⇒ all required; else highest pivot < n.
let c = MinShouldMatch::Combination(vec![
crate::ast::CombCond {
pivot: 2,
spec: Box::new(MinShouldMatch::NegativePercentage(25)),
},
crate::ast::CombCond {
pivot: 9,
spec: Box::new(MinShouldMatch::Negative(3)),
},
]);
assert_eq!(c.required(2), Some(2)); // n <= smallest pivot → all
assert_eq!(c.required(5), Some(4)); // pivot 2 applies: 5 - floor(1.25)
assert_eq!(c.required(10), Some(7)); // pivot 9 applies: 10 - 3
}
#[test]
fn msm_negative_survives_through_bool_parse() {
// End-to-end: a bool with `minimum_should_match: -1` no longer errors
// or drops — it lands as Negative(1) on the AST.
match q(json!({"bool": {"should": [
{"term": {"a": "x"}}, {"term": {"b": "y"}}, {"term": {"c": "z"}}
], "minimum_should_match": -1}}))
{
QueryNode::Bool {
minimum_should_match,
..
} => assert_eq!(minimum_should_match, Some(MinShouldMatch::Negative(1))),
other => panic!("expected Bool, got {other:?}"),
}
}
// ── match_all ─────────────────────────────────────────────────────────────
#[test]
fn test_match_all() {
assert_eq!(q(json!({"match_all": {}})), QueryNode::MatchAll);
}
#[test]
fn test_match_all_with_boost() {
// ES scores match_all{boost} as `boost` per hit (constant-score
// semantics) — the boost must not be dropped.
assert_eq!(
q(json!({"match_all": {"boost": 2.0}})),
QueryNode::Constant {
score: 2.0,
query: Box::new(QueryNode::MatchAll),
}
);
}
#[test]
fn test_match_none() {
assert_eq!(q(json!({"match_none": {}})), QueryNode::MatchNone);
}
#[test]
fn test_unresolved_terms_lookup_is_a_loud_error_not_silent_empty() {
// An UNRESOLVED lookup object should never reach the parser on a
// supported endpoint (`_search`/`_count` substitute the value array
// first). If it does — an endpoint that forgot to resolve — this used
// to parse to MatchNone and log a warning, i.e. silently match nothing.
// It must be a hard parse error so the gap is visible.
let err = parse_query(&json!({
"terms": {"user_id": {"index": "customers", "id": "1", "path": "user_id"}}
}));
assert!(
err.is_err(),
"unresolved terms lookup must error, not MatchNone"
);
let msg = format!("{}", err.unwrap_err());
assert!(
msg.contains("terms lookup") && msg.contains("unresolved"),
"error should explain the unresolved-lookup gap, got: {msg}"
);
}
#[test]
fn test_plain_terms_still_parses() {
// The literal-array form is unaffected.
assert!(matches!(
q(json!({"terms": {"svc": ["auth", "checkout"]}})),
QueryNode::Terms { .. }
));
}
// ── match ─────────────────────────────────────────────────────────────────
#[test]
fn test_match_shorthand() {
let node = q(json!({"match": {"title": "hello world"}}));
assert!(
matches!(node, QueryNode::Match { ref field, ref query, operator: BoolOperator::Omitted, .. }
if field == "title" && query == "hello world")
);
}
#[test]
fn test_match_long_form() {
let node = q(json!({
"match": {
"title": {
"query": "hello world",
"operator": "AND",
"analyzer": "english"
}
}
}));
if let QueryNode::Match {
field,
query,
operator,
analyzer,
..
} = node
{
assert_eq!(field, "title");
assert_eq!(query, "hello world");
assert_eq!(operator, BoolOperator::And);
assert_eq!(analyzer, Some("english".to_string()));
} else {
panic!("wrong variant");
}
}
/// #1504: a long-form `match` that leaves `operator` out is not the same
/// node as one that says `"operator": "or"`. The log-index default can
/// fill the gap; it must not override an explicit OR.
#[test]
fn match_without_an_operator_is_omitted_and_explicit_or_is_or() {
let omitted = q(json!({"match": {"message": {"query": "SIP 403 Forbidden"}}}));
match omitted {
QueryNode::Match { operator, .. } => assert_eq!(operator, BoolOperator::Omitted),
other => panic!("expected match, got {other:?}"),
}
let explicit = q(json!({
"match": {"message": {"query": "SIP 403 Forbidden", "operator": "or"}}
}));
match explicit {
QueryNode::Match { operator, .. } => assert_eq!(operator, BoolOperator::Or),
other => panic!("expected match, got {other:?}"),
}
}
// ── track_total_hits ──────────────────────────────────────────────────────
#[test]
fn test_track_total_hits_parsing() {
// Absent → exact tracking at the parser level (the ES 10k default is
// injected by the HTTP layer, NOT here — `_count` and internal
// sub-searches rely on the parser staying exact when unset).
let req = parse_request(&json!({"query": {"match_all": {}}})).unwrap();
assert_eq!(req.track_total_hits, TrackTotalHits::True);
// true → exact.
let req = parse_request(&json!({"track_total_hits": true})).unwrap();
assert_eq!(req.track_total_hits, TrackTotalHits::True);
// false → don't track.
let req = parse_request(&json!({"track_total_hits": false})).unwrap();
assert_eq!(req.track_total_hits, TrackTotalHits::False);
// Integer N → cap at N.
let req = parse_request(&json!({"track_total_hits": 10_000})).unwrap();
assert_eq!(req.track_total_hits, TrackTotalHits::Limit(10_000));
// -1 is the ES alias for `true` (exact), NOT a 10k cap.
let req = parse_request(&json!({"track_total_hits": -1})).unwrap();
assert_eq!(req.track_total_hits, TrackTotalHits::True);
}
// ── match_phrase ──────────────────────────────────────────────────────────
#[test]
fn test_match_phrase_shorthand() {
let node = q(json!({"match_phrase": {"body": "quick brown fox"}}));
assert!(
matches!(node, QueryNode::MatchPhrase { ref field, slop: 0, .. }
if field == "body")
);
}
#[test]
fn test_match_phrase_with_slop() {
let node = q(json!({"match_phrase": {"body": {"query": "quick fox", "slop": 2}}}));
assert!(matches!(node, QueryNode::MatchPhrase { slop: 2, .. }));
}
// ── multi_match ───────────────────────────────────────────────────────────
#[test]
fn test_multi_match_basic() {
let node = q(json!({
"multi_match": {
"query": "hello",
"fields": ["title", "body^2"]
}
}));
if let QueryNode::MultiMatch {
fields,
query,
match_type,
..
} = node
{
assert_eq!(query, "hello");
assert_eq!(fields, vec!["title", "body^2"]);
assert_eq!(match_type, MultiMatchType::BestFields);
} else {
panic!("wrong variant");
}
}
#[test]
fn test_multi_match_cross_fields() {
let node = q(json!({
"multi_match": {
"query": "Will Smith",
"fields": ["first_name", "last_name"],
"type": "cross_fields",
"operator": "AND"
}
}));
assert!(matches!(
node,
QueryNode::MultiMatch {
match_type: MultiMatchType::CrossFields,
..
}
));
}
/// #230 — `slop` and `max_expansions` are phrase parameters of
/// `multi_match`. They used to be dropped here, so `{"type":"phrase",
/// "slop":2}` was accepted and silently answered as an exact phrase.
#[test]
fn test_multi_match_phrase_params_are_parsed() {
let node = q(json!({
"multi_match": {
"query": "quick fox", "fields": ["body"],
"type": "phrase", "slop": 3
}
}));
assert!(matches!(
node,
QueryNode::MultiMatch {
match_type: MultiMatchType::Phrase,
slop: 3,
max_expansions: 50,
..
}
));
let node = q(json!({
"multi_match": {
"query": "quick fo", "fields": ["body"],
"type": "phrase_prefix", "max_expansions": 7
}
}));
assert!(matches!(
node,
QueryNode::MultiMatch {
match_type: MultiMatchType::PhrasePrefix,
slop: 0,
max_expansions: 7,
..
}
));
}
/// Values ES rejects must be rejected here too, not silently coerced.
#[test]
fn test_multi_match_phrase_params_are_validated() {
for bad in [
json!({"multi_match": {"query": "a b", "fields": ["body"],
"type": "phrase", "slop": -1}}),
json!({"multi_match": {"query": "a b", "fields": ["body"],
"type": "phrase", "slop": 4294967296i64}}),
json!({"multi_match": {"query": "a b", "fields": ["body"],
"type": "phrase_prefix", "max_expansions": 0}}),
// ES rejects slop for bool_prefix ONLY
// (MultiMatchQueryBuilder.java:673).
json!({"multi_match": {"query": "a b", "fields": ["body"],
"type": "bool_prefix", "slop": 2}}),
// The same values are rejected on the single-field phrase
// entry points — one JSON value, one answer, whichever query
// wraps it.
json!({"match_phrase": {"body": {"query": "a b", "slop": -1}}}),
json!({"match_phrase_prefix": {"body": {"query": "a b", "slop": -1}}}),
json!({"match_phrase_prefix": {"body": {"query": "a b", "slop": 4294967296i64}}}),
// `max_expansions` used to be read here as
// `as_u64().unwrap_or(50)`, so both of these were accepted and
// silently answered with 50 (#204 class). ES throws "No negative
// maxExpansions allowed" (MatchPhrasePrefixQueryBuilder.java:118).
json!({"match_phrase_prefix": {"body": {"query": "a b", "max_expansions": -1}}}),
json!({"match_phrase_prefix": {"body": {"query": "a b", "max_expansions": "many"}}}),
json!({"match_phrase": {"body": {"query": "a b", "slop": "two"}}}),
] {
assert!(
parse_query(&bad).is_err(),
"expected a parse error for {bad}"
);
}
}
/// Values ES *accepts by coercing* must be accepted here too. ES reads
/// `slop` and `max_expansions` with `XContentParser.intValue()` under the
/// default coercing policy, which truncates a float token and narrows a
/// numeric string (`AbstractXContentParser.java:171` `intValue(coerce)`,
/// `:162` `parseInt`, `:70`), so
/// `{"slop": 2.0}` is a request ES answers with slop 2. Refusing it would
/// be a new 400 on a query that works today, and reading it as 0 would be
/// the accept-and-ignore this parser exists to remove — both are wrong.
#[test]
fn test_phrase_params_are_coerced_like_es() {
for (v, want) in [(json!(2.0), 2u32), (json!(2.9), 2), (json!("2"), 2)] {
let node = q(json!({"match_phrase": {"body": {"query": "a b", "slop": v}}}));
assert!(
matches!(node, QueryNode::MatchPhrase { slop, .. } if slop == want),
"slop {v} must coerce to {want}, parsed to {node:?}"
);
let node = q(json!({"multi_match": {"query": "a b", "fields": ["body"],
"type": "phrase", "slop": v}}));
assert!(
matches!(node, QueryNode::MultiMatch { slop, .. } if slop == want),
"multi_match slop {v} must coerce to {want}, parsed to {node:?}"
);
}
// `max_expansions: 0` is a 400 on `multi_match`
// (MultiMatchQueryBuilder.java:389 rejects `<= 0`) and ACCEPTED on
// `match_phrase_prefix` (MatchPhrasePrefixQueryBuilder.java:118
// rejects only `< 0`). The asymmetry is ES's; XERJ mirrors it rather
// than inventing a rule ES does not have.
let node = q(json!({"match_phrase_prefix": {"body": {"query": "a b",
"max_expansions": 0}}}));
assert!(
matches!(node, QueryNode::MatchPhrasePrefix { max_expansions, .. }
if max_expansions == 0),
"ES accepts max_expansions 0 on match_phrase_prefix, parsed to {node:?}"
);
assert!(
parse_query(&json!({"multi_match": {"query": "a b", "fields": ["body"],
"type": "phrase_prefix",
"max_expansions": 0}}))
.is_err(),
"ES rejects max_expansions 0 on multi_match"
);
}
/// `slop` + `type: phrase_prefix` is ACCEPTED and carried, at BOTH
/// entry points. ES honours it (`MultiMatchQueryBuilder` rejects slop
/// only for `bool_prefix`; `TextFieldMapper.createPhrasePrefixQuery`
/// calls `MultiPhrasePrefixQuery.setSlop`), so refusing it would be a
/// wire-compat break — and dropping it, as `parse_match_phrase_prefix`
/// used to, is the accept-and-ignore defect class of #204.
#[test]
fn test_phrase_prefix_slop_is_carried_at_both_entry_points() {
let node = q(json!({
"multi_match": {"query": "quick fo", "fields": ["body"],
"type": "phrase_prefix", "slop": 2}
}));
assert!(
matches!(
node,
QueryNode::MultiMatch {
match_type: MultiMatchType::PhrasePrefix,
slop: 2,
..
}
),
"multi_match phrase_prefix must carry slop, got {node:?}"
);
let node = q(json!({
"match_phrase_prefix": {"body": {"query": "quick fo", "slop": 2}}
}));
assert!(
matches!(node, QueryNode::MatchPhrasePrefix { slop: 2, .. }),
"match_phrase_prefix must carry slop, got {node:?}"
);
// Absent slop is 0 at both entry points.
let node = q(json!({"match_phrase_prefix": {"body": "quick fo"}}));
assert!(matches!(node, QueryNode::MatchPhrasePrefix { slop: 0, .. }));
}
// ── term ──────────────────────────────────────────────────────────────────
#[test]
fn test_term_shorthand() {
let node = q(json!({"term": {"status": "active"}}));
assert!(matches!(node, QueryNode::Term { ref field, ref value, .. }
if field == "status" && *value == json!("active")));
}
#[test]
fn test_term_long_form() {
let node = q(json!({"term": {"status": {"value": "active", "boost": 1.5}}}));
assert!(matches!(node, QueryNode::Term { boost: Some(b), .. } if (b - 1.5).abs() < 0.001));
}
#[test]
fn test_term_numeric() {
let node = q(json!({"term": {"age": 30}}));
assert!(matches!(node, QueryNode::Term { ref field, ref value, .. }
if field == "age" && *value == json!(30)));
}
// ── terms ─────────────────────────────────────────────────────────────────
#[test]
fn test_terms() {
let node = q(json!({"terms": {"status": ["active", "pending"]}}));
if let QueryNode::Terms { field, values, .. } = node {
assert_eq!(field, "status");
assert_eq!(values, vec![json!("active"), json!("pending")]);
} else {
panic!("wrong variant");
}
}
// ── range ─────────────────────────────────────────────────────────────────
#[test]
fn test_range_numeric() {
let node = q(json!({"range": {"age": {"gte": 18, "lt": 65}}}));
if let QueryNode::Range {
field,
gte,
lt,
gt,
lte,
..
} = node
{
assert_eq!(field, "age");
assert_eq!(gte, Some(json!(18)));
assert_eq!(lt, Some(json!(65)));
assert_eq!(gt, None);
assert_eq!(lte, None);
} else {
panic!("wrong variant");
}
}
#[test]
fn test_range_date_time_zone() {
let node = q(json!({"range": {"date": {
"gte": "2024-03-10", "lt": "2024-03-11", "time_zone": "+05:30"
}}}));
if let QueryNode::Range { gte, lt, .. } = node {
assert_eq!(gte, Some(json!("2024-03-09T18:30:00.000Z")));
assert_eq!(lt, Some(json!("2024-03-10T18:30:00.000Z")));
} else {
panic!("wrong variant");
}
let err = parse_query(
&json!({"range": {"date": {"gte": "2024-03-10", "time_zone": "Mars/Base"}}}),
);
assert!(err.is_err(), "an unknown time_zone must be rejected");
}
#[test]
fn test_range_date() {
let node = q(json!({"range": {"date": {"gte": "2024-01-01", "lte": "2024-12-31"}}}));
assert!(matches!(node, QueryNode::Range { ref field, .. } if field == "date"));
}
#[test]
fn test_range_no_bounds_fails() {
assert!(parse_query(&json!({"range": {"age": {}}})).is_err());
}
// ── prefix ────────────────────────────────────────────────────────────────
#[test]
fn test_prefix_shorthand() {
let node = q(json!({"prefix": {"name": "Joh"}}));
assert!(
matches!(node, QueryNode::Prefix { ref field, ref value, .. }
if field == "name" && value == "Joh")
);
}
#[test]
fn test_prefix_long_form() {
let node = q(json!({"prefix": {"name": {"value": "Joh", "boost": 2.0}}}));
assert!(matches!(node, QueryNode::Prefix { ref value, .. } if value == "Joh"));
}
// ── wildcard ──────────────────────────────────────────────────────────────
#[test]
fn test_wildcard() {
let node = q(json!({"wildcard": {"name": "Jo*n"}}));
assert!(
matches!(node, QueryNode::Wildcard { ref field, ref value, .. }
if field == "name" && value == "Jo*n")
);
}
// ── exists ────────────────────────────────────────────────────────────────
#[test]
fn test_exists() {
let node = q(json!({"exists": {"field": "email"}}));
assert!(matches!(node, QueryNode::Exists { ref field } if field == "email"));
}
// ── ids ───────────────────────────────────────────────────────────────────
#[test]
fn test_ids() {
let node = q(json!({"ids": {"values": ["abc", "def", "123"]}}));
if let QueryNode::Ids { values } = node {
assert_eq!(values, vec!["abc", "def", "123"]);
} else {
panic!("wrong variant");
}
}
// ── script ────────────────────────────────────────────────────────────────
#[test]
fn test_script_query() {
let node = q(json!({
"script": {
"script": {
"source": "doc['x'].value > params.min",
"params": {"min": 5}
}
}
}));
if let QueryNode::Script { source, params } = node {
assert_eq!(source, "doc['x'].value > params.min");
assert_eq!(params, Some(json!({"min": 5})));
} else {
panic!("wrong variant");
}
}
#[test]
fn test_script_query_no_params() {
let node = q(json!({"script": {"script": {"source": "true"}}}));
if let QueryNode::Script { source, params } = node {
assert_eq!(source, "true");
assert_eq!(params, None);
} else {
panic!("wrong variant");
}
}
#[test]
fn test_script_query_missing_source_errs() {
let result = parse_query(&json!({"script": {"script": {}}}));
assert!(result.is_err());
}
// ── bool ──────────────────────────────────────────────────────────────────
#[test]
fn test_bool_basic() {
let node = q(json!({
"bool": {
"must": [{"term": {"status": "active"}}],
"must_not": [{"term": {"deleted": true}}],
"filter": [{"range": {"age": {"gte": 18}}}]
}
}));
if let QueryNode::Bool {
must,
must_not,
filter,
should,
..
} = node
{
assert_eq!(must.len(), 1);
assert_eq!(must_not.len(), 1);
assert_eq!(filter.len(), 1);
assert!(should.is_empty());
} else {
panic!("wrong variant");
}
}
#[test]
fn test_bool_single_must_not_array() {
let node = q(json!({
"bool": {
"must": {"match": {"title": "rust"}}
}
}));
if let QueryNode::Bool { must, .. } = node {
assert_eq!(must.len(), 1);
}
}
#[test]
fn test_bool_empty_is_match_all() {
let node = q(json!({"bool": {}}));
assert_eq!(node, QueryNode::MatchAll);
}
#[test]
fn test_bool_minimum_should_match() {
let node = q(json!({
"bool": {
"should": [
{"term": {"tag": "a"}},
{"term": {"tag": "b"}},
{"term": {"tag": "c"}}
],
"minimum_should_match": 2
}
}));
if let QueryNode::Bool {
minimum_should_match,
..
} = node
{
assert_eq!(minimum_should_match, Some(MinShouldMatch::Fixed(2)));
}
}
#[test]
fn test_bool_minimum_should_match_pct() {
let node = q(json!({
"bool": {
"should": [{"term": {"tag": "a"}}],
"minimum_should_match": "75%"
}
}));
if let QueryNode::Bool {
minimum_should_match,
..
} = node
{
assert_eq!(minimum_should_match, Some(MinShouldMatch::Percentage(75)));
}
}
// ── constant_score ────────────────────────────────────────────────────────
#[test]
fn test_constant_score() {
// constant_score keeps its Constant wrapper: ES scores every hit as
// exactly `boost` (default 1.0), NOT the inner query's score — the
// old flatten returned the inner term's brute score (live-diverged
// vs ES 8.13.4). Matching fast paths peel the wrapper instead.
let node = q(json!({
"constant_score": {
"filter": {"term": {"status": "active"}},
"boost": 1.5
}
}));
match node {
QueryNode::Constant { score, query } => {
assert_eq!(score, 1.5);
assert!(matches!(*query, QueryNode::Term { .. }));
}
other => panic!("expected Constant wrapper, got {other:?}"),
}
}
#[test]
fn test_constant_score_default_boost() {
let node = q(json!({
"constant_score": {"filter": {"term": {"status": "active"}}}
}));
match node {
QueryNode::Constant { score, .. } => assert_eq!(score, 1.0),
other => panic!("expected Constant wrapper, got {other:?}"),
}
}
// ── parent-child join (unsupported) ────────────────────────────────────────
#[test]
fn test_has_child_rejected() {
// Parent-child joins are not materialized in XERJ; parsing must
// fail loud (400) rather than build an AST node that silently runs
// the inner query on flat docs.
let err = parse_query(&json!({
"has_child": {
"type": "answer",
"query": { "match": { "body": "hello" } }
}
}))
.unwrap_err();
assert!(
format!("{err}").contains("parent-child join queries"),
"unexpected error: {err}"
);
}
#[test]
fn test_has_parent_rejected() {
let err = parse_query(&json!({
"has_parent": {
"parent_type": "question",
"query": { "match": { "body": "hello" } }
}
}))
.unwrap_err();
assert!(
format!("{err}").contains("parent-child join queries"),
"unexpected error: {err}"
);
}
// ── query_string ──────────────────────────────────────────────────────────
#[test]
fn test_query_string() {
// `field:value AND field:value` is lowered into a Bool tree by
// try_lower_query_string so the FTS / planner fast paths apply.
// The opaque QueryString variant is kept only for inputs the
// lowerer can't translate.
let node = q(json!({
"query_string": {
"query": "title:rust AND body:ownership",
"default_field": "title"
}
}));
assert!(matches!(node, QueryNode::Bool { .. }));
}
fn qs(query: &str) -> QueryNode {
q(json!({"query_string": {"query": query}}))
}
fn expect_range(
node: QueryNode,
) -> (
String,
Option<Value>,
Option<Value>,
Option<Value>,
Option<Value>,
) {
match node {
QueryNode::Range {
field,
gt,
gte,
lt,
lte,
..
} => (field, gt, gte, lt, lte),
other => panic!("expected Range, got {other:?}"),
}
}
#[test]
fn test_query_string_range_gt() {
let (field, gt, gte, lt, lte) = expect_range(qs("n:>1"));
assert_eq!(field, "n");
assert_eq!(gt, Some(json!(1)));
assert!(gte.is_none() && lt.is_none() && lte.is_none());
}
#[test]
fn test_query_string_range_gte() {
let (field, gt, gte, lt, lte) = expect_range(qs("n:>=2"));
assert_eq!(field, "n");
assert_eq!(gte, Some(json!(2)));
assert!(gt.is_none() && lt.is_none() && lte.is_none());
}
#[test]
fn test_query_string_range_lt() {
let (field, gt, gte, lt, lte) = expect_range(qs("n:<5"));
assert_eq!(field, "n");
assert_eq!(lt, Some(json!(5)));
assert!(gt.is_none() && gte.is_none() && lte.is_none());
}
#[test]
fn test_query_string_range_lte() {
let (field, _, _, _, lte) = expect_range(qs("n:<=5"));
assert_eq!(field, "n");
assert_eq!(lte, Some(json!(5)));
}
/// The `query` of each bare `Match` in `nodes`, in order.
fn match_terms(nodes: &[QueryNode]) -> Vec<&str> {
nodes
.iter()
.map(|n| match n {
QueryNode::Match { query, .. } => query.as_str(),
other => panic!("expected a bare match, got {other:?}"),
})
.collect()
}
/// One query-string boolean level as (must, should, must_not, msm).
fn occurs(
query: &str,
default_operator: Option<&str>,
) -> (
Vec<String>,
Vec<String>,
Vec<String>,
Option<MinShouldMatch>,
) {
let mut body = json!({"query": query, "default_field": "t"});
if let Some(op) = default_operator {
body["default_operator"] = json!(op);
}
match q(json!({ "query_string": body })) {
QueryNode::Bool {
must,
should,
must_not,
minimum_should_match,
..
} => {
let own = |v: &[QueryNode]| match_terms(v).into_iter().map(String::from).collect();
(
own(&must),
own(&should),
own(&must_not),
minimum_should_match,
)
}
other => panic!("{query}: expected a Bool, got {other:?}"),
}
}
fn strs(v: &[&str]) -> Vec<String> {
v.iter().map(|s| s.to_string()).collect()
}
/// #1299: a prohibited clause excludes from its whole level. `alpha
/// -beta` used to lower to `alpha OR (NOT beta)`, whose pure-negative
/// branch matched every document without `beta`.
#[test]
fn query_string_negation_excludes_from_the_whole_level() {
let one = Some(MinShouldMatch::Fixed(1));
for query in [
"alpha -beta",
"-beta alpha",
"alpha NOT beta",
"alpha OR -beta",
] {
assert_eq!(
occurs(query, None),
(vec![], strs(&["alpha"]), strs(&["beta"]), one.clone()),
"{query}"
);
}
assert_eq!(
occurs("alpha beta -gamma", None),
(vec![], strs(&["alpha", "beta"]), strs(&["gamma"]), one)
);
// `+` makes a clause required and the rest only score.
assert_eq!(
occurs("+alpha beta -gamma", None),
(strs(&["alpha"]), strs(&["beta"]), strs(&["gamma"]), None)
);
}
/// Mixed `AND` / `OR` follow Lucene's classic parser, as ES 8.13.4 does:
/// `AND` makes the clause before it required too, and under
/// `default_operator: AND` an `OR` makes the clause before it optional.
#[test]
fn query_string_mixed_operators_follow_the_classic_parser() {
assert_eq!(
occurs("kiwi OR lime AND plum", None),
(strs(&["lime", "plum"]), strs(&["kiwi"]), vec![], None)
);
assert_eq!(
occurs("kiwi AND lime OR plum", None),
(strs(&["kiwi", "lime"]), strs(&["plum"]), vec![], None)
);
assert_eq!(
occurs("kiwi AND NOT lime OR plum", None),
(strs(&["kiwi"]), strs(&["plum"]), strs(&["lime"]), None)
);
assert_eq!(
occurs("kiwi OR lime plum", Some("AND")),
(strs(&["plum"]), strs(&["kiwi", "lime"]), vec![], None)
);
assert_eq!(
occurs("-kiwi lime OR plum", Some("AND")),
(
vec![],
strs(&["lime", "plum"]),
strs(&["kiwi"]),
Some(MinShouldMatch::Fixed(1))
)
);
}
/// Every (field, value) leaf of a lowered query_string, in tree order.
fn qs_leaves(node: &QueryNode) -> Vec<(String, String)> {
fn walk(n: &QueryNode, out: &mut Vec<(String, String)>) {
match n {
QueryNode::Match { field, query, .. }
| QueryNode::MatchPhrase { field, query, .. } => {
out.push((field.clone(), query.clone()))
}
QueryNode::Wildcard { field, value, .. } => {
out.push((field.clone(), value.clone()))
}
QueryNode::Range { field, .. } => out.push((field.clone(), "<range>".into())),
QueryNode::Bool {
must,
should,
must_not,
filter,
..
} => {
for c in must.iter().chain(should).chain(must_not).chain(filter) {
walk(c, out);
}
}
QueryNode::DisMax { queries, .. } => queries.iter().for_each(|c| walk(c, out)),
QueryNode::Boosted { query, .. } => walk(query, out),
other => panic!("unexpected leaf {other:?}"),
}
}
let mut out = Vec::new();
walk(node, &mut out);
out
}
fn pairs(v: &[(&str, &str)]) -> Vec<(String, String)> {
v.iter()
.map(|(f, q)| (f.to_string(), q.to_string()))
.collect()
}
/// #1298: `field:( … )` scopes the whole group to `field`. It used to
/// lower to an empty-valued `Match` on `field` plus the group's terms on
/// the `*` placeholder, so the group searched every field.
#[test]
fn query_string_field_group_is_scoped_to_the_field() {
assert_eq!(qs_leaves(&qs("title:(beta)")), pairs(&[("title", "beta")]));
assert_eq!(qs_leaves(&qs("title: (beta)")), pairs(&[("title", "beta")]));
assert_eq!(
qs_leaves(&qs("title:(alpha OR (beta AND gamma))")),
pairs(&[("title", "alpha"), ("title", "beta"), ("title", "gamma")])
);
// Phrases and wildcards inside the group land on the field too.
assert_eq!(
qs_leaves(&qs("title:(\"alpha beta\" alp*)")),
pairs(&[("title", "alpha beta"), ("title", "alp*")])
);
// A clause that names its own field keeps it, as in ES.
assert_eq!(
qs_leaves(&qs("title:(alpha OR body:gamma)")),
pairs(&[("title", "alpha"), ("body", "gamma")])
);
// The group's field beats `default_field` / `fields`.
let with_default =
q(json!({"query_string": {"query": "title:(beta)", "default_field": "body"}}));
assert_eq!(qs_leaves(&with_default), pairs(&[("title", "beta")]));
let with_fields =
q(json!({"query_string": {"query": "title:(beta)", "fields": ["body", "x"]}}));
assert_eq!(qs_leaves(&with_fields), pairs(&[("title", "beta")]));
}
/// #1298: an unqualified range inside `n:( … )` has a concrete field and
/// lowers to a `Range` on it. It used to be refused ("requires an
/// explicit field").
#[test]
fn query_string_range_inside_a_field_group_targets_the_field() {
assert_eq!(qs_leaves(&qs("n:(>4)")), pairs(&[("n", "<range>")]));
assert_eq!(qs_leaves(&qs("n:([2 TO 8])")), pairs(&[("n", "<range>")]));
// Outside any field group the old refusal still holds.
assert!(parse_query(&json!({"query_string": {"query": "(>4)"}})).is_err());
}
/// `default_operator` reaches inside a group: ES 8.13.4 requires both
/// terms for `(alpha beta)` with `AND`. Groups used to be implicitly OR.
#[test]
fn query_string_default_operator_applies_inside_a_group() {
for query in ["title:(alpha beta)", "(alpha beta)"] {
let node = q(json!({"query_string": {
"query": query, "default_field": "title", "default_operator": "AND"
}}));
match node {
QueryNode::Bool { must, should, .. } => {
assert_eq!(must.len(), 2, "{query}: {must:?}");
assert!(should.is_empty(), "{query}: {should:?}");
}
other => panic!("{query}: expected a Bool, got {other:?}"),
}
}
}
/// `query_string`'s `fields` was accepted and ignored — the key never
/// reached this parser, so the query ran over every field regardless. It
/// now selects the targets for an unqualified clause, the same way
/// `simple_query_string`'s `fields` already did.
#[test]
fn test_query_string_fields_select_the_unqualified_targets() {
// One field is exactly `default_field`.
match q(json!({"query_string": {"query": "hello", "fields": ["title"]}})) {
QueryNode::Match { field, query, .. } => {
assert_eq!(field, "title");
assert_eq!(query, "hello");
}
other => panic!("expected Match on title, got {other:?}"),
}
// Several become a dis_max over one leaf per field, and `^boost` on a
// spec lands on that leaf.
match q(json!({"query_string": {"query": "hello", "fields": ["title^3", "body"]}})) {
QueryNode::DisMax { queries, .. } => {
assert_eq!(queries.len(), 2);
match &queries[0] {
QueryNode::Match { field, boost, .. } => {
assert_eq!(field, "title");
assert_eq!(*boost, Some(3.0));
}
other => panic!("expected boosted Match on title, got {other:?}"),
}
match &queries[1] {
QueryNode::Match { field, boost, .. } => {
assert_eq!(field, "body");
assert_eq!(*boost, None);
}
other => panic!("expected Match on body, got {other:?}"),
}
}
other => panic!("expected DisMax, got {other:?}"),
}
// A clause that names its own field keeps it: `fields` only supplies
// the target for clauses that named none, as in ES.
match q(json!({"query_string": {"query": "body:hello", "fields": ["title"]}})) {
QueryNode::Match { field, .. } => assert_eq!(field, "body"),
other => panic!("expected Match on body, got {other:?}"),
}
// With no `fields` and no `default_field` nothing changes: the
// field-less `"*"` placeholder is still what an unqualified clause
// resolves to.
match qs("hello") {
QueryNode::Match { field, .. } => assert_eq!(field, "*"),
other => panic!("expected Match on *, got {other:?}"),
}
// An unqualified range now resolves against `fields` too, instead of
// erroring for want of a `default_field`.
match q(json!({"query_string": {"query": ">10", "fields": ["n"]}})) {
QueryNode::Range { field, gt, .. } => {
assert_eq!(field, "n");
assert_eq!(gt, Some(json!(10)));
}
other => panic!("expected Range on n, got {other:?}"),
}
}
#[test]
fn test_query_string_range_inclusive_brackets() {
let (field, gt, gte, lt, lte) = expect_range(qs("n:[2 TO 5]"));
assert_eq!(field, "n");
assert_eq!(gte, Some(json!(2)));
assert_eq!(lte, Some(json!(5)));
assert!(gt.is_none() && lt.is_none());
}
#[test]
fn test_query_string_range_exclusive_brackets() {
let (field, gt, gte, lt, lte) = expect_range(qs("n:{2 TO 5}"));
assert_eq!(field, "n");
assert_eq!(gt, Some(json!(2)));
assert_eq!(lt, Some(json!(5)));
assert!(gte.is_none() && lte.is_none());
}
#[test]
fn test_query_string_range_mixed_brackets() {
let (field, gt, gte, lt, lte) = expect_range(qs("n:[2 TO 5}"));
assert_eq!(field, "n");
assert_eq!(gte, Some(json!(2)));
assert_eq!(lt, Some(json!(5)));
assert!(gt.is_none() && lte.is_none());
}
#[test]
fn test_query_string_range_open_upper() {
let (field, gt, gte, lt, lte) = expect_range(qs("n:[2 TO *]"));
assert_eq!(field, "n");
assert_eq!(gte, Some(json!(2)));
assert!(gt.is_none() && lt.is_none() && lte.is_none());
}
#[test]
fn test_query_string_range_open_lower() {
let (field, gt, gte, lt, lte) = expect_range(qs("n:[* TO 5]"));
assert_eq!(field, "n");
assert_eq!(lte, Some(json!(5)));
assert!(gt.is_none() && gte.is_none() && lt.is_none());
}
#[test]
fn test_query_string_range_negative_and_float() {
let (_, gt, ..) = expect_range(qs("n:>-1"));
assert_eq!(gt, Some(json!(-1)));
let (_, gt, ..) = expect_range(qs("n:>1.5"));
assert_eq!(gt, Some(json!(1.5)));
}
#[test]
fn test_query_string_range_date() {
// Date bounds resolve with ES rounding semantics: `>` (exclusive
// lower) rounds UP to the last ms of the covered day, `>=`/`<=`
// round down/up respectively — live-verified vs ES 8.13.4.
let (field, gt, ..) = expect_range(qs("ts:>2020-01-01"));
assert_eq!(field, "ts");
assert_eq!(gt, Some(json!("2020-01-01T23:59:59.999Z")));
let (field, _, gte, _, lte) = expect_range(qs("ts:[2020-01-01 TO 2020-12-31]"));
assert_eq!(field, "ts");
assert_eq!(gte, Some(json!("2020-01-01T00:00:00.000Z")));
assert_eq!(lte, Some(json!("2020-12-31T23:59:59.999Z")));
}
#[test]
fn test_query_string_range_combined_and() {
// "msg:foo AND n:>1" → Bool.must = [Match(msg), Range(n, gt 1)]
let node = qs("msg:foo AND n:>1");
let QueryNode::Bool {
must,
must_not,
should,
..
} = node
else {
panic!("expected Bool");
};
assert!(must_not.is_empty() && should.is_empty());
assert_eq!(must.len(), 2);
assert!(matches!(&must[0], QueryNode::Match { field, .. } if field == "msg"));
let (field, gt, ..) = expect_range(must[1].clone());
assert_eq!(field, "n");
assert_eq!(gt, Some(json!(1)));
}
#[test]
fn test_query_string_range_combined_bracket_and() {
let node = qs("msg:foo AND n:[2 TO *]");
let QueryNode::Bool { must, .. } = node else {
panic!("expected Bool")
};
assert_eq!(must.len(), 2);
let (field, _, gte, ..) = expect_range(must[1].clone());
assert_eq!(field, "n");
assert_eq!(gte, Some(json!(2)));
}
#[test]
fn test_query_string_range_default_field() {
// Unqualified range resolves against default_field.
let node = q(json!({
"query_string": {"query": ">10", "default_field": "n"}
}));
let (field, gt, ..) = expect_range(node);
assert_eq!(field, "n");
assert_eq!(gt, Some(json!(10)));
}
#[test]
fn test_query_string_range_errors_do_not_degrade() {
// Malformed / unrepresentable ranges must be parse errors,
// never a silent term match.
for bad in [
"n:[2 TO", // unterminated bracket
"n:[2 5]", // missing TO
"n:>", // missing value
"n:[* TO *]", // no usable bound
">10", // no field and no default_field
] {
let res = parse_query(&json!({"query_string": {"query": bad}}));
assert!(
res.is_err(),
"expected parse error for {bad:?}, got {res:?}"
);
}
}
// ── knn ───────────────────────────────────────────────────────────────────
#[test]
fn test_knn() {
let node = q(json!({
"knn": {
"field": "embedding",
"query_vector": [0.1, 0.2, 0.3],
"k": 5
}
}));
if let QueryNode::Knn {
field,
vector,
k,
filter,
..
} = node
{
assert_eq!(field, "embedding");
assert_eq!(k, 5);
assert_eq!(vector.len(), 3);
assert!(filter.is_none());
} else {
panic!("wrong variant");
}
}
#[test]
fn test_knn_num_candidates_independent_of_k() {
// num_candidates is carried through as its own value; k stays explicit.
let node = q(json!({
"knn": {
"field": "embedding",
"query_vector": [0.1, 0.2, 0.3],
"k": 3,
"num_candidates": 50
}
}));
match node {
QueryNode::Knn {
k, num_candidates, ..
} => {
assert_eq!(k, 3);
assert_eq!(num_candidates, Some(50));
}
other => panic!("expected knn, got {:?}", other),
}
}
#[test]
fn test_knn_k_defaults_to_num_candidates_when_k_omitted() {
// With k omitted, k still derives from num_candidates (unchanged).
let node = q(json!({
"knn": {
"field": "embedding",
"query_vector": [0.1],
"num_candidates": 7
}
}));
match node {
QueryNode::Knn {
k, num_candidates, ..
} => {
assert_eq!(k, 7);
assert_eq!(num_candidates, Some(7));
}
other => panic!("expected knn, got {:?}", other),
}
}
#[test]
fn test_knn_with_filter() {
let node = q(json!({
"knn": {
"field": "embedding",
"query_vector": [0.1, 0.2],
"k": 10,
"filter": {"term": {"status": "active"}}
}
}));
assert!(matches!(
node,
QueryNode::Knn {
filter: Some(_),
..
}
));
}
// ── full request ──────────────────────────────────────────────────────────
#[test]
fn test_parse_full_request() {
let body = json!({
"query": {
"bool": {
"must": [{"match": {"title": "rust"}}],
"filter": [{"term": {"status": "published"}}]
}
},
"from": 20,
"size": 5,
"sort": [{"date": "desc"}, "_score"],
"_source": ["title", "date"],
"explain": true
});
let req = parse_request(&body).expect("parse_request failed");
assert_eq!(req.from, 20);
assert_eq!(req.size, 5);
assert_eq!(req.sort.len(), 2);
assert!(req.explain);
assert!(matches!(req.query, QueryNode::Bool { .. }));
}
#[test]
fn test_parse_request_defaults() {
let req = parse_request(&json!({})).expect("should default to match_all");
assert_eq!(req.query, QueryNode::MatchAll);
assert_eq!(req.from, 0);
assert_eq!(req.size, 10);
}
// ── error cases ───────────────────────────────────────────────────────────
#[test]
fn test_unknown_query_type_error() {
let err = parse_query(&json!({"fuzzy_wuzzy": {}})).unwrap_err();
assert!(err.to_string().contains("fuzzy_wuzzy"));
}
#[test]
fn test_multi_key_object_error() {
let err = parse_query(&json!({"match": {}, "term": {}})).unwrap_err();
assert!(err.to_string().contains("exactly one key"));
}
#[test]
fn test_hybrid_query() {
let node = q(json!({
"hybrid": {
"queries": [
{"query": {"match": {"title": "rust"}}, "weight": 0.7},
{"query": {"knn": {"field": "vec", "query_vector": [0.1], "k": 5}}, "weight": 0.3}
],
"fusion": "rrf"
}
}));
if let QueryNode::Hybrid { queries, fusion } = node {
assert_eq!(queries.len(), 2);
assert!((queries[0].weight - 0.7).abs() < 0.001);
assert!(matches!(fusion, FusionStrategy::Rrf { k: 60 }));
} else {
panic!("wrong variant");
}
}
#[test]
fn hybrid_item_missing_query_names_the_query_weight_shape() {
let err = parse_query(&json!({
"hybrid": {
"queries": [
{"weight": 1.0},
{"query": {"match_all": {}}}
]
}
}))
.unwrap_err();
let msg = err.to_string();
assert!(msg.contains("`hybrid.queries[0]` missing `query`"), "{msg}");
assert!(
msg.contains("{\"query\": <clause>, \"weight\": <number>}"),
"{msg}"
);
assert!(msg.contains("weight defaults to 1"), "{msg}");
let err = parse_query(&json!({
"hybrid": { "queries": ["rotate keys"] }
}))
.unwrap_err();
let msg = err.to_string();
assert!(
msg.contains(
"`hybrid.queries[0]` must be an object {\"query\": <clause>, \"weight\": <number>}"
),
"{msg}"
);
}
#[test]
fn test_hybrid_learned_rejected() {
// Learned fusion is not implemented — must fail loud rather than
// silently substituting RRF. Both the string and object forms.
for fusion in [json!("learned"), json!({ "type": "learned" })] {
let err = parse_query(&json!({
"hybrid": {
"queries": [
{"query": {"match": {"title": "rust"}}},
{"query": {"match": {"title": "go"}}}
],
"fusion": fusion
}
}))
.unwrap_err();
assert!(
format!("{err}").contains("learned is not yet supported"),
"unexpected error: {err}"
);
}
}
#[test]
fn test_nested_bool() {
let node = q(json!({
"bool": {
"must": [
{
"bool": {
"should": [
{"term": {"tag": "rust"}},
{"term": {"tag": "systems"}}
]
}
},
{"range": {"year": {"gte": 2020}}}
]
}
}));
assert!(matches!(node, QueryNode::Bool { .. }));
}
// ── percolate ─────────────────────────────────────────────────────────────
#[test]
fn test_percolate_single_document() {
let node = q(json!({
"percolate": { "field": "query", "document": { "message": "hi" } }
}));
match node {
QueryNode::Percolate { field, documents } => {
assert_eq!(field, "query");
assert_eq!(documents.len(), 1);
assert_eq!(documents[0]["message"], json!("hi"));
}
other => panic!("expected percolate, got {:?}", other),
}
}
#[test]
fn test_percolate_multiple_documents() {
let node = q(json!({
"percolate": {
"field": "query",
"documents": [ { "message": "a" }, { "message": "b" } ]
}
}));
match node {
QueryNode::Percolate { documents, .. } => assert_eq!(documents.len(), 2),
other => panic!("expected percolate, got {:?}", other),
}
}
#[test]
fn test_percolate_missing_document_is_400() {
// Neither `document` nor `documents` present.
assert!(parse_query(&json!({ "percolate": { "field": "query" } })).is_err());
// Index/id fetch form is rejected.
assert!(parse_query(&json!({
"percolate": { "field": "query", "index": "i", "id": "1" }
}))
.is_err());
// Missing field is rejected.
assert!(parse_query(&json!({
"percolate": { "document": { "m": "x" } }
}))
.is_err());
}
// ── span_containing / span_within ───────────────────────────────────────
#[test]
fn test_span_containing_parses_little_and_big() {
let node = q(json!({
"span_containing": {
"little": { "span_term": { "text": "brown" } },
"big": {
"span_near": {
"clauses": [
{ "span_term": { "text": "quick" } },
{ "span_term": { "text": "fox" } }
],
"slop": 3,
"in_order": true
}
}
}
}));
match node {
QueryNode::SpanContaining { little, big } => {
assert!(matches!(*little, QueryNode::SpanTerm { .. }));
assert!(matches!(*big, QueryNode::SpanNear { .. }));
}
other => panic!("expected span_containing, got {:?}", other),
}
}
#[test]
fn test_span_within_variant() {
let node = q(json!({
"span_within": {
"little": { "span_term": { "text": "brown" } },
"big": { "span_term": { "text": "quick" } }
}
}));
assert!(matches!(node, QueryNode::SpanWithin { .. }));
}
#[test]
fn test_span_containing_missing_clause_is_400() {
assert!(parse_query(&json!({
"span_containing": { "big": { "span_term": { "text": "x" } } }
}))
.is_err());
assert!(parse_query(&json!({
"span_within": { "little": { "span_term": { "text": "x" } } }
}))
.is_err());
}
// ── terms_set minimum_should_match_field / _script ──────────────────────
#[test]
fn test_terms_set_minimum_should_match_field() {
let node = q(json!({
"terms_set": {
"codes": {
"terms": ["a", "b", "c"],
"minimum_should_match_field": "required"
}
}
}));
match node {
QueryNode::Bool {
minimum_should_match: Some(MinShouldMatch::Field(name)),
should,
..
} => {
assert_eq!(name, "required");
assert_eq!(should.len(), 3);
}
other => panic!("expected bool w/ field msm, got {:?}", other),
}
}
#[test]
fn test_terms_set_minimum_should_match_script() {
let node = q(json!({
"terms_set": {
"codes": {
"terms": ["a", "b"],
"minimum_should_match_script": { "source": "params.num_terms" }
}
}
}));
match node {
QueryNode::Bool {
minimum_should_match: Some(MinShouldMatch::Script { source, .. }),
..
} => assert_eq!(source, "params.num_terms"),
other => panic!("expected bool w/ script msm, got {:?}", other),
}
}
// ── rank_feature ────────────────────────────────────────────────────────
fn rank_feature_fn(body: serde_json::Value) -> crate::ast::RankFeatureFn {
use crate::ast::QueryNode;
match q(body) {
QueryNode::FunctionScore {
functions,
boost_mode,
..
} => {
assert_eq!(boost_mode, crate::ast::BoostMode::Replace);
functions[0]
.rank_feature
.as_ref()
.expect("rank_feature payload present")
.function
.clone()
}
other => panic!("expected function_score, got {:?}", other),
}
}
#[test]
fn test_rank_feature_saturation_with_pivot() {
let f = rank_feature_fn(json!({
"rank_feature": { "field": "pagerank", "saturation": { "pivot": 8 } }
}));
assert_eq!(
f,
crate::ast::RankFeatureFn::Saturation { pivot: Some(8.0) }
);
}
#[test]
fn test_rank_feature_defaults_to_saturation() {
let f = rank_feature_fn(json!({ "rank_feature": { "field": "pagerank" } }));
assert_eq!(f, crate::ast::RankFeatureFn::Saturation { pivot: None });
}
#[test]
fn test_rank_feature_log_sigmoid_linear() {
assert_eq!(
rank_feature_fn(json!({
"rank_feature": { "field": "pr", "log": { "scaling_factor": 4 } }
})),
crate::ast::RankFeatureFn::Log {
scaling_factor: 4.0
}
);
assert_eq!(
rank_feature_fn(json!({
"rank_feature": { "field": "pr", "sigmoid": { "pivot": 7, "exponent": 0.6 } }
})),
crate::ast::RankFeatureFn::Sigmoid {
pivot: 7.0,
exponent: 0.6
}
);
assert_eq!(
rank_feature_fn(json!({ "rank_feature": { "field": "pr", "linear": {} } })),
crate::ast::RankFeatureFn::Linear
);
}
#[test]
fn test_rank_feature_log_missing_scaling_is_400() {
assert!(parse_query(&json!({
"rank_feature": { "field": "pr", "log": {} }
}))
.is_err());
}
#[test]
fn fields_accept_scalar_array_and_object_forms() {
for (body, expected) in [
(json!({"fields": "_passage"}), vec!["_passage"]),
(
json!({"fields": ["company", "_passage"]}),
vec!["company", "_passage"],
),
(
json!({"fields": [{"field": "_passage", "format": "ignored"}]}),
vec!["_passage"],
),
] {
assert_eq!(parse_request(&body).unwrap().fields, expected);
}
}
// ── Security regression tests ───────────────────────────────────────────
/// F1: deeply nested parens in `query_string` must not overflow the stack.
/// Pre-fix, ~100 k nested `(` caused a SIGSEGV process abort. The depth
/// guard in `parse_qs_unary`'s `LParen` arm caps nesting to
/// `MAX_QUERY_DEPTH` (64) and falls back to the opaque `QueryString` path.
#[test]
fn test_query_string_deep_paren_nesting_does_not_overflow() {
// 5000 nested parens is well above the 64-depth cap but well below
// the stack-overflow threshold (~100 k). Pre-fix this would have
// recursed 5000 deep; post-fix the depth guard trips at 64 and the
// parser falls back to QueryString without crashing.
let deep = "(".repeat(5000) + "a" + &")".repeat(5000);
let node = q(json!({"query_string": {"query": &deep}}));
// The fallback is opaque QueryString (the depth guard returns None
// from parse_qs_unary, try_lower_query_string returns Ok(None), and
// parse_query_string wraps the raw query in QueryNode::QueryString).
// It must NOT panic / abort.
match &node {
QueryNode::QueryString { query, .. } => assert_eq!(query, &deep),
other => panic!("expected QueryString fallback, got {other:?}"),
}
}
/// F1: a `query_string.query` longer than 64 KiB is rejected with a parse
/// error (defense-in-depth before tokenizing).
#[test]
fn test_query_string_over_length_cap_rejected() {
let too_long = "a ".repeat(40_000); // 80_000 chars > 65_536
let res = parse_query(&json!({
"query_string": { "query": too_long }
}));
assert!(res.is_err(), "oversized query_string should be rejected");
}
/// F1: a legitimate moderately-nested query still lowers into a Bool tree.
/// Ensures the depth guard doesn't trip on reasonable nesting (10 levels).
#[test]
fn test_query_string_moderate_paren_nesting_still_parses() {
let mut qs = String::new();
for _ in 0..10 {
qs.push_str("(title:foo OR ");
}
qs.push_str("title:bar");
for _ in 0..10 {
qs.push(')');
}
let node = q(json!({"query_string": {"query": &qs}}));
// 10 levels of nesting is well within the 64-depth cap, so it should
// lower into a Bool tree (not fall back to opaque QueryString).
assert!(
matches!(node, QueryNode::Bool { .. }),
"moderate nesting should parse to Bool, got {node:?}"
);
}
/// F6: `more_like_this` with an oversized `fields × like` cross-product
/// is rejected with a parse error instead of pre-allocating a huge Vec.
/// Pre-fix, 10 000 × 10 000 would try to allocate ~10 GiB and abort.
#[test]
fn test_more_like_this_cross_product_capped() {
let fields: Vec<String> = (0..200).map(|i| format!("f{i}")).collect();
let like: Vec<String> = (0..200).map(|i| format!("text{i}")).collect();
let res = parse_query(&json!({
"more_like_this": { "fields": fields, "like": like }
}));
assert!(
res.is_err(),
"200×200=40000 cross-product exceeds 4096 cap and must be rejected"
);
}
/// F6: `more_like_this` with too many fields is rejected.
#[test]
fn test_more_like_this_fields_cap() {
let fields: Vec<String> = (0..65).map(|i| format!("f{i}")).collect();
let res = parse_query(&json!({
"more_like_this": { "fields": fields, "like": ["text"] }
}));
assert!(res.is_err(), "65 fields exceeds the 64-field cap");
}
/// F6: `more_like_this` within the caps still parses successfully.
#[test]
fn test_more_like_this_within_caps_parses() {
let fields = vec!["title".to_string(), "body".to_string()];
let like = vec!["interesting text".to_string(), "more text".to_string()];
// 2 fields × 2 like = 4 cross-product, well within 4096.
let res = parse_query(&json!({
"more_like_this": { "fields": fields, "like": like }
}));
assert!(res.is_ok(), "2×2 cross-product should parse fine");
}
// ── bool clause count (issue #122) ────────────────────────────────────
fn bool_with_clauses(n: usize) -> serde_json::Value {
let clauses: Vec<serde_json::Value> = (0..n)
.map(|i| json!({ "term": { format!("f{i}"): format!("v{i}") } }))
.collect();
json!({ "bool": { "should": clauses } })
}
/// `MAX_QUERY_DEPTH` bounds how deep a query nests; nothing bounded how
/// wide it is. Width is what multiplies per-document work: with no
/// compiled-script cache in the engine, N script clauses over D documents
/// is N x D full script parses, and the clause count is the only place
/// that product can be bounded before any of it happens.
#[test]
fn a_bool_query_may_not_carry_unbounded_clauses() {
let err = parse_query(&bool_with_clauses(MAX_CLAUSE_COUNT + 1))
.expect_err("an over-wide bool must be refused");
assert!(
err.to_string().contains("too_many_clauses"),
"the error must be ES's own, got {err}"
);
}
/// Exactly at the cap still parses — the limit is a cap, not an off-by-one
/// haircut on legitimate queries.
#[test]
fn a_bool_query_at_the_clause_cap_still_parses() {
parse_query(&bool_with_clauses(MAX_CLAUSE_COUNT))
.expect("a query at exactly the cap must parse");
}
/// The width is the whole query's, not one `bool`'s: two sibling bools of
/// 600 clauses each are 1,200 clauses of work however they are spelled.
#[test]
fn the_clause_cap_is_summed_across_sibling_bools() {
let query = json!({
"bool": {
"must": [ bool_with_clauses(600), bool_with_clauses(600) ]
}
});
let err = parse_query(&query).expect_err("1,200 clauses must be refused");
assert!(err.to_string().contains("too_many_clauses"), "got {err}");
}
/// The counter is a thread-local, so a rejected query must not poison the
/// next request that happens to land on the same worker.
#[test]
fn a_rejected_query_does_not_poison_the_next_one() {
let _ = parse_query(&bool_with_clauses(MAX_CLAUSE_COUNT + 1));
parse_query(&bool_with_clauses(8))
.expect("an ordinary query after a rejected one must still parse");
}
/// Span clause lists, `dis_max.queries` and an array `knn.filter` are all
/// clause lists under other names, and all count towards the same width.
/// The cap is exercised through each of them — together with the refusal
/// semantics that go with it — in `tests/span_clause_refusal.rs`, which
/// survives a revert of this file and so can show what the fix is worth.
#[test]
fn the_cap_is_reachable_through_every_clause_list_shape() {
let wide: Vec<serde_json::Value> = (0..MAX_CLAUSE_COUNT + 1)
.map(|i| json!({ "term": { "f": format!("v{i}") } }))
.collect();
for query in [
json!({ "span_or": { "clauses": wide } }),
json!({ "dis_max": { "queries": wide } }),
json!({ "knn": {
"field": "vec", "query_vector": [0.1, 0.2], "k": 3, "filter": wide
}}),
] {
let err = parse_query(&query).expect_err("an over-wide clause list must be refused");
assert!(err.to_string().contains("too_many_clauses"), "got {err}");
}
}
/// Regression for the crash the `query_string` fuzz target found (#207).
///
/// The tokeniser walks bytes and slices `&q[start..i]` as a `&str`, and it
/// used to break on `is_whitespace()` — which is true for Latin-1 NBSP
/// (0xA0). In valid UTF-8 that byte is only ever a *continuation* byte, so
/// `_٠` (U+0660, encoded D9 A0) stopped the scan between the two bytes and
/// the slice panicked on a character boundary. `query_string` is reachable
/// unauthenticated from a request body and from `?q=`, and the release
/// profile sets `panic = "abort"` — so this was the process, not a 400.
///
/// Before the fix these abort the test process rather than failing.
#[test]
fn a_non_ascii_query_string_is_parsed_or_refused_but_never_panics() {
// The character libFuzzer landed on, plus other multi-byte widths and
// the two bytes `is_whitespace()` used to accept (0x85, 0xA0).
for query in [
"?:\"i(`:\"||+(l0O)_\u{660}\u{556}_ti(?:\"kk:))",
"_\u{660}",
"\u{660}",
"a\u{660}b c",
"field:\u{660}",
"field:>\u{660}",
"field:[\u{660} TO \u{661}]",
"\u{4e2d}\u{6587} AND \u{e9}t\u{e9}",
"caf\u{e9}\u{85}bar",
"caf\u{e9}\u{a0}bar",
"\u{1f600}",
] {
for body in [
json!({ "query_string": { "query": query, "default_field": "body" } }),
json!({ "query_string": { "query": query } }),
json!({ "simple_query_string": { "query": query } }),
] {
// Parsing may fail. It may not take the process with it.
let _ = parse_query(&body);
}
}
// ASCII query strings still parse to the same shapes.
let node = q(json!({
"query_string": { "query": "title:quick AND body:fox", "default_field": "body" }
}));
assert!(
matches!(node, QueryNode::Bool { .. }),
"an ordinary fielded query_string must still lower to a bool: {node:?}"
);
}
// ── Capability manifest (issue #211) ─────────────────────────────────────
/// Names in `parse_query`'s dispatch table, read out of this file's own
/// source at compile time.
///
/// A pattern line is one whose text before `=>` is nothing but quoted
/// string literals, `|` and whitespace — which is true of every match arm
/// head and of no arm body, so no marker comments are needed and nothing
/// has to be kept in sync by hand. The scan is bounded by the `match` head
/// and the catch-all arm that closes it.
fn dispatch_table_names() -> Vec<String> {
const SRC: &str = include_str!("parser.rs");
const START: &str = "match query_type.as_str() {";
const END: &str = "unknown => unknown_type(unknown),";
let start = SRC.find(START).expect("parse_query dispatch head moved") + START.len();
let end = SRC[start..]
.find(END)
.expect("parse_query catch-all arm moved")
+ start;
let mut names = Vec::new();
for line in SRC[start..end].lines() {
let code = line.split("//").next().unwrap_or("");
let head = code.split("=>").next().unwrap_or("");
if !head.contains('"') {
continue;
}
// Everything that is not a string literal must be `|`/whitespace,
// otherwise this is an arm body that merely mentions a literal.
let mut literals = Vec::new();
let mut rest = String::new();
let mut in_str = false;
let mut current = String::new();
for ch in head.chars() {
match (ch, in_str) {
('"', false) => in_str = true,
('"', true) => {
in_str = false;
literals.push(std::mem::take(&mut current));
}
(c, true) => current.push(c),
(c, false) => rest.push(c),
}
}
if in_str || rest.chars().any(|c| c != '|' && !c.is_whitespace()) {
continue;
}
names.extend(literals);
}
names
}
/// The drift guard. `SUPPORTED_QUERY_TYPES` + `REJECTED_QUERY_TYPES` must
/// be exactly the dispatch table — no more, no less.
///
/// Without this, adding a `parse_query` arm leaves every published list
/// silently short (the pipeline-aggregation half of issue #211) and
/// deleting one leaves them advertising a query that 400s.
#[test]
fn dispatch_table_matches_capability_manifest() {
use std::collections::BTreeSet;
let dispatched: BTreeSet<String> = dispatch_table_names().into_iter().collect();
assert!(
dispatched.len() > 40,
"scraper found only {} arms — the dispatch table shape changed and the \
scan is silently under-reading it",
dispatched.len()
);
let supported: BTreeSet<String> = SUPPORTED_QUERY_TYPES
.iter()
.map(|s| s.to_string())
.collect();
let rejected: BTreeSet<String> =
REJECTED_QUERY_TYPES.iter().map(|s| s.to_string()).collect();
assert_eq!(
supported.len(),
SUPPORTED_QUERY_TYPES.len(),
"SUPPORTED_QUERY_TYPES contains duplicates"
);
assert!(
supported.is_disjoint(&rejected),
"a query type cannot be both supported and rejected: {:?}",
supported.intersection(&rejected).collect::<Vec<_>>()
);
let manifest: BTreeSet<String> = supported.union(&rejected).cloned().collect();
let missing: Vec<_> = dispatched.difference(&manifest).collect();
let extra: Vec<_> = manifest.difference(&dispatched).collect();
assert!(
missing.is_empty() && extra.is_empty(),
"capability manifest has drifted from parse_query's dispatch table.\n \
dispatched but not in the manifest: {missing:?}\n \
in the manifest but not dispatched: {extra:?}\n \
Fix SUPPORTED_QUERY_TYPES / REJECTED_QUERY_TYPES in this file; the \
docs are checked against them by xerj-engine/tests/docs_capability_lists.rs."
);
}
/// Behavioural half: the manifest's two halves must actually behave the
/// way they are labelled — in **both** directions. A supported type must
/// neither answer `unknown query type` nor refuse with a `not supported`
/// message, and a rejected type must refuse with exactly that message.
/// Checking only the first of those let a recognised-and-refused type be
/// relabelled supported with the whole manifest suite green.
#[test]
fn manifest_labels_match_observed_behaviour() {
// `{ "<type>": {} }` — the minimal body that reaches the dispatch arm.
// Most arms then reject it for missing parameters; what matters here is
// only whether the *type* was recognised.
fn bare(name: &str) -> Value {
let mut obj = serde_json::Map::new();
obj.insert(name.to_string(), json!({}));
Value::Object(obj)
}
for name in SUPPORTED_QUERY_TYPES {
let err = parse_query(&bare(name)).err();
if let Some(QueryError::Parse(ParseError::UnknownQueryType(t))) = &err {
panic!(
"`{name}` is listed as supported but parse_query rejects it as unknown: {t}"
);
}
// The unknown-query-type check alone does not prove the *supported*
// label: a type that is recognised and then refused with a 400 —
// exactly what `has_child` does — never produces
// `UnknownQueryType`, so moving it into SUPPORTED_QUERY_TYPES used
// to pass here and then oblige the docs guard to publish it as a
// capability. That is the #211 defect in the direction this test
// exists to catch, so the refusal wording is checked too: the
// phrase REJECTED_QUERY_TYPES is required to carry is the phrase
// SUPPORTED_QUERY_TYPES is forbidden to carry.
if let Some(e) = &err {
let msg = e.to_string();
assert!(
!msg.contains("not supported"),
"`{name}` is listed as supported but refuses with a not-supported \
message: {msg}\n A recognised-and-refused type belongs in \
REJECTED_QUERY_TYPES, or the docs will advertise a query that 400s."
);
}
}
for name in REJECTED_QUERY_TYPES {
let err = parse_query(&bare(name))
.err()
.unwrap_or_else(|| panic!("`{name}` is listed as rejected but parsed cleanly"));
assert!(
err.to_string().contains("not supported"),
"`{name}` must refuse with an explanatory message, got: {err}"
);
}
}
// ── #1751: simple_query_string standalone and infix operators ──────────────
#[test]
fn simple_query_string_honors_operators_grouping_and_phrases() {
// `fox | bear` under `default_operator: and` must be OR (should clauses).
let node = q(json!({
"simple_query_string": {
"query": "fox | bear",
"fields": ["title"],
"default_operator": "and"
}
}));
match node {
QueryNode::Bool {
should,
must,
minimum_should_match,
..
} => {
assert!(
must.is_empty(),
"must be empty under OR conjunction: {must:?}"
);
assert_eq!(should.len(), 2);
assert_eq!(minimum_should_match, Some(MinShouldMatch::Fixed(1)));
}
other => panic!("expected Bool, got {other:?}"),
}
// `fox + lazy` under default operator must be AND (must clauses).
let node = q(json!({
"simple_query_string": {
"query": "fox + lazy",
"fields": ["title"]
}
}));
match node {
QueryNode::Bool { must, should, .. } => {
assert_eq!(must.len(), 2, "both terms must be required: {must:?}");
assert!(should.is_empty());
}
other => panic!("expected Bool, got {other:?}"),
}
// `"quick brown" | bear` under `default_operator: and` must produce MatchPhrase and Match in should.
let node = q(json!({
"simple_query_string": {
"query": "\"quick brown\" | bear",
"fields": ["title"],
"default_operator": "and"
}
}));
match node {
QueryNode::Bool { should, must, .. } => {
assert!(must.is_empty());
assert_eq!(should.len(), 2);
assert!(
matches!(&should[0], QueryNode::MatchPhrase { ref query, .. } if query == "quick brown")
);
assert!(
matches!(&should[1], QueryNode::Match { ref query, .. } if query == "bear")
);
}
other => panic!("expected Bool, got {other:?}"),
}
// `(fox | bear) + brown` under `default_operator: and` must group (fox | bear) and require brown.
let node = q(json!({
"simple_query_string": {
"query": "(fox | bear) + brown",
"fields": ["title"],
"default_operator": "and"
}
}));
match node {
QueryNode::Bool { must, .. } => {
assert_eq!(must.len(), 2);
assert!(
matches!(&must[0], QueryNode::Bool { ref should, .. } if should.len() == 2)
);
assert!(matches!(&must[1], QueryNode::Match { ref query, .. } if query == "brown"));
}
other => panic!("expected Bool, got {other:?}"),
}
// Negation with `-`
let node = q(json!({
"simple_query_string": {
"query": "+fox -dog",
"fields": ["title"]
}
}));
match node {
QueryNode::Bool { must, must_not, .. } => {
assert_eq!(must.len(), 1);
assert_eq!(must_not.len(), 1);
}
other => panic!("expected Bool, got {other:?}"),
}
// Resilient to trailing/standalone operators and unclosed quotes/parens
let _ = q(json!({ "simple_query_string": { "query": "fox |" } }));
let _ = q(json!({ "simple_query_string": { "query": "(fox | bear" } }));
let _ = q(json!({ "simple_query_string": { "query": "\"unclosed phrase" } }));
let _ = q(json!({ "simple_query_string": { "query": "++ -- ||" } }));
}
}