Skip to main content

uqa_sql/plan/
optimization.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! SQL-plan contract for a caller-selected executable planner.
8
9use super::{SharedExecutablePlan, UnifiedPlan};
10use crate::{binding::statements::AnalyzedResult, SQLError, SQLParam};
11use uqa_core::memory::{OwnedProductionControl, ProductionControl};
12
13/// Analyze and optimize a logical plan using metadata captured for this call.
14pub trait ExecutablePlanOptimizer {
15    fn planning_control(&self) -> Result<OwnedProductionControl, SQLError> {
16        Ok(ProductionControl::uncontrolled().capture())
17    }
18
19    fn plan_owned_for_execution(
20        &self,
21        plan: super::MutableExecutablePlan,
22        params: &[SQLParam],
23        control: &ProductionControl<'_>,
24    ) -> Result<SharedExecutablePlan, SQLError> {
25        self.plan_for_execution(ordinary_plan(plan, control)?, params)
26    }
27
28    fn plan_owned_with_result(
29        &self,
30        plan: super::MutableExecutablePlan,
31        params: &[SQLParam],
32        control: &ProductionControl<'_>,
33    ) -> Result<(SharedExecutablePlan, AnalyzedResult), SQLError> {
34        self.plan_with_result(ordinary_plan(plan, control)?, params)
35    }
36
37    fn plan_owned_for_statement_cache(
38        &self,
39        plan: super::MutableExecutablePlan,
40        params: &[SQLParam],
41        control: &ProductionControl<'_>,
42    ) -> Result<(SharedExecutablePlan, bool), SQLError> {
43        self.plan_for_statement_cache(ordinary_plan(plan, control)?, params)
44    }
45
46    fn plan_owned_with_cached_analysis(
47        &self,
48        plan: super::MutableExecutablePlan,
49        params: &[SQLParam],
50        cached: Option<crate::binding::statements::AnalyzedStatement>,
51        control: &ProductionControl<'_>,
52    ) -> Result<
53        (
54            SharedExecutablePlan,
55            Option<crate::binding::statements::AnalyzedStatement>,
56        ),
57        SQLError,
58    > {
59        self.plan_with_cached_analysis(ordinary_plan(plan, control)?, params, cached)
60    }
61    /// Select reusable analysis before constructing mutable inputs. The preliminary owner is consumed, so its storage can retire before analysis and optimization allocate their outputs.
62    fn plan_retained_with_cached_analysis(
63        &self,
64        plan: SharedExecutablePlan,
65        params: &[SQLParam],
66        cached: Option<crate::binding::statements::AnalyzedStatement>,
67        control: &ProductionControl<'_>,
68    ) -> Result<
69        (
70            SharedExecutablePlan,
71            Option<crate::binding::statements::AnalyzedStatement>,
72        ),
73        SQLError,
74    > {
75        let mutable = plan.copy_for_rewrite(control)?;
76        drop(plan);
77        self.plan_owned_with_cached_analysis(mutable, params, cached, control)
78    }
79
80    /// Reuse analysis only after the caller validates its catalog/scope in the selected snapshot. Optimization still runs for this invocation. The default retains full analysis for implementations without this capability.
81    fn plan_with_cached_analysis(
82        &self,
83        plan: UnifiedPlan,
84        params: &[SQLParam],
85        _cached: Option<crate::binding::statements::AnalyzedStatement>,
86    ) -> Result<
87        (
88            SharedExecutablePlan,
89            Option<crate::binding::statements::AnalyzedStatement>,
90        ),
91        SQLError,
92    > {
93        self.plan_for_execution(plan, params)
94            .map(|plan| (plan, None))
95    }
96
97    /// Return an executable and whether its analysis inputs permit reuse across
98    /// ordinary messages. Planners without that evidence must analyze again.
99    fn plan_for_statement_cache(
100        &self,
101        plan: UnifiedPlan,
102        params: &[SQLParam],
103    ) -> Result<(SharedExecutablePlan, bool), SQLError> {
104        self.plan_for_execution(plan, params)
105            .map(|plan| (plan, false))
106    }
107
108    fn plan_for_execution(
109        &self,
110        plan: UnifiedPlan,
111        params: &[SQLParam],
112    ) -> Result<SharedExecutablePlan, SQLError>;
113
114    /// Analyze and optimize a logical plan, and return what its analysis derives about its result.
115    fn plan_with_result(
116        &self,
117        plan: UnifiedPlan,
118        params: &[SQLParam],
119    ) -> Result<(SharedExecutablePlan, AnalyzedResult), SQLError>;
120}
121
122/// Legacy adapters run only with their declared ordinary owner. Controlled planners must implement the consuming entry points and retain every lease in their returned executable.
123fn ordinary_plan(
124    plan: super::MutableExecutablePlan,
125    control: &ProductionControl<'_>,
126) -> Result<UnifiedPlan, SQLError> {
127    if control.budget().is_some() {
128        return Err(SQLError::Unsupported(
129            "executable planner does not implement controlled plan ownership".into(),
130        ));
131    }
132    Ok(plan.finish(control)?.into_parts().0)
133}