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    /// Lower `expression` on `table`, whose declared columns decide how a predicate on an engine pseudo column lowers. They are read only for an expression that names one.
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            self.trees
57                .driver
58                .relations
59                .try_describe_query_table(table)
60                .map_err(|error| {
61                    SQLError::Internal(format!("resolve retrieval table `{table}`: {error}"))
62                })?
63                .unwrap_or_default()
64        } else {
65            Vec::new()
66        };
67        self.binding
68            .lower_relation_where(&columns, expression, params)
69    }
70
71    pub fn optimized(
72        &self,
73        table: &str,
74        where_expr: Option<&ScalarExpr>,
75        params: &[SQLParam],
76    ) -> Result<Option<Vec<ScoredEntry>>, SQLError> {
77        let Some(expr) = where_expr else {
78            return Ok(None);
79        };
80        let Some(tree) = self.lower_relation_where(table, expr, params)? else {
81            return Ok(None);
82        };
83        let pl = expect_posting_output(
84            execute_tree(&self.trees, table, table, params, &tree)?,
85            "SQL WHERE",
86        )?;
87        Ok(Some(posting_list_to_scored(&pl)))
88    }
89
90    pub fn prepare_accelerated<'b>(
91        &self,
92        table: &'b str,
93        signal_table: &'b str,
94        where_expr: Option<&ScalarExpr>,
95        params: &'b [SQLParam],
96        capture_complete_scores: bool,
97    ) -> Result<Option<crate::query::scored_input::ScoredEntriesProducer<'b>>, SQLError>
98    where
99        'a: 'b,
100    {
101        let Some(expression) = where_expr else {
102            return Ok(None);
103        };
104        let Some(tree) = self.lower_relation_where(table, expression, params)? else {
105            return Ok(None);
106        };
107        let Some(optimized) = self.planner.accelerated_tree(table, expression, tree)? else {
108            return Ok(None);
109        };
110        let trees = self.trees;
111        Ok(Some(Box::new(move || {
112            execute_preoptimized_scored_entries(
113                &trees,
114                table,
115                signal_table,
116                params,
117                &optimized,
118                capture_complete_scores,
119            )
120        })))
121    }
122
123    /// Preserve the ordinary predicate's lowering and optimizer boundary while retaining complete text scores in bounded storage.
124    pub fn captured(
125        &self,
126        table: &str,
127        where_expr: Option<&ScalarExpr>,
128        params: &[SQLParam],
129    ) -> Result<Option<crate::query::scored_input::ProducedScoredEntries>, SQLError> {
130        let Some(expr) = where_expr else {
131            return Ok(None);
132        };
133        let Some(tree) = self.lower_relation_where(table, expr, params)? else {
134            return Ok(None);
135        };
136        super::runtime::execute_captured_tree(&self.trees, table, params, &tree).map(Some)
137    }
138}