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_tree, execute_tree, expect_posting_output, TreeExecutionContext,
16    },
17};
18use crate::query::graph_lifecycle::GraphLifecycle;
19use uqa_core::ScoredEntry;
20use uqa_operators::OperatorTree;
21use uqa_sql::{SQLError, SQLParam, ScalarExpr};
22
23/// Planner-owned access selection and physical text limits.
24pub trait RelationRetrievalPlanner: Sync {
25    fn accelerated_tree(
26        &self,
27        table: &str,
28        expression: &ScalarExpr,
29        tree: OperatorTree,
30    ) -> Result<Option<OperatorTree>, SQLError>;
31    fn text_top_k(
32        &self,
33        table: &str,
34        tree: OperatorTree,
35        top_k: usize,
36    ) -> Result<OperatorTree, SQLError>;
37}
38
39/// Inputs for retrieval calls below the caller's statement and transaction boundary.
40pub struct RetrievalQueryContext<'a> {
41    pub binding: RetrievalBinding<'a>,
42    pub trees: TreeExecutionContext<'a>,
43    pub planner: &'a dyn RelationRetrievalPlanner,
44    pub graphs: &'a dyn GraphLifecycle,
45}
46impl<'a> RetrievalQueryContext<'a> {
47    /// 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.
48    fn lower_relation_where(
49        &self,
50        table: &str,
51        expression: &ScalarExpr,
52        params: &[SQLParam],
53    ) -> Result<Option<OperatorTree>, SQLError> {
54        let columns = if uqa_sql::retrieval::names_engine_pseudo_column(expression) {
55            self.trees
56                .driver
57                .relations
58                .try_describe_query_table(table)
59                .map_err(|error| {
60                    SQLError::Internal(format!("resolve retrieval table `{table}`: {error}"))
61                })?
62                .unwrap_or_default()
63        } else {
64            Vec::new()
65        };
66        self.binding
67            .lower_relation_where(&columns, expression, params)
68    }
69
70    pub fn optimized(
71        &self,
72        table: &str,
73        where_expr: Option<&ScalarExpr>,
74        params: &[SQLParam],
75    ) -> Result<Option<Vec<ScoredEntry>>, SQLError> {
76        let Some(expr) = where_expr else {
77            return Ok(None);
78        };
79        let Some(tree) = self.lower_relation_where(table, expr, params)? else {
80            return Ok(None);
81        };
82        let pl = expect_posting_output(
83            execute_tree(&self.trees, table, table, params, &tree)?,
84            "SQL WHERE",
85        )?;
86        Ok(Some(posting_list_to_scored(&pl)))
87    }
88
89    pub fn prepare_accelerated<'b>(
90        &self,
91        table: &'b str,
92        signal_table: &'b str,
93        where_expr: Option<&ScalarExpr>,
94        params: &'b [SQLParam],
95    ) -> Result<Option<crate::query::scored_input::ScoredEntriesProducer<'b>>, SQLError>
96    where
97        'a: 'b,
98    {
99        let Some(expression) = where_expr else {
100            return Ok(None);
101        };
102        let Some(tree) = self.lower_relation_where(table, expression, params)? else {
103            return Ok(None);
104        };
105        let Some(optimized) = self.planner.accelerated_tree(table, expression, tree)? else {
106            return Ok(None);
107        };
108        let trees = self.trees;
109        Ok(Some(Box::new(move || {
110            let output =
111                execute_preoptimized_tree(&trees, table, signal_table, params, &optimized)?;
112            let posting = expect_posting_output(output, "SQL WHERE")?;
113            Ok(posting_list_to_scored(&posting))
114        })))
115    }
116}