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