Skip to main content

uqa_execution/operator_tree/
query.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Retrieval predicates and row functions within an active query statement.
8
9mod functions;
10
11use super::{
12    binding::RetrievalBinding,
13    driver::posting::posting_list_to_scored,
14    runtime::{
15        execute_preoptimized_scored_entries, execute_tree, expect_posting_output,
16        TreeExecutionContext,
17    },
18};
19use crate::query::graph_lifecycle::GraphLifecycle;
20use uqa_core::ScoredEntry;
21use uqa_operators::OperatorTree;
22use uqa_sql::{SQLError, SQLParam, ScalarExpr};
23
24/// Planner-owned access selection and physical text limits.
25pub trait RelationRetrievalPlanner: Sync {
26    fn accelerated_tree(
27        &self,
28        table: &str,
29        expression: &ScalarExpr,
30        tree: OperatorTree,
31    ) -> Result<Option<OperatorTree>, SQLError>;
32    fn text_top_k(
33        &self,
34        table: &str,
35        tree: OperatorTree,
36        top_k: usize,
37    ) -> Result<OperatorTree, SQLError>;
38}
39
40/// Inputs for retrieval calls below the caller's statement and transaction boundary.
41pub struct RetrievalQueryContext<'a> {
42    pub binding: RetrievalBinding<'a>,
43    pub trees: TreeExecutionContext<'a>,
44    pub planner: &'a dyn RelationRetrievalPlanner,
45    pub graphs: &'a dyn GraphLifecycle,
46}
47impl<'a> RetrievalQueryContext<'a> {
48    /// Read relation declarations when lowering needs to distinguish stored pseudo columns or composite NULL tests from scalar storage predicates.
49    fn lower_relation_where(
50        &self,
51        table: &str,
52        expression: &ScalarExpr,
53        params: &[SQLParam],
54    ) -> Result<Option<OperatorTree>, SQLError> {
55        let columns = if uqa_sql::retrieval::names_engine_pseudo_column(expression)
56            || super::binding::has_column_null_test(expression)
57        {
58            self.trees
59                .driver
60                .relations
61                .try_describe_query_table(table)
62                .map_err(|error| {
63                    SQLError::Internal(format!("resolve retrieval table `{table}`: {error}"))
64                })?
65                .unwrap_or_default()
66        } else {
67            Vec::new()
68        };
69        self.binding
70            .lower_relation_where(&columns, expression, params)
71    }
72
73    pub fn optimized(
74        &self,
75        table: &str,
76        where_expr: Option<&ScalarExpr>,
77        params: &[SQLParam],
78    ) -> Result<Option<Vec<ScoredEntry>>, SQLError> {
79        let Some(expr) = where_expr else {
80            return Ok(None);
81        };
82        let Some(tree) = self.lower_relation_where(table, expr, params)? else {
83            return Ok(None);
84        };
85        let pl = expect_posting_output(
86            execute_tree(&self.trees, table, table, params, &tree)?,
87            "SQL WHERE",
88        )?;
89        Ok(Some(posting_list_to_scored(&pl)))
90    }
91
92    pub fn prepare_accelerated<'b>(
93        &self,
94        table: &'b str,
95        signal_table: &'b str,
96        where_expr: Option<&ScalarExpr>,
97        params: &'b [SQLParam],
98        capture_complete_scores: bool,
99    ) -> Result<Option<crate::query::scored_input::ScoredEntriesProducer<'b>>, SQLError>
100    where
101        'a: 'b,
102    {
103        let Some(expression) = where_expr else {
104            return Ok(None);
105        };
106        let Some(tree) = self.lower_relation_where(table, expression, params)? else {
107            return Ok(None);
108        };
109        let Some(optimized) = self.planner.accelerated_tree(table, expression, tree)? else {
110            return Ok(None);
111        };
112        let trees = self.trees;
113        Ok(Some(Box::new(move || {
114            execute_preoptimized_scored_entries(
115                &trees,
116                table,
117                signal_table,
118                params,
119                &optimized,
120                capture_complete_scores,
121            )
122        })))
123    }
124
125    /// Preserve the ordinary predicate's lowering and optimizer boundary while retaining complete text scores in bounded storage.
126    pub fn captured(
127        &self,
128        table: &str,
129        where_expr: Option<&ScalarExpr>,
130        params: &[SQLParam],
131    ) -> Result<Option<crate::query::scored_input::ProducedScoredEntries>, SQLError> {
132        let Some(expr) = where_expr else {
133            return Ok(None);
134        };
135        let Some(tree) = self.lower_relation_where(table, expr, params)? else {
136            return Ok(None);
137        };
138        super::runtime::execute_captured_tree(&self.trees, table, params, &tree).map(Some)
139    }
140}