Skip to main content

uqa_engine/capabilities/
statement_planning.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Supply current catalog metadata and the configured retrieval planner to statement planning.
8use crate::Engine;
9use std::sync::Arc;
10use uqa_core::catalog_index::CatalogIndexSnapshot;
11use uqa_execution::storage_errors::storage_error;
12use uqa_planner::{
13    statement_planning::{
14        rule_inputs::{RuleInputColumns, RuleInputPlanningContext},
15        PlannerStatisticsCatalog, RetrievalSourceCosting, StatementStatisticsContext,
16        StatisticsTableState,
17    },
18    ColumnStatistics, LocalAccessEstimate,
19};
20use uqa_sql::{ast::OperatorJoinRelations, SQLError, ScalarExpr};
21
22impl uqa_sql::plan::ExecutablePlanOptimizer for Engine {
23    fn planning_control(&self) -> Result<uqa_core::memory::OwnedProductionControl, SQLError> {
24        uqa_sql::plan::ExecutablePlanOptimizer::planning_control(&self.statement_planning_context())
25    }
26    fn plan_owned_for_execution(
27        &self,
28        plan: uqa_sql::plan::MutableExecutablePlan,
29        params: &[uqa_sql::SQLParam],
30        control: &uqa_core::memory::ProductionControl<'_>,
31    ) -> Result<uqa_sql::plan::SharedExecutablePlan, SQLError> {
32        uqa_sql::plan::ExecutablePlanOptimizer::plan_owned_for_execution(
33            &self.statement_planning_context(),
34            plan,
35            params,
36            control,
37        )
38    }
39    fn plan_owned_with_result(
40        &self,
41        plan: uqa_sql::plan::MutableExecutablePlan,
42        params: &[uqa_sql::SQLParam],
43        control: &uqa_core::memory::ProductionControl<'_>,
44    ) -> Result<
45        (
46            uqa_sql::plan::SharedExecutablePlan,
47            uqa_sql::binding::statements::AnalyzedResult,
48        ),
49        SQLError,
50    > {
51        uqa_sql::plan::ExecutablePlanOptimizer::plan_owned_with_result(
52            &self.statement_planning_context(),
53            plan,
54            params,
55            control,
56        )
57    }
58    fn plan_owned_for_statement_cache(
59        &self,
60        plan: uqa_sql::plan::MutableExecutablePlan,
61        params: &[uqa_sql::SQLParam],
62        control: &uqa_core::memory::ProductionControl<'_>,
63    ) -> Result<(uqa_sql::plan::SharedExecutablePlan, bool), SQLError> {
64        uqa_sql::plan::ExecutablePlanOptimizer::plan_owned_for_statement_cache(
65            &self.statement_planning_context(),
66            plan,
67            params,
68            control,
69        )
70    }
71    fn plan_owned_with_cached_analysis(
72        &self,
73        plan: uqa_sql::plan::MutableExecutablePlan,
74        params: &[uqa_sql::SQLParam],
75        cached: Option<uqa_sql::binding::statements::AnalyzedStatement>,
76        control: &uqa_core::memory::ProductionControl<'_>,
77    ) -> Result<
78        (
79            uqa_sql::plan::SharedExecutablePlan,
80            Option<uqa_sql::binding::statements::AnalyzedStatement>,
81        ),
82        SQLError,
83    > {
84        uqa_sql::plan::ExecutablePlanOptimizer::plan_owned_with_cached_analysis(
85            &self.statement_planning_context(),
86            plan,
87            params,
88            cached,
89            control,
90        )
91    }
92    fn plan_retained_with_cached_analysis(
93        &self,
94        plan: uqa_sql::plan::SharedExecutablePlan,
95        params: &[uqa_sql::SQLParam],
96        cached: Option<uqa_sql::binding::statements::AnalyzedStatement>,
97        control: &uqa_core::memory::ProductionControl<'_>,
98    ) -> Result<
99        (
100            uqa_sql::plan::SharedExecutablePlan,
101            Option<uqa_sql::binding::statements::AnalyzedStatement>,
102        ),
103        SQLError,
104    > {
105        uqa_sql::plan::ExecutablePlanOptimizer::plan_retained_with_cached_analysis(
106            &self.statement_planning_context(),
107            plan,
108            params,
109            cached,
110            control,
111        )
112    }
113    fn plan_with_cached_analysis(
114        &self,
115        plan: uqa_sql::plan::UnifiedPlan,
116        params: &[uqa_sql::SQLParam],
117        cached: Option<uqa_sql::binding::statements::AnalyzedStatement>,
118    ) -> Result<
119        (
120            uqa_sql::plan::SharedExecutablePlan,
121            Option<uqa_sql::binding::statements::AnalyzedStatement>,
122        ),
123        SQLError,
124    > {
125        uqa_sql::plan::ExecutablePlanOptimizer::plan_with_cached_analysis(
126            &self.statement_planning_context(),
127            plan,
128            params,
129            cached,
130        )
131    }
132
133    fn plan_for_statement_cache(
134        &self,
135        plan: uqa_sql::plan::UnifiedPlan,
136        params: &[uqa_sql::SQLParam],
137    ) -> Result<(uqa_sql::plan::SharedExecutablePlan, bool), SQLError> {
138        uqa_sql::plan::ExecutablePlanOptimizer::plan_for_statement_cache(
139            &self.statement_planning_context(),
140            plan,
141            params,
142        )
143    }
144
145    fn plan_for_execution(
146        &self,
147        plan: uqa_sql::plan::UnifiedPlan,
148        params: &[uqa_sql::SQLParam],
149    ) -> Result<uqa_sql::plan::SharedExecutablePlan, SQLError> {
150        uqa_sql::plan::ExecutablePlanOptimizer::plan_for_execution(
151            &self.statement_planning_context(),
152            plan,
153            params,
154        )
155    }
156
157    fn plan_with_result(
158        &self,
159        plan: uqa_sql::plan::UnifiedPlan,
160        params: &[uqa_sql::SQLParam],
161    ) -> Result<
162        (
163            uqa_sql::plan::SharedExecutablePlan,
164            uqa_sql::binding::statements::AnalyzedResult,
165        ),
166        SQLError,
167    > {
168        uqa_sql::plan::ExecutablePlanOptimizer::plan_with_result(
169            &self.statement_planning_context(),
170            plan,
171            params,
172        )
173    }
174}
175
176impl Engine {
177    pub(crate) fn statement_statistics_context(&self) -> StatementStatisticsContext<'_> {
178        StatementStatisticsContext {
179            catalog: self,
180            volatility: self,
181            retrieval: self,
182        }
183    }
184    pub(crate) fn rule_input_planning_context(&self) -> RuleInputPlanningContext<'_> {
185        RuleInputPlanningContext {
186            rules: self,
187            views: self.view_rewrite_context(),
188            columns: self,
189            volatility: self,
190        }
191    }
192}
193impl StatisticsTableState for crate::TableState {}
194
195impl PlannerStatisticsCatalog for Engine {
196    fn storage_table(
197        &self,
198        table: &str,
199    ) -> Result<Option<Arc<dyn StatisticsTableState>>, SQLError> {
200        self.try_table(table)
201            .map(|state| state.map(|state| state as Arc<dyn StatisticsTableState>))
202            .map_err(|error| {
203                storage_error(
204                    &format!("resolve optimizer storage table `{table}`"),
205                    &error,
206                )
207            })
208    }
209    fn hierarchy_scan_tables(&self, table: &str) -> Result<Vec<String>, SQLError> {
210        self.query_hierarchy_scan_tables(table, true)
211    }
212    fn table_row_count(&self, table: &str) -> Result<u64, SQLError> {
213        self.table_row_estimate(table)
214    }
215    fn column_statistics(&self, table: &str) -> Result<ColumnStatistics, SQLError> {
216        self.try_query_column_stats(table).map_err(|error| {
217            storage_error(&format!("read optimizer statistics for `{table}`"), &error)
218        })
219    }
220    fn resolved_table_name(&self, table: &str) -> Result<Option<String>, SQLError> {
221        self.resolve_table_name(table)
222            .map_err(|error| storage_error("resolve optimizer index target", &error))
223    }
224    fn catalog_indexes(&self) -> Result<CatalogIndexSnapshot, SQLError> {
225        self.catalog_index_snapshot_in_execution()
226            .map_err(|error| storage_error("read optimizer catalog indexes", &error))
227    }
228}
229impl RetrievalSourceCosting for Engine {
230    fn operator_join_access(
231        &self,
232        name: &str,
233        relations: Option<&OperatorJoinRelations>,
234        args: &[ScalarExpr],
235    ) -> Result<LocalAccessEstimate, SQLError> {
236        crate::operator_tree_bridge::estimate_operator_join_table_function(
237            self,
238            name,
239            relations,
240            args,
241            &[],
242        )
243    }
244    fn local_access(
245        &self,
246        table: &str,
247        predicate: &ScalarExpr,
248    ) -> Result<Option<LocalAccessEstimate>, SQLError> {
249        crate::operator_tree_bridge::estimate_local_access(self, table, predicate, &[])
250    }
251}
252impl RuleInputColumns for Engine {
253    fn source_column_names(
254        &self,
255        table: &str,
256        relations_bound: bool,
257    ) -> Result<Option<Vec<String>>, SQLError> {
258        uqa_execution::catalog::projection::query_source_column_names(
259            &self.catalog_execution(),
260            table,
261            relations_bound,
262        )
263    }
264}
265
266impl Engine {
267    pub(crate) fn statement_planning_context(
268        &self,
269    ) -> uqa_planner::statement_planning::executable::StatementPlanningContext<'_> {
270        uqa_planner::statement_planning::executable::StatementPlanningContext {
271            analysis: uqa_sql::binding::statements::StatementAnalysisContext {
272                scopes: self,
273                routines: self,
274                aliases: self,
275            },
276            aggregates: self,
277            optimization: self,
278            constant_evaluator: uqa_execution::scalar::eval_constant_scalar_with_control,
279        }
280    }
281}
282impl uqa_planner::statement_planning::executable::StatementOptimizationContexts for Engine {
283    fn production_resources(
284        &self,
285    ) -> Result<Option<uqa_planner::statement_planning::executable::PlanningResources>, SQLError>
286    {
287        let control = self.query_retention_control()?;
288        Ok(Some(
289            uqa_planner::statement_planning::executable::PlanningResources::new(
290                control.memory().clone(),
291                control.cancellation().clone(),
292            ),
293        ))
294    }
295    fn constant_storage(
296        &self,
297    ) -> Result<Option<Arc<dyn uqa_sql::ir::ConstantValueStorage>>, SQLError> {
298        let bytes =
299            uqa_execution::query::runtime::QueryMemorySettings::work_mem_bytes(&*self.session)?;
300        Ok(Some(Arc::new(
301            uqa_execution::scalar::RetainedConstants::new(bytes),
302        )))
303    }
304    fn constant_storage_with_control(
305        &self,
306        control: &uqa_core::memory::ProductionControl<'_>,
307    ) -> Result<Option<Arc<dyn uqa_sql::ir::ConstantValueStorage>>, SQLError> {
308        let bytes =
309            uqa_execution::query::runtime::QueryMemorySettings::work_mem_bytes(&*self.session)?;
310        uqa_execution::scalar::RetainedConstants::shared_with_control(bytes, control).map(Some)
311    }
312    fn builtin_permissions(
313        &self,
314    ) -> Option<Arc<dyn uqa_sql::catalog::security::builtin_routines::BuiltinRoutineExecution>>
315    {
316        Some(Arc::new(uqa_execution::catalog::security::builtin_routines::execution::BuiltinRoutinePermissions::capture(&self.catalog_execution())))
317    }
318    fn statistics(&self) -> StatementStatisticsContext<'_> {
319        self.statement_statistics_context()
320    }
321
322    fn builtin_permissions_with_control(
323        &self,
324        control: &uqa_core::memory::ProductionControl<'_>,
325    ) -> Result<
326        Option<Arc<dyn uqa_sql::catalog::security::builtin_routines::BuiltinRoutineExecution>>,
327        SQLError,
328    > {
329        uqa_execution::catalog::security::builtin_routines::execution::BuiltinRoutinePermissions::shared_with_control(&self.catalog_execution(), control).map(Some)
330    }
331    fn rule_inputs(&self) -> RuleInputPlanningContext<'_> {
332        self.rule_input_planning_context()
333    }
334    fn routine_inlining(&self) -> Option<uqa_sql::routines::inlining::RoutineInliningContext<'_>> {
335        let compilation = self.routine_definition_context().compilation.analysis;
336        Some(uqa_sql::routines::inlining::RoutineInliningContext {
337            routines: compilation.routines,
338            types: compilation.types,
339            parsers: compilation.parsers,
340            catalog: compilation.catalog,
341            relations: compilation.relations,
342            authority: self,
343            volatility: self,
344            expressions: self,
345        })
346    }
347}
348
349#[cfg(test)]
350pub(crate) fn estimate_engine_plan(
351    engine: &Engine,
352    plan: &uqa_sql::plan::UnifiedPlan,
353) -> Result<uqa_planner::plan_cost::PlanCost, SQLError> {
354    uqa_planner::statement_planning::executable::estimate_plan(
355        &engine.statement_planning_context(),
356        plan,
357    )
358}
359
360pub(crate) fn optimize_engine_query(
361    engine: &Engine,
362    query: std::borrow::Cow<'_, uqa_planner::QueryPlan>,
363) -> Result<uqa_sql::plan::OwnedQueryPlan, SQLError> {
364    uqa_planner::statement_planning::executable::optimize_query(
365        &engine.statement_planning_context(),
366        query,
367    )
368}
369
370#[cfg(test)]
371pub(crate) fn optimize_engine_plan(
372    engine: &Engine,
373    plan: uqa_planner::UnifiedPlan,
374) -> Result<uqa_sql::plan::OwnedExecutablePlan, SQLError> {
375    uqa_planner::statement_planning::executable::optimize_plan(
376        &engine.statement_planning_context(),
377        plan,
378    )
379}
380
381impl uqa_sql::routines::inlining::RoutinePlanExpressions for Engine {
382    fn evaluate_constant_routine_with_control(
383        &self,
384        expression: &ScalarExpr,
385        control: &uqa_core::memory::ProductionControl<'_>,
386    ) -> Result<uqa_core::memory::Produced<uqa_core::Value>, SQLError> {
387        let scope =
388            crate::capabilities::query_scope::new_for_current_routine_with_control(self, control)?;
389        let hook = crate::capabilities::query_expressions::ScopedEngineHook::new(self, &scope);
390        uqa_execution::query::catalog_expression::evaluate_catalog_scalar_with_control(
391            expression.copy_for_rewrite(control)?,
392            &uqa_sql::ResultRow::new(),
393            &uqa_sql::RowSchema::default(),
394            &[],
395            &hook,
396            control,
397            Ok,
398        )
399    }
400
401    fn evaluate_constant_routine(
402        &self,
403        expression: &ScalarExpr,
404    ) -> Result<uqa_core::Value, SQLError> {
405        uqa_execution::query::catalog_expression::eval_scalar_plan_with_schema(
406            self,
407            crate::capabilities::query_scope::new_for_current_routine(self)?,
408            expression,
409            &uqa_sql::ResultRow::new(),
410            &uqa_sql::RowSchema::default(),
411            &[],
412        )
413    }
414}