Skip to main content

uqa_planner/optimizer/
api.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Optimizer configuration, statistics seam, and public entry points.
8
9use super::{
10    optimize_unified_plan, reorder_unified_plan_joins, AggregateClassifier, JoinGraphError,
11    RelationStats, ScalarExpr, SourcePlan, UnifiedPlan,
12};
13use crate::LocalAccessEstimate;
14
15/// Errors raised while simplifying expressions or choosing a physical join order.
16#[derive(Debug, thiserror::Error)]
17pub enum OptimizerError {
18    #[error(transparent)]
19    Expression(#[from] uqa_sql::SQLError),
20    #[error(transparent)]
21    JoinGraph(#[from] JoinGraphError),
22}
23
24pub type OptimizerResult<T> = Result<T, OptimizerError>;
25
26impl From<crate::JoinOrderError> for OptimizerError {
27    fn from(error: crate::JoinOrderError) -> Self {
28        match error {
29            crate::JoinOrderError::Graph(error) => Self::JoinGraph(error),
30            crate::JoinOrderError::Production(error) => Self::Expression(error.into()),
31        }
32    }
33}
34
35/// Evaluate a planner-proven constant under the optimizer's production allowance, retaining the result's constructor lease.
36pub type ConstantEvaluator =
37    fn(
38        &ScalarExpr,
39        &[uqa_sql::SQLParam],
40        &uqa_core::memory::ProductionControl<'_>,
41    ) -> Result<uqa_core::memory::Produced<uqa_core::Value>, uqa_sql::SQLError>;
42
43/// Plan an already analyzed scalar at its owning command's preparation boundary. This uses the same lazy conditional simplification and constant-error propagation as query planning.
44pub fn optimize_scalar_expression(
45    expression: &mut ScalarExpr,
46    config: &OptimizerConfig,
47) -> Result<(), uqa_sql::SQLError> {
48    super::optimize_scalar_slot(expression, config)
49}
50
51/// Simplify an independently owned scalar under its existing statement allowance.
52pub fn optimize_owned_scalar_expression(
53    expression: uqa_sql::plan::OwnedScalarExpr,
54    config: &OptimizerConfig<'_>,
55) -> Result<uqa_sql::plan::OwnedScalarExpr, uqa_sql::SQLError> {
56    super::scalar::owned::optimize(expression, config)
57}
58
59type ConstantStorageResult =
60    Result<Option<std::sync::Arc<dyn uqa_sql::ir::ConstantValueStorage>>, uqa_sql::SQLError>;
61
62/// Borrowed initialization is used only while optimizing a VALUES command; produced literals own their storage independently.
63#[derive(Clone, Copy)]
64pub(crate) struct ConstantStorageFactory<'a>(
65    pub &'a dyn Fn(&uqa_core::memory::ProductionControl<'_>) -> ConstantStorageResult,
66);
67
68impl std::fmt::Debug for ConstantStorageFactory<'_> {
69    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
70        f.debug_struct("ConstantStorageFactory")
71            .finish_non_exhaustive()
72    }
73}
74
75#[derive(Debug, Clone)]
76pub struct OptimizerConfig<'a> {
77    /// Allocation owner and cancellation scopes for optimizer producers.
78    pub production: uqa_core::memory::ProductionControl<'a>,
79    /// CASE/COALESCE result types and arm coercions have already been retained by the caller. Unreachable arms can be discarded without changing subsequent type inference.
80    pub coerced_conditionals: bool,
81    pub enable_filter_pushdown: bool,
82    pub enable_boolean_simplify: bool,
83    pub enable_vector_threshold_merge: bool,
84    pub enable_join_reordering: bool,
85    /// Shared scalar execution supplied by the engine composition boundary.
86    pub constant_evaluator: ConstantEvaluator,
87    /// Shared storage for immutable builtin constants produced while optimizing VALUES inputs.
88    pub constant_storage: Option<std::sync::Arc<dyn uqa_sql::ir::ConstantValueStorage>>,
89    pub(super) retain_values_constants: bool,
90    pub(crate) constant_storage_factory: Option<ConstantStorageFactory<'a>>,
91    /// Retained selected-call authority for immutable evaluation. An absent catalog has no mutable routine ACLs.
92    pub builtin_permissions: Option<
93        std::sync::Arc<dyn uqa_sql::catalog::security::builtin_routines::BuiltinRoutineExecution>,
94    >,
95    /// Selected SQL functions expanded in the caller's plan, never in stored syntax.
96    pub routine_inlining: Option<uqa_sql::routines::inlining::RoutineInliningContext<'a>>,
97    pub(super) active_inline_routines: Vec<[u8; 16]>,
98}
99
100impl OptimizerConfig<'_> {
101    pub(super) fn for_values(&self) -> Result<Self, uqa_sql::SQLError> {
102        let mut config = self.for_values_without_active()?;
103        config
104            .active_inline_routines
105            .clone_from(&self.active_inline_routines);
106        Ok(config)
107    }
108
109    pub(super) fn for_values_without_active(&self) -> Result<Self, uqa_sql::SQLError> {
110        let mut config = Self {
111            production: self.production,
112            coerced_conditionals: self.coerced_conditionals,
113            enable_filter_pushdown: self.enable_filter_pushdown,
114            enable_boolean_simplify: self.enable_boolean_simplify,
115            enable_vector_threshold_merge: self.enable_vector_threshold_merge,
116            enable_join_reordering: self.enable_join_reordering,
117            constant_evaluator: self.constant_evaluator,
118            constant_storage: self.constant_storage.clone(),
119            retain_values_constants: true,
120            constant_storage_factory: self.constant_storage_factory,
121            builtin_permissions: self.builtin_permissions.clone(),
122            routine_inlining: self.routine_inlining,
123            active_inline_routines: Vec::new(),
124        };
125        if config.constant_storage.is_none() {
126            if let Some(factory) = config.constant_storage_factory {
127                config.constant_storage = factory.0(&config.production)?;
128            }
129        }
130        Ok(config)
131    }
132
133    #[must_use]
134    pub const fn new(constant_evaluator: ConstantEvaluator) -> Self {
135        Self {
136            production: uqa_core::memory::ProductionControl::uncontrolled(),
137            coerced_conditionals: false,
138            enable_filter_pushdown: true,
139            enable_boolean_simplify: true,
140            enable_vector_threshold_merge: true,
141            enable_join_reordering: true,
142            constant_evaluator,
143            constant_storage: None,
144            retain_values_constants: false,
145            constant_storage_factory: None,
146            builtin_permissions: None,
147            routine_inlining: None,
148            active_inline_routines: Vec::new(),
149        }
150    }
151}
152
153/// Cardinality and column statistics used to cost base relations during
154/// join enumeration. Engines implement this against their live catalogue;
155/// callers without a catalogue still get deterministic DPccp enumeration
156/// from the optimizer's fallback cardinality.
157pub trait SourceStatistics {
158    fn relation_statistics(&self, table: &str) -> Option<RelationStats>;
159
160    /// Estimate a non-table source that can participate as one atom in an
161    /// inner-join region. Returning `None` keeps that region in SQL order.
162    fn source_access_estimate(&self, _source: &SourcePlan) -> Option<LocalAccessEstimate> {
163        None
164    }
165
166    /// Estimate a predicate that references only `table`. Returning `None`
167    /// delegates to the planner's scalar selectivity model.
168    fn local_access_estimate(
169        &self,
170        _table: &str,
171        _predicate: &ScalarExpr,
172    ) -> Option<LocalAccessEstimate> {
173        None
174    }
175}
176
177impl<F> SourceStatistics for F
178where
179    F: Fn(&str) -> Option<RelationStats>,
180{
181    fn relation_statistics(&self, table: &str) -> Option<RelationStats> {
182        self(table)
183    }
184}
185
186struct NoSourceStatistics;
187
188impl SourceStatistics for NoSourceStatistics {
189    fn relation_statistics(&self, _table: &str) -> Option<RelationStats> {
190        None
191    }
192}
193
194struct NoRegisteredAggregates;
195
196impl AggregateClassifier for NoRegisteredAggregates {
197    fn is_registered_aggregate(&self, _name: &str) -> bool {
198        false
199    }
200}
201
202/// Optimize a fully lowered plan using the built-in aggregate catalogue.
203pub fn optimize(
204    plan: UnifiedPlan,
205    config: &OptimizerConfig,
206) -> OptimizerResult<uqa_sql::plan::OwnedExecutablePlan> {
207    optimize_with_aggregates_and_statistics(
208        plan,
209        config,
210        &NoRegisteredAggregates,
211        &NoSourceStatistics,
212    )
213}
214
215/// Optimize a fully lowered plan while classifying engine-local aggregates.
216pub fn optimize_with_aggregates(
217    plan: UnifiedPlan,
218    config: &OptimizerConfig,
219    aggregates: &dyn AggregateClassifier,
220) -> OptimizerResult<uqa_sql::plan::OwnedExecutablePlan> {
221    optimize_with_aggregates_and_statistics(plan, config, aggregates, &NoSourceStatistics)
222}
223
224/// Optimize a fully lowered plan with caller-provided relation statistics.
225pub fn optimize_with_statistics(
226    plan: UnifiedPlan,
227    config: &OptimizerConfig,
228    statistics: &dyn SourceStatistics,
229) -> OptimizerResult<uqa_sql::plan::OwnedExecutablePlan> {
230    optimize_with_aggregates_and_statistics(plan, config, &NoRegisteredAggregates, statistics)
231}
232
233/// Optimize a fully lowered plan while classifying engine-local aggregates
234/// and costing join orders from the engine's relation statistics.
235pub fn optimize_with_aggregates_and_statistics(
236    mut plan: UnifiedPlan,
237    config: &OptimizerConfig,
238    aggregates: &dyn AggregateClassifier,
239    statistics: &dyn SourceStatistics,
240) -> OptimizerResult<uqa_sql::plan::OwnedExecutablePlan> {
241    optimize_unified_plan(&mut plan, config, aggregates)?;
242    if config.enable_join_reordering {
243        reorder_unified_plan_joins(plan, statistics, &config.production)
244    } else {
245        Ok(plan.into())
246    }
247}
248
249/// Optimize a mutable admitted plan without converting its constructor owners to ordinary storage.
250pub fn optimize_owned_with_aggregates_and_statistics(
251    plan: uqa_sql::plan::MutableExecutablePlan,
252    config: &OptimizerConfig<'_>,
253    aggregates: &dyn AggregateClassifier,
254    statistics: &dyn SourceStatistics,
255) -> OptimizerResult<uqa_sql::plan::MutableExecutablePlan> {
256    let plan = super::owned::optimize(plan, config, aggregates)?;
257    if config.enable_join_reordering {
258        super::join_reorder::reorder_owned_plan(plan, statistics, &config.production)
259    } else {
260        Ok(plan)
261    }
262}