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    binding::stored_routines::mark_catalog_statement_relations_bound,
14    plan::{AggregateClassifier, CommandPlan, ExecutablePlanOptimizer, UnifiedPlan},
15    SQLError, SQLParam, SQLResult, Statement,
16};
17
18pub struct CompiledStatementContext<'a, S: Clone + 'static> {
19    pub aggregates: &'a dyn AggregateClassifier,
20    pub planning: &'a dyn ExecutablePlanOptimizer,
21    pub statements: &'a dyn StatementExecutionInputs<S>,
22    /// The session's cancellation, which the statement's analysis, planning and execution observe.
23    pub cancellation: &'a uqa_core::CancellationToken,
24}
25
26pub fn execute<S: Clone + Send + Sync + 'static>(
27    context: &CompiledStatementContext<'_, S>,
28    statement: Statement,
29    params: &[SQLParam],
30) -> Result<SQLResult, SQLError> {
31    let plan = UnifiedPlan::lower_with(statement, context.aggregates);
32    execute_plan(context, plan, params)
33}
34
35pub fn execute_plan<S: Clone + Send + Sync + 'static>(
36    context: &CompiledStatementContext<'_, S>,
37    plan: UnifiedPlan,
38    params: &[SQLParam],
39) -> Result<SQLResult, SQLError> {
40    let _statement_thread =
41        super::context::statement_thread_scope(context.statements, context.cancellation);
42    let plan = context.planning.plan_for_execution(plan, params)?;
43    UnifiedPlanExecutor::new_nested(context.statements.statement_execution_context(), params)
44        .execute(&plan)
45}
46
47/// A prepared owner has already analyzed and selected this executable. Capture
48/// fresh execution inputs without binding or optimizing it a second time.
49pub fn execute_selected_plan<S: Clone + Send + Sync + 'static>(
50    context: &CompiledStatementContext<'_, S>,
51    plan: &UnifiedPlan,
52    params: &[SQLParam],
53) -> Result<SQLResult, SQLError> {
54    let _statement_thread =
55        super::context::statement_thread_scope(context.statements, context.cancellation);
56    UnifiedPlanExecutor::new_nested(context.statements.statement_execution_context(), params)
57        .execute(plan)
58}
59
60/// Run a statement once `check` accepts what its analysis derives about its result.
61pub fn execute_checked_plan<S: Clone + Send + Sync + 'static>(
62    context: &CompiledStatementContext<'_, S>,
63    plan: UnifiedPlan,
64    params: &[SQLParam],
65    check: &dyn Fn(&AnalyzedResult) -> Result<(), SQLError>,
66) -> Result<SQLResult, SQLError> {
67    let _statement_thread =
68        super::context::statement_thread_scope(context.statements, context.cancellation);
69    let (plan, result) = context.planning.plan_with_result(plan, params)?;
70    check(&result)?;
71    UnifiedPlanExecutor::new_nested(context.statements.statement_execution_context(), params)
72        .execute(&plan)
73}
74
75pub fn execute_with_privilege_subject<S: Clone + Send + Sync + 'static>(
76    context: &CompiledStatementContext<'_, S>,
77    statement: Statement,
78    params: &[SQLParam],
79    privilege_subject: &RoleReference,
80) -> Result<SQLResult, SQLError> {
81    let _statement_thread =
82        super::context::statement_thread_scope(context.statements, context.cancellation);
83    let plan = stored_plan(context, statement, params)?;
84    UnifiedPlanExecutor::new_nested(context.statements.statement_execution_context(), params)
85        .with_privilege_subject(privilege_subject)
86        .execute(&plan)
87}
88
89/// Finish a stored rule action under its owner, keeping query and mutation output in bounded physical storage.
90pub fn execute_output_with_privilege_subject<S: Clone + Send + Sync + 'static>(
91    context: &CompiledStatementContext<'_, S>,
92    action: uqa_sql::semantics::rules::binding::RuleAction,
93    params: &[SQLParam],
94    inherited_ctes: Option<&crate::query::CteScope<S>>,
95    privilege_subject: &RoleReference,
96    consumer: Option<std::rc::Rc<dyn crate::query::consumer::QueryRowConsumer + '_>>,
97) -> Result<super::plan_executor::StatementOutput, SQLError> {
98    let _statement_thread =
99        super::context::statement_thread_scope(context.statements, context.cancellation);
100    let plan = action.lower(context.aggregates)?;
101    let plan = context.planning.plan_for_execution(plan, params)?;
102    UnifiedPlanExecutor::new_nested(context.statements.statement_execution_context(), params)
103        .with_privilege_subject(privilege_subject)
104        .with_inherited_ctes(inherited_ctes)
105        .execute_for_output_mode(
106            &plan,
107            consumer.map_or(
108                crate::query::statement::consumer::QueryOutputMode::SharedSpill,
109                crate::query::statement::consumer::QueryOutputMode::physical_consumer,
110            ),
111        )
112}
113
114fn stored_plan<S: Clone + 'static>(
115    context: &CompiledStatementContext<'_, S>,
116    statement: Statement,
117    params: &[SQLParam],
118) -> Result<UnifiedPlan, SQLError> {
119    let mut plan = UnifiedPlan::lower_with(statement, context.aggregates);
120    mark_catalog_statement_relations_bound(&mut plan)?;
121    context.planning.plan_for_execution(plan, params)
122}
123
124pub fn execute_optimized_command<S: Clone + Send + Sync + 'static>(
125    context: &CompiledStatementContext<'_, S>,
126    command: &CommandPlan,
127    params: &[SQLParam],
128) -> Result<SQLResult, SQLError> {
129    let _statement_thread =
130        super::context::statement_thread_scope(context.statements, context.cancellation);
131    UnifiedPlanExecutor::new_nested(context.statements.statement_execution_context(), params)
132        .execute(&UnifiedPlan::Command(Box::new(command.clone())))
133}
134
135#[cfg(test)]
136mod tests;