uqa_sql/retrieval/
mod.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! SQL retrieval argument binding and lowering to runtime-independent expressions.
8
9mod binding;
10mod calls;
11mod constants;
12mod description;
13mod fusion;
14mod graph;
15mod ir;
16mod joins;
17mod predicates;
18#[cfg(test)]
19mod tests;
20use crate::semantics::graph_functions::{
21    default_graph_name as default_operator_graph, GraphNameCatalog,
22};
23use crate::{ast::BinaryOp, SQLError, SQLParam, ScalarExpr};
24pub use binding::{lower_sql_function_bound, lower_where_bound};
25pub use description::{describe_vector_call, VectorCallDescription};
26pub use ir::{AttentionSpec, MultiStageEntry, RetrievalExpr, TextScoringMode};
27pub use joins::lower_operator_join_table_function;
28use std::collections::BTreeSet;
29use uqa_core::{
30    retrieval::{Direction as DeepGraphDirection, ExternalPriorMode, GatingSpec, MultiStageCutoff},
31    Predicate, Value,
32};
33type BindingResult<T> = Result<T, SQLError>;
34
35/// Evaluates a scalar with the caller's parameter values and without runtime function hooks.
36pub type ConstantEvaluator<'a> = dyn Fn(&ScalarExpr, &[SQLParam]) -> Result<Value, SQLError> + 'a;
37pub struct RetrievalConstants<'a> {
38    pub params: &'a [SQLParam],
39    pub evaluate: &'a ConstantEvaluator<'a>,
40    /// Whether the relation a predicate filters declares a column of the given name. A predicate on an engine pseudo column such as `_doc_id` filters a stored field only where the relation declares one; elsewhere it stays relational, where the column carries each row's value.
41    pub stores: &'a dyn Fn(&str) -> bool,
42}
43impl RetrievalConstants<'_> {
44    fn without_parameters(&self) -> RetrievalConstants<'_> {
45        RetrievalConstants {
46            params: &[],
47            evaluate: self.evaluate,
48            stores: self.stores,
49        }
50    }
51}
52
53/// Whether `expression` names an engine pseudo column, whose predicates lower according to the columns the relation declares.
54#[must_use]
55pub fn names_engine_pseudo_column(expression: &ScalarExpr) -> bool {
56    let mut names = false;
57    expression.visit(&mut |node| {
58        if let ScalarExpr::Column(column) | ScalarExpr::QualifiedColumn { column, .. } = node {
59            names |= crate::semantics::is_engine_pseudo_column(column);
60        }
61    });
62    names
63}
64/// Runtime scalar evaluation and graph catalog access; SQL owns recursion and validation order.
65pub trait RetrievalArguments: GraphNameCatalog {
66    fn evaluate_argument(
67        &self,
68        expression: &ScalarExpr,
69        params: &[SQLParam],
70    ) -> Result<Value, SQLError>;
71}
72
73use calls::{
74    bind_operator_argument, checked_retrieval_call_tree_present, lower_bayesian_match_with_prior,
75    lower_calibrated_vector_match, lower_multi_field_match, lower_operator_arg, lower_signal_arg,
76    lower_staged_retrieval, try_lower_fts_match, try_lower_knn_match, try_lower_text_match,
77    validate_checked_retrieval_call_tree, validate_operator_function_arity,
78    validate_probability_signal_contract,
79};
80use constants::{
81    const_bool, const_f64, const_f64_vector, const_gating, const_optional_string, const_string,
82    const_temporal_bound, const_usize, const_value, const_vector, named_arg_expr,
83};
84use fusion::{
85    lower_bayesian_evidence_fusion, lower_learned_fusion, lower_positive_evidence_pool,
86    try_lower_attention_fusion,
87};
88use graph::lower_graph_function;
89use predicates::{column_name, lower_comparison, lower_document_boolean, lower_function};
90
91enum OptionalStringConstant {
92    Null,
93    Value(String),
94}
95impl OptionalStringConstant {
96    fn into_option(self) -> Option<String> {
97        match self {
98            Self::Null => None,
99            Self::Value(value) => Some(value),
100        }
101    }
102}
103
104/// Lower representable SQL predicates using the supplied constant evaluator. Unsupported scalar shapes remain relational predicates.
105pub fn lower_where(expr: &ScalarExpr, constants: &RetrievalConstants<'_>) -> Option<RetrievalExpr> {
106    if let Some(membership) = crate::semantics::membership_operands(expr) {
107        return lower_membership(
108            membership.value,
109            membership.items,
110            membership.negated,
111            constants,
112        );
113    }
114    match expr {
115        ScalarExpr::And(parts) => {
116            let mut out: Vec<RetrievalExpr> = Vec::with_capacity(parts.len());
117            for p in parts {
118                out.push(lower_where(p, constants)?);
119            }
120            Some(lower_document_boolean(out, false))
121        }
122        ScalarExpr::Or(parts) => {
123            let mut out: Vec<RetrievalExpr> = Vec::with_capacity(parts.len());
124            for p in parts {
125                out.push(lower_where(p, constants)?);
126            }
127            Some(lower_document_boolean(out, true))
128        }
129        // Complement is only sound when the inner predicate cannot be
130        // NULL for any row (search functions, IS NULL tests). Column
131        // comparisons under NOT fall through to the wildcard `None`
132        // and keep three-valued semantics through the row-evaluator
133        // relational evaluation: `NOT (col = 5)` must not match rows whose `col`
134        // is NULL.
135        ScalarExpr::Not(inner) if crate::semantics::expr_is_null_free(inner) => Some(
136            RetrievalExpr::Complement(Box::new(lower_where(inner, constants)?)),
137        ),
138        ScalarExpr::Func { name, args, .. } => lower_function(name, args, constants),
139        ScalarExpr::Binary { op, lhs, rhs } => lower_comparison(*op, lhs, rhs, constants),
140        ScalarExpr::IsNull { expr, negated } => {
141            let field = predicates::filter_field(expr, constants)?;
142            let predicate = if *negated {
143                Predicate::IsNotNull
144            } else {
145                Predicate::IsNull
146            };
147            Some(RetrievalExpr::Filter {
148                field,
149                predicate,
150                source: None,
151            })
152        }
153        ScalarExpr::Between { expr, low, high } => {
154            let field = predicates::filter_field(expr, constants)?;
155            let lo = const_value(low, constants)?;
156            let hi = const_value(high, constants)?;
157            Some(RetrievalExpr::Filter {
158                field,
159                predicate: Predicate::Between { low: lo, high: hi },
160                source: None,
161            })
162        }
163        _ => None,
164    }
165}
166
167fn lower_membership(
168    expr: &ScalarExpr,
169    list: crate::semantics::MembershipItems<'_>,
170    negated: bool,
171    constants: &RetrievalConstants<'_>,
172) -> Option<RetrievalExpr> {
173    let field = predicates::filter_field(expr, constants)?;
174    let mut set: BTreeSet<Value> = BTreeSet::new();
175    let mut has_null = false;
176    for item in list.iter() {
177        let value = match item {
178            crate::semantics::MembershipItem::Expression(expression) => {
179                const_value(expression, constants)?
180            }
181            crate::semantics::MembershipItem::Constant(value) => value.clone(),
182        };
183        if matches!(value, Value::Array(_)) {
184            return None;
185        }
186        if matches!(value, Value::Null) {
187            has_null = true;
188            continue;
189        }
190        set.insert(value);
191    }
192    if negated {
193        // `col NOT IN (...)`: a NULL in the list means no row
194        // can ever satisfy it; otherwise complement the match
195        // set but keep NULL rows excluded (three-valued NOT).
196        if has_null {
197            return Some(RetrievalExpr::Empty);
198        }
199        let filter = RetrievalExpr::Filter {
200            field: field.clone(),
201            predicate: Predicate::InSet(set),
202            source: None,
203        };
204        let not_null = RetrievalExpr::Filter {
205            field,
206            predicate: Predicate::IsNotNull,
207            source: None,
208        };
209        return Some(RetrievalExpr::Intersect(vec![
210            RetrievalExpr::Complement(Box::new(filter)),
211            not_null,
212        ]));
213    }
214    Some(RetrievalExpr::Filter {
215        field,
216        predicate: Predicate::InSet(set),
217        source: None,
218    })
219}
uqa_sql/retrieval/mod.rs

uqa_sql/retrieval/
mod.rs
