Skip to main content

uqa_sql/routines/
inlining.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Caller-plan expansion of selected SQL routines. Source text is analyzed for
8//! each planning attempt; declining expansion never changes the session body cache.
9
10mod arguments;
11mod operators;
12mod properties;
13mod table;
14use std::sync::Arc;
15pub use table::InlineRoutineQuery;
16#[cfg(test)]
17mod tests;
18
19use super::{
20    body_parameters::sql_body_parameter_scope,
21    body_validation::routine_parameter_values,
22    compilation::{RoutineCompilationCatalog, RoutineParserCatalog},
23    declaration::RoutineTypeCatalog,
24    result_check::{sql_function_result_layout, SQLFunctionResultKind},
25    security::{ensure_routine_execute_privilege, RoutineExecutionAuthority},
26    CompiledFunctionBody, RoutineBody, RoutineResolution,
27};
28use crate::{
29    ast::{CreateFunction, FunctionBinding, FunctionBody, FunctionReturns},
30    binding::{bind_routine_parameter_references, prepare_routine_body_inputs},
31    plan::{RelationalPlan, UnifiedPlan},
32    semantics::{sets::placement_scope::SetPlacementScope, volatility::VolatilityCatalog},
33    ColumnType, SQLError, ScalarExpr,
34};
35
36/// Metadata and analysis capabilities borrowed for one optimizer invocation.
37pub trait RoutinePlanExpressions {
38    /// Execute only an immutable call whose inputs the planner proved constant.
39    /// The existing runtime boundary retains authorization and session body caches.
40    fn evaluate_constant_routine(
41        &self,
42        expression: &ScalarExpr,
43    ) -> Result<uqa_core::Value, SQLError>;
44}
45
46#[derive(Clone, Copy)]
47pub struct RoutineInliningContext<'a> {
48    pub routines: &'a dyn RoutineResolution,
49    pub types: &'a dyn RoutineTypeCatalog,
50    pub parsers: &'a dyn RoutineParserCatalog,
51    pub catalog: &'a dyn RoutineCompilationCatalog,
52    pub relations: &'a dyn crate::binding::stored_relations::StoredRelationCatalog,
53    pub authority: &'a dyn RoutineExecutionAuthority,
54    pub volatility: &'a dyn VolatilityCatalog,
55    pub expressions: &'a dyn RoutinePlanExpressions,
56}
57
58impl std::fmt::Debug for RoutineInliningContext<'_> {
59    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
60        formatter
61            .debug_struct("RoutineInliningContext")
62            .finish_non_exhaustive()
63    }
64}
65
66/// A typed replacement, together with the routine identity whose recursive
67/// expansion the planner must suppress while simplifying the replacement.
68pub struct InlineRoutineExpression {
69    pub identity: [u8; 16],
70    pub expression: ScalarExpr,
71    pub error_context: Option<String>,
72}
73
74impl RoutineInliningContext<'_> {
75    /// Classify an analyzed/planned expression in its own row scope, including casts and selected operators.
76    pub fn expression_volatility(
77        &self,
78        expression: &ScalarExpr,
79        schema: &crate::RowSchema,
80    ) -> Result<crate::ast::FunctionVolatility, SQLError> {
81        properties::volatility(self, expression, schema)
82    }
83
84    /// Try the selected routine only; a same-named overload cannot replace it.
85    /// Argument simplification and lazy branches belong to the caller's planner.
86    pub fn prepare(
87        &self,
88        binding: &FunctionBinding,
89        arguments: &[ScalarExpr],
90        active: &[[u8; 16]],
91    ) -> Result<Option<InlineRoutineExpression>, SQLError> {
92        if binding.builtin || binding.resolution_error.is_some() {
93            return Ok(None);
94        }
95        let Some(identity) = binding.object_id else {
96            return Ok(None);
97        };
98        let Some(function) = self.selected_function(binding) else {
99            return Ok(None);
100        };
101        let Some(invocation) = binding.invocation.as_deref() else {
102            return Ok(None);
103        };
104        let specialized = super::invocation::specialized_definition(&function.def, invocation)?;
105        let definition = specialized.as_ref().unwrap_or(&function.def);
106        let arguments_for_evaluation = arguments;
107        let Some(arguments) = arguments::prepare(self, definition, invocation, arguments)? else {
108            return Ok(None);
109        };
110        if let Some(expression) =
111            self.constant_call(definition, binding, &arguments, arguments_for_evaluation)?
112        {
113            return Ok(Some(InlineRoutineExpression {
114                identity,
115                expression,
116                error_context: None,
117            }));
118        }
119        if !eligible_definition(definition) || active.contains(&identity) {
120            return Ok(None);
121        }
122        match ensure_routine_execute_privilege(self.authority, definition) {
123            Ok(()) => {}
124            Err(error) if error.sqlstate() == Some("42501") => return Ok(None),
125            Err(error) => return Err(error),
126        }
127        let error_context = super::diagnostics::sql_context(
128            definition,
129            super::diagnostics::SQLRoutineStage::Inlining,
130        );
131        let Some((mut expression, parameters)) = self
132            .analyze_body(&function, definition)
133            .map_err(|error| error.with_context(&error_context))?
134        else {
135            return Ok(None);
136        };
137        let properties = properties::inspect(self, &expression, &parameters)?;
138        if !properties.permits(definition) {
139            return Ok(None);
140        }
141        let uses = arguments::use_counts(&expression, arguments.len())?;
142        for (argument, count) in arguments.iter().zip(uses) {
143            if count == 0 && definition.strict {
144                return Ok(None);
145            }
146            if count > 1 && !properties::can_duplicate(self, argument)? {
147                return Ok(None);
148            }
149        }
150        arguments::substitute(&mut expression, &arguments);
151        Ok(Some(InlineRoutineExpression {
152            identity,
153            expression,
154            error_context: Some(error_context),
155        }))
156    }
157
158    fn constant_call(
159        &self,
160        definition: &CreateFunction,
161        binding: &FunctionBinding,
162        arguments: &[ScalarExpr],
163        arguments_for_evaluation: &[ScalarExpr],
164    ) -> Result<Option<ScalarExpr>, SQLError> {
165        if !definition.is_procedure
166            && !definition.returns_set()
167            && definition.output_params().nth(1).is_none()
168            && !super::routine_returns_anonymous_record(definition)
169        {
170            let layout = super::result_check::declared_sql_function_result(self.types, definition)?;
171            if definition.strict && arguments.iter().any(is_null_constant) {
172                return Ok(Some(ScalarExpr::TypedLiteral {
173                    collation_oid: None,
174                    composite_source: None,
175                    value: uqa_core::Value::Null,
176                    ty: layout.declared_type.catalog_name(),
177                    bound_type: Some(layout.declared_type),
178                    parameter_index: None,
179                }));
180            }
181            if definition.volatility == crate::ast::FunctionVolatility::Immutable
182                && arguments.iter().all(is_constant)
183            {
184                let call = ScalarExpr::Func {
185                    name: binding.name.clone(),
186                    binding: Some(binding.clone()),
187                    args: arguments_for_evaluation.to_vec(),
188                    distinct: false,
189                    order_by: Vec::new(),
190                    order_syntax: crate::ast::FunctionCallSyntax::Ordinary,
191                    filter: None,
192                };
193                let value = self.expressions.evaluate_constant_routine(&call)?;
194                return Ok(Some(ScalarExpr::TypedLiteral {
195                    collation_oid: None,
196                    composite_source: None,
197                    value,
198                    ty: layout.declared_type.catalog_name(),
199                    bound_type: Some(layout.declared_type),
200                    parameter_index: None,
201                }));
202            }
203        }
204        Ok(None)
205    }
206
207    fn analyze_body(
208        &self,
209        function: &super::SQLUserFunction,
210        definition: &CreateFunction,
211    ) -> Result<Option<(ScalarExpr, Vec<crate::SQLParam>)>, SQLError> {
212        let Some((plan, result, parameters)) = self.analyze_plan(function, definition)? else {
213            return Ok(None);
214        };
215        let UnifiedPlan::Query(query) = plan else {
216            return Ok(None);
217        };
218        if !query.ctes.is_empty() {
219            return Ok(None);
220        }
221        let RelationalPlan::QueryBlock(mut block) = query.root else {
222            return Ok(None);
223        };
224        if !block.is_single_expression() {
225            return Ok(None);
226        }
227        let layout = sql_function_result_layout(self.types, definition, Some(&result))?;
228        if layout.kind == SQLFunctionResultKind::Tuple {
229            return Ok(None);
230        }
231        let mut expression = block.projections.remove(0).expr;
232        let actual = result
233            .column_types()
234            .and_then(|types| types.first())
235            .and_then(Option::as_ref);
236        if layout.kind == SQLFunctionResultKind::Void && actual != Some(&ColumnType::Void) {
237            return Ok(None);
238        }
239        if actual != Some(&layout.declared_type) {
240            expression = ScalarExpr::Cast {
241                implicit: true,
242                expr: Box::new(expression),
243                ty: layout.declared_type.catalog_name(),
244            };
245        }
246        Ok(Some((expression, parameters)))
247    }
248
249    fn analyze_plan(
250        &self,
251        function: &super::SQLUserFunction,
252        definition: &CreateFunction,
253    ) -> Result<
254        Option<(
255            UnifiedPlan,
256            crate::binding::statements::AnalyzedResult,
257            Vec<crate::SQLParam>,
258        )>,
259        SQLError,
260    > {
261        let Some(mut plan) = self.body_plan(function)? else {
262            return Ok(None);
263        };
264        let parameters = routine_parameter_values(self.types, definition);
265        let names = matches!(definition.body, FunctionBody::Source(_))
266            .then(|| sql_body_parameter_scope(definition, &parameters))
267            .transpose()?;
268        let mut snapshot = self.catalog.binding_snapshot()?;
269        let namespace = self.catalog.stored_query_namespace();
270        // A function body is parsed independently of the caller's WITH names. Trigger transition relations retain their activation scope.
271        snapshot
272            .ctes
273            .retain(|name, _| namespace.transition_relations.contains(name));
274        snapshot.deferred_ctes.clear();
275        snapshot.non_returning_ctes.clear();
276        snapshot.scalar_subqueries = Arc::default();
277        let result = {
278            // A SQL-standard body is inlined as it was stored; a body compiled from source text places its set-returning calls as a new statement does.
279            let _placement = if matches!(definition.body, FunctionBody::Statements(_)) {
280                SetPlacementScope::stored_definition()
281            } else {
282                SetPlacementScope::compiled_source()
283            };
284            prepare_routine_body_inputs(
285                self.routines,
286                &mut plan,
287                &parameters,
288                &snapshot.context(),
289                self.catalog,
290                names.as_ref(),
291            )
292        }?;
293        if let Some(names) = &names {
294            bind_routine_parameter_references(
295                self.routines,
296                &mut plan,
297                &parameters,
298                &snapshot.context(),
299                names,
300            )?;
301        }
302        Ok(Some((plan, result, parameters)))
303    }
304
305    /// Expand defaults, named arguments and implicit casts before the planner
306    /// simplifies children. Returning an exact invocation prevents a second
307    /// overload selection and keeps discarded or repeated arguments typed.
308    pub fn materialize_call(
309        &self,
310        binding: &FunctionBinding,
311        arguments: &[ScalarExpr],
312    ) -> Result<Option<(FunctionBinding, Vec<ScalarExpr>)>, SQLError> {
313        let Some(function) = self.selected_function(binding) else {
314            return Ok(None);
315        };
316        let Some(invocation) = binding.invocation.as_deref() else {
317            return Ok(None);
318        };
319        let specialized = super::invocation::specialized_definition(&function.def, invocation)?;
320        let definition = specialized.as_ref().unwrap_or(&function.def);
321        let Some(mut arguments) = arguments::prepare(self, definition, invocation, arguments)?
322        else {
323            return Ok(None);
324        };
325        let mut selected = binding.clone();
326        let invocation = selected.invocation.as_mut().expect("selected invocation");
327        invocation.argument_positions = definition
328            .params
329            .iter()
330            .enumerate()
331            .filter_map(|(index, parameter)| {
332                super::body_parameters::is_sql_body_parameter(parameter).then_some(index)
333            })
334            .collect();
335        invocation.argument_targets = invocation
336            .argument_positions
337            .iter()
338            .map(|index| invocation.parameter_types[*index].clone())
339            .collect();
340        invocation.argument_sources = invocation
341            .argument_targets
342            .iter()
343            .cloned()
344            .map(Some)
345            .collect();
346        if let crate::ast::RoutineVariadicMode::Expanded { parameter_index } =
347            invocation.variadic_mode
348        {
349            invocation.variadic_mode =
350                crate::ast::RoutineVariadicMode::Explicit { parameter_index };
351        }
352        if let crate::ast::RoutineVariadicMode::Explicit { parameter_index } =
353            invocation.variadic_mode
354        {
355            let position = invocation
356                .argument_positions
357                .iter()
358                .position(|index| *index == parameter_index)
359                .ok_or_else(|| SQLError::Internal("variadic call lost its argument".into()))?;
360            let value = std::mem::replace(
361                &mut arguments[position],
362                ScalarExpr::Literal(uqa_core::Value::Null),
363            );
364            let marker =
365                FunctionBinding::dispatched(crate::ast::FunctionDispatch::VariadicArgument);
366            arguments[position] = ScalarExpr::Func {
367                name: marker.name.clone(),
368                binding: Some(marker),
369                args: vec![value],
370                distinct: false,
371                order_by: Vec::new(),
372                filter: None,
373                order_syntax: crate::ast::FunctionCallSyntax::Ordinary,
374            };
375        }
376        Ok(Some((selected, arguments)))
377    }
378
379    fn selected_function(
380        &self,
381        binding: &FunctionBinding,
382    ) -> Option<std::sync::Arc<super::SQLUserFunction>> {
383        super::selected_bound_function(self.routines, binding)
384    }
385
386    /// Ordinary messages repeat optimizer-time routine work. Prepared plans
387    /// intentionally keep their own custom/generic planning lifetime instead.
388    pub fn requires_replanning(&self, plan: &UnifiedPlan) -> bool {
389        let mut required = false;
390        plan.visit_scalar_expressions(&mut |root| {
391            root.visit(&mut |expression| {
392                let ScalarExpr::Func {
393                    binding: Some(binding),
394                    ..
395                } = expression
396                else {
397                    return;
398                };
399                if binding.builtin {
400                    return;
401                }
402                required |= self
403                    .routines
404                    .lookup_bound_sql_functions_by_binding(binding)
405                    .is_some_and(|functions| {
406                        functions.iter().any(|function| {
407                            function.def.object_id == binding.object_id
408                                && super::routine_signature_types(&function.def)
409                                    == binding.argument_types
410                                && (eligible_definition(&function.def)
411                                    || function.def.volatility
412                                        == crate::ast::FunctionVolatility::Immutable)
413                        })
414                    });
415            });
416        });
417        plan.visit_sources(&mut |source| {
418            if let crate::plan::SourcePlan::Function {
419                binding: Some(binding),
420                ..
421            } = source
422            {
423                required |= self.selected_function(binding).is_some_and(|function| {
424                    eligible_definition(&function.def)
425                        || table::eligible_definition(&function.def)
426                        || function.def.volatility == crate::ast::FunctionVolatility::Immutable
427                });
428            }
429        });
430        required
431    }
432
433    fn body_plan(
434        &self,
435        function: &super::SQLUserFunction,
436    ) -> Result<Option<UnifiedPlan>, SQLError> {
437        match &function.body {
438            RoutineBody::Bound(body) => match body.as_ref() {
439                CompiledFunctionBody::SQL(plans) if plans.len() == 1 => Ok(Some(plans[0].clone())),
440                _ => Ok(None),
441            },
442            RoutineBody::Source => {
443                let FunctionBody::Source(source) = &function.def.body else {
444                    return Err(SQLError::Internal(
445                        "source routine has no SQL source".into(),
446                    ));
447                };
448                // Parse the complete message once, then decline a multi-statement
449                // body before semantic compilation. Lexical notices still belong
450                // to every attempted expansion, as in inline_function.
451                super::compilation::with_parser_context(self.parsers, || {
452                    let statements = crate::parse_statements(source)?;
453                    let [statement] = statements.as_slice() else {
454                        return Ok(None);
455                    };
456                    Ok(Some(UnifiedPlan::lower_with(
457                        statement.compile()?,
458                        &|name: &str| self.catalog.has_registered_aggregate_function(name),
459                    )))
460                })
461            }
462        }
463    }
464}
465
466fn eligible_definition(definition: &CreateFunction) -> bool {
467    definition.language == "sql"
468        && !definition.is_procedure
469        && !definition.security.security_definer
470        && !definition.returns_set()
471        && definition.config.is_empty()
472        && definition.output_params().nth(1).is_none()
473        && !matches!(&definition.returns, FunctionReturns::Scalar { type_name }
474            if crate::type_resolution::canonical_routine_type_name(type_name) == "record")
475}
476
477fn is_constant(expression: &ScalarExpr) -> bool {
478    matches!(
479        expression,
480        ScalarExpr::Literal(_) | ScalarExpr::TypedLiteral { .. } | ScalarExpr::RetainedLiteral(_)
481    )
482}
483
484fn is_null_constant(expression: &ScalarExpr) -> bool {
485    matches!(
486        expression,
487        ScalarExpr::Literal(uqa_core::Value::Null)
488            | ScalarExpr::TypedLiteral {
489                value: uqa_core::Value::Null,
490                ..
491            }
492    )
493}