use crate::filter::top_level_filter;
use crate::prefetch::{build_query_with_prefetch, default_model_for_using, extract_lookup_from};
use crate::semantic::PlanQueryInput;
use crate::types::*;
use qql_core::ast::{FusionMethod, OrderDirection, QueryExpr, QueryInput, QueryStmt, VectorValue};
use qql_core::error::QqlError;
pub use crate::params::{lower_request_opts, lower_search_params, push_read_opts};
pub use crate::prefetch::{lower_prefetch, lower_prefetch_with_ctes};
pub fn lower_vector_value(value: &VectorValue) -> PlanVectorValue {
PlanVectorValue::from(value)
}
pub fn lower_query_input(input: &QueryInput) -> PlanQueryInput {
PlanQueryInput::from(input)
}
pub fn lower_query_expr(expr: &QueryExpr) -> Result<QueryVariant, QqlError> {
Ok(match expr {
QueryExpr::Nearest {
input, using, mmr, ..
} => {
let mut nearest = lower_query_input(input);
if let PlanQueryInput::Document { model, .. } = &mut nearest
&& model.as_deref().unwrap_or("").is_empty()
{
*model = default_model_for_using(using.as_ref().map(|t| t.name.as_str()))
.or_else(|| model.clone());
}
QueryVariant::Nearest(NearestQuery {
nearest,
mmr: mmr.as_ref().map(|m| MmrQueryParams {
diversity: m.diversity,
candidates_limit: m.candidates,
}),
})
}
QueryExpr::Recommend {
positive,
negative,
strategy,
..
} => {
let pos: Vec<_> = positive.iter().map(lower_query_input).collect();
let neg: Vec<_> = negative.iter().map(lower_query_input).collect();
let s = strategy.map(|s| match s {
qql_core::ast::RecommendStrategy::AverageVector => "average_vector".into(),
qql_core::ast::RecommendStrategy::BestScore => "best_score".into(),
qql_core::ast::RecommendStrategy::SumScores => "sum_scores".into(),
});
QueryVariant::Recommend {
recommend: RecommendQuery {
positive: pos,
negative: neg,
strategy: s,
},
}
}
QueryExpr::Context { pairs, .. } => {
let ctx: Vec<_> = pairs
.iter()
.map(|pair| ContextPair {
positive: lower_query_input(&pair.positive),
negative: lower_query_input(&pair.negative),
})
.collect();
QueryVariant::Context { context: ctx }
}
QueryExpr::Discover {
target, context, ..
} => {
let ctx: Vec<_> = context
.iter()
.map(|pair| ContextPair {
positive: lower_query_input(&pair.positive),
negative: lower_query_input(&pair.negative),
})
.collect();
QueryVariant::Discover {
discover: DiscoverQuery {
target: lower_query_input(target),
context: ctx,
},
}
}
QueryExpr::OrderBy {
field,
direction,
start_from,
} => {
let dir = match direction {
OrderDirection::Asc => Some("asc".into()),
OrderDirection::Desc => Some("desc".into()),
};
QueryVariant::OrderBy {
order_by: OrderByQuery {
key: field.clone(),
direction: dir,
start_from: start_from.clone(),
},
}
}
QueryExpr::SampleRandom => QueryVariant::Sample {
sample: "random".into(),
},
QueryExpr::Fusion { method, .. } => {
let m = match method {
FusionMethod::Rrf => "rrf",
FusionMethod::Dbsf => "dbsf",
};
QueryVariant::Fusion { fusion: m.into() }
}
QueryExpr::Formula {
expression,
defaults,
..
} => {
let defaults = if defaults.is_empty() {
None
} else {
Some(
defaults
.iter()
.map(|(key, value)| (key.clone(), FormulaDefault::from(value)))
.collect(),
)
};
QueryVariant::Formula(FormulaQuery {
formula: PlanFormula::from_expr(expression.as_ref())?,
defaults,
})
}
QueryExpr::RelevanceFeedback {
target,
feedback,
strategy,
..
} => {
let feedback_items: Vec<_> = feedback
.iter()
.map(|item| FeedbackItem {
example: lower_query_input(&item.example),
score: item.score,
})
.collect();
QueryVariant::RelevanceFeedback {
relevance_feedback: RelevanceFeedbackInput {
target: lower_query_input(target),
feedback: feedback_items,
strategy: FeedbackStrategy {
naive: NaiveFeedbackStrategyParams {
a: strategy.a,
b: strategy.b,
c: strategy.c,
},
},
},
}
}
QueryExpr::Hybrid { .. } => QueryVariant::Fusion {
fusion: "rrf".into(),
},
QueryExpr::Rerank { input, .. } => QueryVariant::Nearest(NearestQuery {
nearest: lower_query_input(input),
mmr: None,
}),
QueryExpr::CrossRerank { .. } | QueryExpr::Points { .. } => {
return Err(QqlError::validation(
"QQL-PLAN-UNSUPPORTED-PREFETCH",
"POINTS / CROSS RERANK are not supported inside PREFETCH",
None,
));
}
})
}
pub fn lower_output_selector_public(
output: &qql_core::ast::QueryOutput,
) -> (Option<PayloadSelectorReq>, Option<VectorSelectorReq>) {
lower_output_selector(output)
}
fn lower_output_selector(
output: &qql_core::ast::QueryOutput,
) -> (Option<PayloadSelectorReq>, Option<VectorSelectorReq>) {
let with_payload = match &output.payload {
Some(qql_core::ast::PayloadSelector::All) => Some(PayloadSelectorReq::All(true)),
Some(qql_core::ast::PayloadSelector::None) => Some(PayloadSelectorReq::All(false)),
Some(qql_core::ast::PayloadSelector::Include(fields)) => {
Some(PayloadSelectorReq::Include {
include: fields.clone(),
})
}
Some(qql_core::ast::PayloadSelector::Exclude(fields)) => {
Some(PayloadSelectorReq::Exclude {
exclude: fields.clone(),
})
}
None => Some(PayloadSelectorReq::All(true)),
};
let with_vector = output.vectors.as_ref().map(|v| match v {
qql_core::ast::VectorSelector::All => VectorSelectorReq::All(true),
qql_core::ast::VectorSelector::None => VectorSelectorReq::All(false),
qql_core::ast::VectorSelector::Names(names) => VectorSelectorReq::Names(names.clone()),
});
(with_payload, with_vector)
}
fn lower_group_lookup(lookup: &qql_core::ast::GroupLookup) -> WithLookupValue {
if lookup.payload.is_none() && lookup.vectors.is_none() {
return WithLookupValue::Collection(lookup.collection.clone());
}
WithLookupValue::Full(WithLookup {
collection: lookup.collection.clone(),
with_payload: lookup.payload.as_ref().map(|selector| match selector {
qql_core::ast::PayloadSelector::All => PayloadSelectorReq::All(true),
qql_core::ast::PayloadSelector::None => PayloadSelectorReq::All(false),
qql_core::ast::PayloadSelector::Include(fields) => PayloadSelectorReq::Include {
include: fields.clone(),
},
qql_core::ast::PayloadSelector::Exclude(fields) => PayloadSelectorReq::Exclude {
exclude: fields.clone(),
},
}),
with_vectors: lookup.vectors.as_ref().map(|selector| match selector {
qql_core::ast::VectorSelector::All => VectorSelectorReq::All(true),
qql_core::ast::VectorSelector::None => VectorSelectorReq::All(false),
qql_core::ast::VectorSelector::Names(names) => VectorSelectorReq::Names(names.clone()),
}),
})
}
pub fn lower_query_request(query: &QueryStmt) -> Result<QueryRequest, QqlError> {
let (with_payload, with_vector) = lower_output_selector(&query.output);
let (query_variant, using, prefetch) = build_query_with_prefetch(query)?;
let (timeout, consistency) = lower_request_opts(query.params.as_ref());
Ok(QueryRequest {
query: query_variant,
using,
prefetch,
filter: query
.filter
.as_ref()
.map(|f| top_level_filter(f))
.transpose()?,
params: match query.params.as_ref() {
Some(p) => lower_search_params(p)?,
None => None,
},
score_threshold: query.score_threshold,
with_payload,
with_vector,
limit: query.page.limit,
offset: query.page.offset,
lookup_from: extract_lookup_from(query),
shard_key: query
.shard_key
.as_ref()
.map(crate::semantic::PlanShardKey::from),
timeout,
consistency,
})
}
pub fn lower_query_groups_request(query: &QueryStmt) -> Result<QueryGroupsRequest, QqlError> {
let Some(group) = query.group.as_ref() else {
return Err(QqlError::validation(
"QQL-PLAN-GROUP",
"group required for groups query",
None,
));
};
if group.field.is_empty() {
return Err(QqlError::validation(
"QQL-PLAN-GROUP",
"group field must not be empty",
group.field_span,
));
};
let offset = query.page.offset.unwrap_or(0);
let user_limit = query.page.limit.unwrap_or(10);
let effective_limit = user_limit.checked_add(offset).ok_or_else(|| {
QqlError::validation(
"QQL-VALIDATION-LIMIT-OVERFLOW",
format!(
"grouped query LIMIT {user_limit} + OFFSET {offset} overflows u64; \
reduce LIMIT or OFFSET"
),
None,
)
})?;
let group_offset = if offset > 0 { Some(offset) } else { None };
let (with_payload, with_vector) = lower_output_selector(&query.output);
let (query_variant, using, prefetch) = build_query_with_prefetch(query)?;
let (timeout, consistency) = lower_request_opts(query.params.as_ref());
Ok(QueryGroupsRequest {
query: query_variant,
using,
prefetch,
filter: query
.filter
.as_ref()
.map(|f| top_level_filter(f))
.transpose()?,
params: match query.params.as_ref() {
Some(p) => lower_search_params(p)?,
None => None,
},
score_threshold: query.score_threshold,
with_payload,
with_vector,
group_by: group.field.clone(),
group_size: group.size.unwrap_or(3),
limit: effective_limit,
with_lookup: group.lookup.as_ref().map(lower_group_lookup),
lookup_from: extract_lookup_from(query),
shard_key: query
.shard_key
.as_ref()
.map(crate::semantic::PlanShardKey::from),
timeout,
consistency,
group_offset,
})
}
#[cfg(test)]
mod tests {
use qql_core::parser::Parser;
fn parse_route(source: &str) -> serde_json::Value {
let s = Parser::parse(source).unwrap();
let r = crate::routing::try_route(&s).unwrap();
r.body_json().unwrap()
}
#[test]
fn acorn_true_serializes_enable() {
let json =
parse_route("QUERY TEXT 'hello' MODEL 'e5' FROM docs PARAMS (acorn = true) LIMIT 5;");
assert_eq!(json["params"]["acorn"]["enable"], true);
}
#[test]
fn acorn_false_serializes_enable_false() {
let json =
parse_route("QUERY TEXT 'hello' MODEL 'e5' FROM docs PARAMS (acorn = false) LIMIT 5;");
assert_eq!(json["params"]["acorn"]["enable"], false);
}
#[test]
fn acorn_max_selectivity_serializes() {
let json = parse_route(
"QUERY TEXT 'hello' MODEL 'e5' FROM docs PARAMS (acorn = true, max_selectivity = 0.4) LIMIT 5;",
);
assert_eq!(json["params"]["acorn"]["enable"], true);
assert_eq!(json["params"]["acorn"]["max_selectivity"], 0.4);
}
#[test]
fn idf_serializes_global_and_corpus() {
let global =
parse_route("QUERY TEXT 'hello' MODEL 'e5' FROM docs PARAMS (idf = 'global') LIMIT 5;");
assert_eq!(global["params"]["idf"], "global");
let corpus = parse_route(
"QUERY TEXT 'hello' MODEL 'e5' FROM docs PARAMS (idf = WHERE status = 'active') LIMIT 5;",
);
let idf = &corpus["params"]["idf"];
assert_eq!(idf["corpus"]["must"][0]["key"], "status");
assert_eq!(idf["corpus"]["must"][0]["match"]["value"], "active");
let tenant = parse_route(
"QUERY TEXT 'hello' MODEL 'e5' FROM docs WHERE tenant_id = 'acme' SHARD 'acme' PARAMS (idf = WHERE tenant_id = 'acme') LIMIT 5;",
);
assert_eq!(
tenant["params"]["idf"]["corpus"]["must"][0]["key"],
"tenant_id"
);
assert_eq!(
tenant["params"]["idf"]["corpus"]["must"][0]["match"]["value"],
"acme"
);
}
#[test]
fn idf_json_corpus_is_rejected_at_parse() {
let err = Parser::parse(
"QUERY TEXT 'hello' MODEL 'e5' FROM docs PARAMS (idf = {corpus: {not_a_filter: true}}) LIMIT 5;",
)
.unwrap_err();
assert_eq!(err.code, "QQL-VALIDATION-IDF");
}
#[test]
fn timeout_and_consistency_are_rest_query_params_not_body() {
let route = crate::plan::try_route(
&Parser::parse(
"QUERY TEXT 'hello' MODEL 'e5' FROM docs PARAMS (timeout = 30, consistency = majority) LIMIT 5;",
)
.unwrap(),
)
.unwrap();
assert!(
route.query.iter().any(|(k, v)| k == "timeout" && v == "30"),
"timeout query param missing: {:?}",
route.query
);
assert!(
route
.query
.iter()
.any(|(k, v)| k == "consistency" && v == "majority"),
"consistency query param missing: {:?}",
route.query
);
let body = route.body_json().expect("body");
assert!(body.get("timeout").is_none(), "timeout must not be body");
assert!(
body.get("consistency").is_none(),
"consistency must not be body"
);
assert!(body.get("params").is_none() || body["params"].as_object().unwrap().is_empty());
}
#[test]
fn consistency_factor_serializes_as_integer_query_param() {
let route = crate::plan::try_route(
&Parser::parse(
"QUERY TEXT 'hello' MODEL 'e5' FROM docs PARAMS (consistency = 2) LIMIT 5;",
)
.unwrap(),
)
.unwrap();
assert!(
route
.query
.iter()
.any(|(k, v)| k == "consistency" && v == "2")
);
}
#[test]
fn group_by_with_offset_is_supported() {
let op = crate::plan::plan(
&Parser::parse("QUERY TEXT 'x' MODEL 'e5' FROM docs GROUP BY topic LIMIT 10 OFFSET 5;")
.unwrap(),
)
.unwrap();
if let crate::plan::PlannedOperation::QueryGroups { request, .. } = op {
assert_eq!(request.limit, 15);
assert_eq!(request.group_offset, Some(5));
} else {
panic!("expected QueryGroups operation");
}
}
#[test]
fn mmr_with_sparse_using_is_supported() {
let op = crate::plan::plan(
&Parser::parse(
"QUERY MMR TEXT 'q' MODEL 'e5' DIVERSITY 0.5 CANDIDATES 20 FROM docs USING sparse AS SPARSE LIMIT 5;",
)
.unwrap(),
);
assert!(op.is_ok());
}
#[test]
fn prefetch_preserves_filter_limit_and_params() {
let json = parse_route(
"WITH a AS (QUERY TEXT 'x' MODEL 'e5' FROM docs USING dense WHERE status = 'active' PARAMS (hnsw_ef = 64) SCORE THRESHOLD 0.5 LIMIT 50) \
QUERY FUSION RRF FROM docs PREFETCH (a) LIMIT 10;",
);
let pf = &json["prefetch"][0];
assert!(
pf["filter"].is_object(),
"CTE filter must be preserved: {}",
pf
);
assert_eq!(pf["limit"], 50);
assert_eq!(pf["params"]["hnsw_ef"], 64);
assert_eq!(pf["score_threshold"], 0.5);
}
#[test]
fn prefetch_cte_name_is_case_insensitive() {
let json = parse_route(
"WITH DenseHits AS (QUERY TEXT 'x' MODEL 'e5' FROM docs USING dense LIMIT 20) \
QUERY FUSION RRF FROM docs PREFETCH (densehits) LIMIT 5;",
);
let pf = &json["prefetch"][0];
assert!(
pf["query"].is_object(),
"case-insensitive CTE lookup must resolve query: {}",
pf
);
assert_eq!(pf["limit"], 20);
}
#[test]
fn formula_div_preserves_by_zero_default() {
let json = parse_route("QUERY FORMULA score * 2 DEFAULTS (score = 0.0) FROM docs LIMIT 5;");
assert!(
json["query"]["formula"].is_object()
|| json["query"]["formula"].is_number()
|| json["query"]["formula"].is_string()
);
assert_ne!(json["query"]["formula"], serde_json::Value::Null);
}
#[test]
fn formula_match_condition_lowers_to_value_when_single() {
let json = parse_route("QUERY FORMULA MATCH(is_superhost, true) FROM docs LIMIT 5;");
let formula = &json["query"]["formula"];
assert_eq!(formula["key"], "is_superhost");
assert_eq!(formula["match"]["value"], true);
}
#[test]
fn hybrid_expands_to_prefetches() {
let json = parse_route(
"QUERY HYBRID TEXT 'ai search' MODEL 'bge' DENSE dense SPARSE sparse FUSION RRF FROM docs LIMIT 10;",
);
assert_eq!(json["query"]["fusion"], "rrf");
assert!(json["query"].get("nearest").is_none());
let pf = json["prefetch"].as_array().unwrap();
assert_eq!(pf.len(), 2);
}
#[test]
fn using_hybrid_expands_like_front_form() {
let front = parse_route(
"QUERY HYBRID TEXT 'ai search' MODEL 'bge' DENSE dense SPARSE sparse FUSION RRF FROM docs LIMIT 10;",
);
let tail = parse_route(
"QUERY TEXT 'ai search' MODEL 'bge' FROM docs USING HYBRID DENSE dense SPARSE sparse FUSION RRF LIMIT 10;",
);
assert_eq!(front, tail);
assert_eq!(tail["query"]["fusion"], "rrf");
assert_eq!(tail["prefetch"].as_array().unwrap().len(), 2);
assert_eq!(tail["prefetch"][0]["using"], "dense");
assert_eq!(tail["prefetch"][1]["using"], "sparse");
assert_eq!(tail["prefetch"][0]["limit"], 100);
assert_eq!(tail["prefetch"][1]["limit"], 100);
}
#[test]
fn using_hybrid_dbsf_and_defaults() {
let json = parse_route(
"QUERY TEXT 'q' MODEL 'bge' FROM docs USING HYBRID DENSE d SPARSE s FUSION DBSF LIMIT 5;",
);
assert_eq!(json["query"]["fusion"], "dbsf");
assert_eq!(json["prefetch"][0]["using"], "d");
assert_eq!(json["prefetch"][1]["using"], "s");
assert_eq!(json["prefetch"][0]["limit"], 50);
}
#[test]
fn nearest_text_without_model_plans_successfully() {
let result = crate::plan::plan(
&Parser::parse("QUERY TEXT 'hello' FROM docs USING dense LIMIT 5;").unwrap(),
);
assert!(
result.is_ok(),
"plan should succeed without MODEL: {}",
result.unwrap_err()
);
}
#[test]
fn nearest_text_with_model_is_object() {
let json =
parse_route("QUERY TEXT 'hello' MODEL 'embedder' FROM docs USING dense LIMIT 5;");
assert_eq!(json["query"]["nearest"]["text"], "hello");
assert_eq!(json["query"]["nearest"]["model"], "embedder");
}
#[test]
fn nearest_vector_is_array() {
let json = parse_route("QUERY NEAREST VECTOR [1.0, 2.0] FROM docs USING dense LIMIT 5;");
assert!(json["query"]["nearest"].is_array());
}
#[test]
fn nearest_with_mmr() {
let json = parse_route(
"QUERY MMR TEXT 'query' MODEL 'embedder' DIVERSITY 0.4 CANDIDATES 100 FROM docs USING dense LIMIT 5;",
);
assert_eq!(json["query"]["nearest"]["text"], "query");
assert_eq!(json["query"]["nearest"]["model"], "embedder");
assert_eq!(json["query"]["mmr"]["diversity"], 0.4);
assert_eq!(json["query"]["mmr"]["candidates_limit"], 100);
}
#[test]
fn recommend_serializes_correctly() {
let json = parse_route(
"QUERY RECOMMEND POSITIVE (1) NEGATIVE (2, 3) STRATEGY average_vector FROM docs USING dense LIMIT 10;",
);
assert_eq!(json["query"]["recommend"]["positive"][0], 1);
assert_eq!(
json["query"]["recommend"]["negative"]
.as_array()
.unwrap()
.len(),
2
);
assert_eq!(json["query"]["recommend"]["strategy"], "average_vector");
}
#[test]
fn formula_case_condition_lowers_to_object_not_null() {
let single = parse_route(
"QUERY FORMULA CASE WHEN status = 'active' THEN $score * 2 ELSE $score END FROM docs LIMIT 5;",
);
let formula = &single["query"]["formula"];
assert!(formula.is_object(), "formula must be an object: {formula}");
let cond = &formula["sum"][0]["mult"][0];
assert_ne!(cond, &serde_json::Value::Null);
assert_eq!(cond["key"], "status");
assert_eq!(cond["match"]["value"], "active");
assert_eq!(formula["sum"][1]["mult"][0]["sum"][1]["neg"], *cond);
let compound = parse_route(
"QUERY FORMULA CASE WHEN a = 1 AND b = 2 THEN $score ELSE 0 END FROM docs LIMIT 5;",
);
let formula = &compound["query"]["formula"];
let cond = &formula["sum"][0]["mult"][0];
assert_ne!(cond, &serde_json::Value::Null);
assert_eq!(cond["must"][0]["key"], "a");
assert_eq!(cond["must"][0]["match"]["value"], 1);
assert_eq!(cond["must"][1]["key"], "b");
}
#[test]
fn formula_with_defaults() {
let json = parse_route(
"QUERY FORMULA score * 2 DEFAULTS (score = 0.0, boost = 1.0) FROM docs LIMIT 5;",
);
assert!(json["query"]["formula"].is_object());
let defaults = json["query"]["defaults"].as_object().unwrap();
assert_eq!(defaults["score"], 0.0);
assert_eq!(defaults["boost"], 1.0);
}
#[test]
fn relevance_feedback_proper_shape() {
let json = parse_route(
"QUERY RELEVANCE FEEDBACK TARGET POINT 42 FEEDBACK ((POINT 43, 0.5), (POINT 44, -0.2)) STRATEGY NAIVE (a = 1.0, b = 0.5, c = 0.5) FROM docs USING dense LIMIT 10;",
);
let rf = &json["query"]["relevance_feedback"];
assert_eq!(rf["target"], 42);
assert_eq!(rf["feedback"].as_array().unwrap().len(), 2);
assert_eq!(rf["feedback"][0]["score"], 0.5);
assert_eq!(rf["strategy"]["naive"]["a"], 1.0);
}
#[test]
fn prefetch_serializes_lookup_from() {
let json = parse_route(
"QUERY NEAREST POINT 42 FROM docs USING dense PREFETCH (QUERY TEXT 'x' MODEL 'e5' FROM docs USING dense LIMIT 50) LIMIT 10;",
);
let pf = &json["prefetch"][0];
assert_eq!(pf["query"]["nearest"]["text"], "x");
assert_eq!(pf["query"]["nearest"]["model"], "e5");
}
#[test]
fn query_request_no_group_fields() {
let json = parse_route("QUERY TEXT 'hello' MODEL 'e5' FROM docs LIMIT 5;");
assert!(json.get("group_by").is_none());
assert!(json.get("group_size").is_none());
}
#[test]
fn grouped_request_has_group_fields() {
let json = parse_route(
"QUERY TEXT 'news' MODEL 'e5' FROM docs GROUP BY topic SIZE 5 LOOKUP FROM topics LIMIT 20;",
);
assert_eq!(json["group_by"], "topic");
assert_eq!(json["group_size"], 5);
assert_eq!(json["limit"], 20);
}
#[test]
fn order_by_query() {
let json = parse_route("QUERY ORDER BY created_at DESC FROM docs LIMIT 10;");
assert_eq!(json["query"]["order_by"]["key"], "created_at");
assert_eq!(json["query"]["order_by"]["direction"], "desc");
}
#[test]
fn sample_query() {
let json = parse_route("QUERY SAMPLE RANDOM FROM docs LIMIT 5;");
assert_eq!(json["query"]["sample"], "random");
}
#[test]
fn fusion_query() {
let json = parse_route(
"WITH a AS (QUERY TEXT 'x' MODEL 'e5' FROM docs USING dense LIMIT 100) QUERY FUSION RRF FROM docs PREFETCH (a) LIMIT 10;",
);
assert_eq!(json["query"]["fusion"], "rrf");
}
#[test]
fn discover_query() {
let json = parse_route(
"QUERY DISCOVER TARGET POINT 42 CONTEXT (POSITIVE POINT 1 NEGATIVE POINT 2) FROM docs USING dense LIMIT 10;",
);
assert_eq!(json["query"]["discover"]["target"], 42);
assert_eq!(
json["query"]["discover"]["context"]
.as_array()
.unwrap()
.len(),
1
);
}
#[test]
fn context_query() {
let json = parse_route(
"QUERY CONTEXT (POSITIVE POINT 1 NEGATIVE POINT 2, POSITIVE POINT 3 NEGATIVE POINT 4) FROM docs LIMIT 10;",
);
assert_eq!(json["query"]["context"].as_array().unwrap().len(), 2);
}
#[test]
fn rerank_has_prefetches_and_model() {
let json = parse_route(
"QUERY RERANK TEXT 'travel tips' MODEL 'colbert-v2' FROM docs USING colbert PREFETCH (QUERY TEXT 'travel tips' MODEL 'e5' FROM docs USING dense LIMIT 50) LIMIT 10;",
);
assert_eq!(json["using"], "colbert");
let nearest = &json["query"]["nearest"];
assert_eq!(nearest["text"], "travel tips");
assert_eq!(nearest["model"], "colbert-v2");
assert_eq!(json["prefetch"].as_array().unwrap().len(), 1);
}
#[test]
fn document_without_model_plans_successfully() {
let result = crate::plan::plan(
&Parser::parse("QUERY 'bare string' FROM docs USING dense LIMIT 5;").unwrap(),
);
assert!(
result.is_ok(),
"plan should succeed without MODEL: {}",
result.unwrap_err()
);
}
#[test]
fn hybrid_without_model_plans_successfully() {
let result = crate::plan::plan(
&Parser::parse(
"QUERY HYBRID TEXT 'search' DENSE d SPARSE s FUSION RRF FROM docs LIMIT 10;",
)
.unwrap(),
);
assert!(
result.is_ok(),
"plan should succeed without MODEL: {}",
result.unwrap_err()
);
}
#[test]
fn document_and_image_with_model_are_objects() {
let doc_json = parse_route("QUERY TEXT 'doc text' MODEL 'my-model' FROM docs LIMIT 5;");
let nearest = &doc_json["query"]["nearest"];
assert!(
nearest.is_object(),
"modelled Document must be object: {nearest}"
);
assert_eq!(nearest["text"], "doc text");
assert_eq!(nearest["model"], "my-model");
let img_json = parse_route(
"QUERY IMAGE 'https://img.example.com/cat.jpg' MODEL 'clip-vision' FROM docs USING img LIMIT 5;",
);
let img_nearest = &img_json["query"]["nearest"];
assert!(
img_nearest.is_object(),
"modelled Image must be object: {img_nearest}"
);
assert_eq!(img_nearest["image"], "https://img.example.com/cat.jpg");
assert_eq!(img_nearest["model"], "clip-vision");
}
#[test]
fn points_prefetch_source_errors_instead_of_panicking() {
let result = crate::plan::plan(
&Parser::parse(
"QUERY TEXT 'x' FROM docs USING dense PREFETCH (QUERY POINTS (1) FROM docs) LIMIT 10;",
)
.unwrap(),
);
let err = result.unwrap_err();
assert_eq!(err.kind, qql_core::error::ErrorKind::Validation);
assert_eq!(err.code, "QQL-PLAN-UNSUPPORTED-PREFETCH");
}
#[test]
fn points_cte_prefetch_source_errors_instead_of_panicking() {
let result = crate::plan::plan(
&Parser::parse(
"WITH a AS (QUERY POINTS (1) FROM docs) \
QUERY FUSION RRF FROM docs PREFETCH (a) LIMIT 10;",
)
.unwrap(),
);
let err = result.unwrap_err();
assert_eq!(err.kind, qql_core::error::ErrorKind::Validation);
assert_eq!(err.code, "QQL-PLAN-UNSUPPORTED-PREFETCH");
}
#[test]
fn cross_rerank_prefetch_source_errors_instead_of_panicking() {
let result = crate::plan::plan(
&Parser::parse(
"QUERY TEXT 'x' FROM docs USING dense \
PREFETCH (QUERY CROSS RERANK TEXT 'q' MODEL 'm' FROM docs \
PREFETCH (QUERY TEXT 'c' FROM docs LIMIT 5)) \
LIMIT 10;",
)
.unwrap(),
);
let err = result.unwrap_err();
assert_eq!(err.kind, qql_core::error::ErrorKind::Validation);
assert_eq!(err.code, "QQL-PLAN-UNSUPPORTED-PREFETCH");
}
#[test]
fn rerank_cte_prefetch_preserves_candidate_query() {
let json = parse_route(
"WITH a AS (QUERY TEXT 'x' MODEL 'e5' FROM docs USING dense LIMIT 20) \
QUERY RERANK TEXT 'q' MODEL 'colbert' FROM docs USING colbert PREFETCH (a) LIMIT 10;",
);
let pf = &json["prefetch"][0];
assert!(
pf["query"].is_object(),
"CTE-referencing RERANK prefetch must keep its candidate query: {pf}"
);
assert_eq!(pf["query"]["nearest"]["text"], "x");
assert_eq!(pf["limit"], 20);
assert_ne!(pf, &serde_json::json!({}));
}
#[test]
fn group_by_prefetch_source_is_rejected() {
let result = crate::plan::plan(
&Parser::parse(
"QUERY FUSION RRF FROM docs PREFETCH \
(QUERY TEXT 'y' FROM docs GROUP BY topic LIMIT 5) \
LIMIT 10;",
)
.unwrap(),
);
let err = result.unwrap_err();
assert_eq!(err.kind, qql_core::error::ErrorKind::Validation);
assert_eq!(err.code, "QQL-PLAN-PREFETCH-GROUP");
}
#[test]
fn prefetch_lowering_errors_are_propagated_not_swallowed() {
use qql_core::ast::*;
let stmt = Stmt::Query(Box::new(QueryStmt {
ctes: vec![],
collection: QueryCollection::Explicit("docs".into()),
collection_span: None,
expression: QueryExpr::Fusion {
method: FusionMethod::Rrf,
prefetch: vec![Prefetch {
source: PrefetchSource::Cte("missing".into()),
filter: None,
score_threshold: None,
lookup: None,
}],
},
filter: None,
params: None,
score_threshold: None,
group: None,
output: QueryOutput::default(),
page: PageSpec {
limit: Some(10),
offset: None,
..Default::default()
},
shard_key: None,
}));
let err = crate::plan::plan(&stmt).unwrap_err();
assert_eq!(err.kind, qql_core::error::ErrorKind::Validation);
assert_eq!(err.code, "QQL-PLAN-PREFETCH-CTE");
}
#[test]
fn grouped_query_limit_offset_overflow_is_a_validation_error() {
let result = crate::plan::plan(
&Parser::parse(
"QUERY TEXT 'x' FROM docs GROUP BY topic \
LIMIT 18446744073709551615 OFFSET 18446744073709551615;",
)
.unwrap(),
);
let err = result.unwrap_err();
assert_eq!(err.kind, qql_core::error::ErrorKind::Validation);
assert_eq!(err.code, "QQL-VALIDATION-LIMIT-OVERFLOW");
}
#[test]
fn parsed_statements_store_collection_and_group_spans() {
let stmt =
Parser::parse("QUERY TEXT 'x' MODEL 'e5' FROM docs GROUP BY topic LIMIT 1;").unwrap();
let qql_core::ast::Stmt::Query(query) = &stmt else {
panic!("expected query");
};
assert!(query.collection_span.is_some());
let group = query.group.as_ref().expect("group must parse");
assert!(group.field_span.is_some());
let stmt = Parser::parse(
"WITH a AS (QUERY TEXT 'x' MODEL 'e5' WHERE status = 'on') \
QUERY TEXT 'x' MODEL 'e5' FROM docs PREFETCH (a) LIMIT 1;",
)
.unwrap();
let qql_core::ast::Stmt::Query(query) = &stmt else {
panic!("expected query");
};
assert!(query.collection_span.is_some());
assert!(query.ctes[0].query.collection_span.is_none());
}
#[test]
fn hybrid_limit_times_ten_overflow_is_a_validation_error() {
let result = crate::plan::plan(
&Parser::parse(
"QUERY HYBRID TEXT 'q' DENSE d SPARSE s FROM docs \
LIMIT 18446744073709551615;",
)
.unwrap(),
);
let err = result.unwrap_err();
assert_eq!(err.kind, qql_core::error::ErrorKind::Validation);
assert_eq!(err.code, "QQL-VALIDATION-LIMIT-OVERFLOW");
}
#[test]
fn plain_limit_and_offset_u64_max_plan_through() {
let op = crate::plan::plan(
&Parser::parse(
"QUERY VECTOR [0.1] FROM docs USING dense \
LIMIT 18446744073709551615 OFFSET 18446744073709551615;",
)
.unwrap(),
)
.unwrap();
let crate::plan::PlannedOperation::Query { request, .. } = &op else {
panic!("expected Query, got {op:?}");
};
assert_eq!(request.limit, Some(u64::MAX));
assert_eq!(request.offset, Some(u64::MAX));
}
#[test]
fn grouped_limit_u64_max_without_offset_plans_through() {
let op = crate::plan::plan(
&Parser::parse("QUERY TEXT 'x' FROM docs GROUP BY topic LIMIT 18446744073709551615;")
.unwrap(),
)
.unwrap();
let crate::plan::PlannedOperation::QueryGroups { request, .. } = &op else {
panic!("expected QueryGroups, got {op:?}");
};
assert_eq!(request.limit, u64::MAX);
}
#[test]
fn hybrid_limit_times_ten_boundary_plans_through() {
let op = crate::plan::plan(
&Parser::parse(
"QUERY HYBRID TEXT 'q' DENSE d SPARSE s FROM docs \
LIMIT 1844674407370955161;",
)
.unwrap(),
)
.unwrap();
let crate::plan::PlannedOperation::Query { request, .. } = &op else {
panic!("expected Query, got {op:?}");
};
let candidates = request.prefetch.first().and_then(|p| p.limit).unwrap();
assert_eq!(candidates, 1844674407370955161 * 10);
}
#[test]
fn query_defaults_with_payload_to_true_when_omitted() {
let json = parse_route("QUERY TEXT 'q' FROM docs;");
assert_eq!(json["with_payload"], true);
}
#[test]
fn query_respects_explicit_with_payload_false() {
let json = parse_route("QUERY TEXT 'q' FROM docs WITH PAYLOAD false;");
assert_eq!(json["with_payload"], false);
}
#[test]
fn decay_datetime_target_and_variable_auto_inferred() {
let json = parse_route(
"QUERY FORMULA EXP_DECAY(judgment_date, TARGET = '2026-09-04T00:00:00Z', SCALE = 630720000, MIDPOINT = 0.5) FROM docs;",
);
let decay = &json["query"]["formula"]["exp_decay"];
assert_eq!(decay["x"]["datetime_key"], "judgment_date");
assert_eq!(decay["target"]["datetime"], "2026-09-04T00:00:00Z");
assert_eq!(decay["scale"], 630720000.0);
assert_eq!(decay["midpoint"], 0.5);
}
}