Skip to main content

uqa_execution/statement/
compiled.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Execute compiled statements with planning and statement scopes captured at their point of use.
8
9use super::{context::StatementExecutionInputs, plan_executor::UnifiedPlanExecutor};
10use uqa_sql::catalog::roles::RoleReference;
11use uqa_sql::{
12    binding::statements::AnalyzedResult,
13    plan::{AggregateClassifier, CommandPlan, ExecutablePlanOptimizer, UnifiedPlan},
14    SQLError, SQLParam, SQLResult, Statement,
15};
16
17pub struct CompiledStatementContext<'a, S: Clone + 'static> {
18    pub aggregates: &'a dyn AggregateClassifier,
19    pub planning: &'a dyn ExecutablePlanOptimizer,
20    pub statements: &'a dyn StatementExecutionInputs<S>,
21    /// The session's cancellation, which the statement's analysis, planning and execution observe.
22    pub cancellation: &'a uqa_core::CancellationToken,
23}
24
25pub fn execute<S: Clone + Send + Sync + 'static>(
26    context: &CompiledStatementContext<'_, S>,
27    statement: Statement,
28    params: &[SQLParam],
29) -> Result<SQLResult, SQLError> {
30    let _statement_thread =
31        super::context::statement_thread_scope(context.statements, context.cancellation);
32    let resources = context.planning.planning_control()?;
33    let control = resources.control();
34    let plan = UnifiedPlan::lower_borrowed_for_rewrite(&statement, context.aggregates, &control)?;
35    let plan = context
36        .planning
37        .plan_owned_for_execution(plan, params, &control)?;
38    UnifiedPlanExecutor::new_nested(context.statements.statement_execution_context(), params)
39        .execute(&plan)
40}
41
42pub fn execute_plan<S: Clone + Send + Sync + 'static>(
43    context: &CompiledStatementContext<'_, S>,
44    plan: UnifiedPlan,
45    params: &[SQLParam],
46) -> Result<SQLResult, SQLError> {
47    let _statement_thread =
48        super::context::statement_thread_scope(context.statements, context.cancellation);
49    let resources = context.planning.planning_control()?;
50    let control = resources.control();
51    let plan = context.planning.plan_owned_for_execution(
52        plan.copy_for_rewrite(&control)?,
53        params,
54        &control,
55    )?;
56    UnifiedPlanExecutor::new_nested(context.statements.statement_execution_context(), params)
57        .execute(&plan)
58}
59
60/// A prepared owner has already analyzed and selected this executable. Capture
61/// fresh execution inputs without binding or optimizing it a second time.
62pub fn execute_selected_plan<S: Clone + Send + Sync + 'static>(
63    context: &CompiledStatementContext<'_, S>,
64    plan: &UnifiedPlan,
65    params: &[SQLParam],
66) -> Result<SQLResult, SQLError> {
67    let _statement_thread =
68        super::context::statement_thread_scope(context.statements, context.cancellation);
69    UnifiedPlanExecutor::new_nested(context.statements.statement_execution_context(), params)
70        .execute(plan)
71}
72
73/// Run a statement once `check` accepts what its analysis derives about its result.
74pub fn execute_checked_plan<S: Clone + Send + Sync + 'static>(
75    context: &CompiledStatementContext<'_, S>,
76    plan: UnifiedPlan,
77    params: &[SQLParam],
78    check: &dyn Fn(&AnalyzedResult) -> Result<(), SQLError>,
79) -> Result<SQLResult, SQLError> {
80    let _statement_thread =
81        super::context::statement_thread_scope(context.statements, context.cancellation);
82    let resources = context.planning.planning_control()?;
83    let control = resources.control();
84    let (plan, result) = context.planning.plan_owned_with_result(
85        plan.copy_for_rewrite(&control)?,
86        params,
87        &control,
88    )?;
89    check(&result)?;
90    UnifiedPlanExecutor::new_nested(context.statements.statement_execution_context(), params)
91        .execute(&plan)
92}
93
94pub fn execute_with_privilege_subject<S: Clone + Send + Sync + 'static>(
95    context: &CompiledStatementContext<'_, S>,
96    statement: Statement,
97    params: &[SQLParam],
98    privilege_subject: &RoleReference,
99) -> Result<SQLResult, SQLError> {
100    let _statement_thread =
101        super::context::statement_thread_scope(context.statements, context.cancellation);
102    let plan = stored_plan(context, statement, params)?;
103    UnifiedPlanExecutor::new_nested(context.statements.statement_execution_context(), params)
104        .with_privilege_subject(privilege_subject)
105        .execute(&plan)
106}
107
108/// Finish a stored rule action under its owner, keeping query and mutation output in bounded physical storage.
109pub fn execute_output_with_privilege_subject<S: Clone + Send + Sync + 'static>(
110    context: &CompiledStatementContext<'_, S>,
111    action: uqa_sql::semantics::rules::binding::RuleAction,
112    params: &[SQLParam],
113    inherited_ctes: Option<&crate::query::CteScope<S>>,
114    privilege_subject: &RoleReference,
115    consumer: Option<std::rc::Rc<dyn crate::query::consumer::QueryRowConsumer + '_>>,
116) -> Result<super::plan_executor::StatementOutput, SQLError> {
117    let _statement_thread =
118        super::context::statement_thread_scope(context.statements, context.cancellation);
119    let resources = context.planning.planning_control()?;
120    let control = resources.control();
121    let plan = action.lower_with_control(context.aggregates, &control)?;
122    let plan = context
123        .planning
124        .plan_owned_for_execution(plan, params, &control)?;
125    UnifiedPlanExecutor::new_nested(context.statements.statement_execution_context(), params)
126        .with_privilege_subject(privilege_subject)
127        .with_inherited_ctes(inherited_ctes)
128        .execute_for_output_mode(
129            &plan,
130            consumer.map_or(
131                crate::query::statement::consumer::QueryOutputMode::SharedSpill,
132                crate::query::statement::consumer::QueryOutputMode::physical_consumer,
133            ),
134        )
135}
136
137fn stored_plan<S: Clone + 'static>(
138    context: &CompiledStatementContext<'_, S>,
139    statement: Statement,
140    params: &[SQLParam],
141) -> Result<uqa_sql::plan::SharedExecutablePlan, SQLError> {
142    let resources = context.planning.planning_control()?;
143    let control = resources.control();
144    let plan = UnifiedPlan::lower_borrowed_for_rewrite(&statement, context.aggregates, &control)?
145        .mark_catalog_relations_bound(&control)?;
146    context
147        .planning
148        .plan_owned_for_execution(plan, params, &control)
149}
150
151pub fn execute_optimized_command<S: Clone + Send + Sync + 'static>(
152    context: &CompiledStatementContext<'_, S>,
153    command: &CommandPlan,
154    params: &[SQLParam],
155) -> Result<SQLResult, SQLError> {
156    let _statement_thread =
157        super::context::statement_thread_scope(context.statements, context.cancellation);
158    let resources = context.planning.planning_control()?;
159    let control = resources.control();
160    let plan = uqa_sql::plan::MutableExecutablePlan::Command(command.copy_for_rewrite(&control)?)
161        .finish(&control)?;
162    UnifiedPlanExecutor::new_nested(context.statements.statement_execution_context(), params)
163        .execute(&plan)
164}
165
166#[cfg(test)]
167mod tests;