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    statement: Statement,
93    params: &[SQLParam],
94    privilege_subject: &RoleReference,
95) -> Result<super::plan_executor::StatementOutput, SQLError> {
96    let _statement_thread =
97        super::context::statement_thread_scope(context.statements, context.cancellation);
98    let plan = stored_plan(context, statement, params)?;
99    UnifiedPlanExecutor::new_nested(context.statements.statement_execution_context(), params)
100        .with_privilege_subject(privilege_subject)
101        .execute_for_output(&plan)
102}
103
104fn stored_plan<S: Clone + 'static>(
105    context: &CompiledStatementContext<'_, S>,
106    statement: Statement,
107    params: &[SQLParam],
108) -> Result<UnifiedPlan, SQLError> {
109    let mut plan = UnifiedPlan::lower_with(statement, context.aggregates);
110    mark_catalog_statement_relations_bound(&mut plan)?;
111    context.planning.plan_for_execution(plan, params)
112}
113
114pub fn execute_optimized_command<S: Clone + Send + Sync + 'static>(
115    context: &CompiledStatementContext<'_, S>,
116    command: &CommandPlan,
117    params: &[SQLParam],
118) -> Result<SQLResult, SQLError> {
119    let _statement_thread =
120        super::context::statement_thread_scope(context.statements, context.cancellation);
121    UnifiedPlanExecutor::new_nested(context.statements.statement_execution_context(), params)
122        .execute(&UnifiedPlan::Command(Box::new(command.clone())))
123}
124
125#[cfg(test)]
126mod tests;