Skip to main content

uqa_execution/query/cte/
context.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Child-query execution, output rewrites, and expression services for CTEs.
8
9use crate::{
10    query::{output::QueryOutput, runtime::QueryRuntimeView, CteScope},
11    OwnedPhysicalRow,
12};
13use uqa_sql::{
14    expr::EngineHook,
15    plan::{CommandPlan, QueryPlan},
16    routines::RoutineResolution,
17    SQLError, SQLParam, ScalarExpr,
18};
19
20pub trait CteBodyExecutor<S: Clone>: Sync {
21    /// Retain the active query allowance and its original cancellation owner for CTE analysis and scheduling.
22    fn read_control(&self) -> Result<uqa_storage::read_control::StorageReadControl, SQLError>;
23    /// Retain one read-only physical producer and its selected session inputs. A semantic materialization that cannot expose a pull operator returns None.
24    fn retained_query(
25        &self,
26        query: &QueryPlan,
27        params: &[SQLParam],
28        ctes: &CteScope<S>,
29    ) -> Result<Option<Box<dyn crate::PhysicalOperator>>, SQLError>;
30    fn execute_query(
31        &self,
32        query: &QueryPlan,
33        params: &[SQLParam],
34        ctes: &mut CteScope<S>,
35    ) -> Result<QueryOutput, SQLError>;
36    fn execute_lateral_query(
37        &self,
38        query: &QueryPlan,
39        outer: &OwnedPhysicalRow,
40        params: &[SQLParam],
41        ctes: &CteScope<S>,
42    ) -> Result<QueryOutput, SQLError>;
43    fn execute_command(
44        &self,
45        command: &CommandPlan,
46        params: &[SQLParam],
47        ctes: &CteScope<S>,
48    ) -> Result<crate::mutation::output::MutationOutput, SQLError>;
49    /// Fire the AFTER events that the commands of a statement queued, once the statement has finished.
50    fn fire_after_triggers(
51        &self,
52        queue: &crate::mutation::triggers::queue::AfterTriggerQueue,
53    ) -> Result<(), SQLError>;
54}
55
56pub trait QueryOutputRewriter: Sync {
57    /// Remove scalar output expressions the containing query does not need, preserving the stored row descriptor and side effects.
58    fn prune_query_outputs(
59        &self,
60        query: &mut QueryPlan,
61        aliases: &[String],
62        projection: &uqa_sql::plan::source_projection::SourceProjection,
63        schema: &crate::RowSchema,
64        visible_ctes: &dyn Fn(&str) -> bool,
65    ) -> Result<(), SQLError>;
66
67    /// Optimize a catalog-retained query before assembling either its streaming or materialized execution path.
68    fn optimize_retained_query(&self, query: &QueryPlan) -> Result<QueryPlan, SQLError>;
69
70    /// Return a plan that applies the complete output predicate, or `None` when the caller must retain it.
71    fn push_output_filter(
72        &self,
73        query: &QueryPlan,
74        qualifier: &str,
75        filter: &ScalarExpr,
76        output_columns: Option<&[String]>,
77    ) -> Result<Option<QueryPlan>, SQLError>;
78
79    /// Place a predicate inside an ordinary derived source. Recursive specialization keeps its separate effect boundary through `push_output_filter`.
80    fn push_derived_output_filter(
81        &self,
82        query: &QueryPlan,
83        qualifier: &str,
84        filter: &ScalarExpr,
85        output_columns: Option<&[String]>,
86    ) -> Result<Option<QueryPlan>, SQLError> {
87        self.push_output_filter(query, qualifier, filter, output_columns)
88    }
89}
90
91#[derive(Clone)]
92pub struct CteExecutionContext<'a, S: Clone> {
93    pub queries: &'a dyn CteBodyExecutor<S>,
94    pub rewrites: &'a dyn QueryOutputRewriter,
95    pub routines: &'a dyn RoutineResolution,
96    pub functions: &'a (dyn EngineHook + Sync),
97    pub runtime: QueryRuntimeView<'a>,
98}
99impl<S: Clone> Copy for CteExecutionContext<'_, S> {}