Skip to main content

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