Skip to main content

uqa_execution/routines/
sql_body.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7use std::{borrow::Cow, cell::RefCell};
8
9pub mod inputs;
10mod parameters;
11mod statements;
12
13use super::descriptions::RoutineBodyDescriptions;
14use super::transaction::DirectRoutineCommandGuard;
15use super::{CreateFunction, RoutineContext, RoutineOutcome, SQLError, SQLParam, SQLResult, Value};
16use uqa_sql::{
17    assignment::routines::coerce_routine_value_from,
18    ast::FunctionBody,
19    binding::statements::AnalyzedResult,
20    plan::{CommandPlan, UnifiedPlan},
21    plpgsql::runtime_diagnostics::result_row_values,
22    routines::{
23        body_parameters::sql_body_parameter_scope_with_control,
24        declaration::RoutineTypeCatalog,
25        resolution::RoutineOverloadContext,
26        result_check::{
27            check_sql_function_result, sql_function_result_layout, validate_sql_function_record,
28            SQLFunctionResultKind, SQLFunctionResultLayout,
29        },
30        routine_returns_anonymous_record, SQLUserFunction,
31    },
32};
33
34pub struct SQLBody<'a> {
35    pub function: &'a SQLUserFunction,
36    pub definition: &'a CreateFunction,
37    pub plans: &'a [UnifiedPlan],
38}
39
40/// `LANGUAGE sql` statements retain their first successful analysis until the
41/// routine, concrete input types, namespace or selected dependencies change.
42/// The final statement is checked before execution and shapes the routine output.
43pub fn execute_sql_language(
44    context: RoutineContext<'_>,
45    types: &dyn RoutineTypeCatalog,
46    overloads: &RoutineOverloadContext<'_>,
47    body: SQLBody<'_>,
48    bound: &[Value],
49    record_target: Option<&[uqa_sql::routines::result_check::SQLFunctionResultColumn]>,
50) -> Result<RoutineOutcome, SQLError> {
51    execute_described_sql_language(context, types, overloads, body, bound, record_target, None)
52}
53
54pub(crate) fn execute_described_sql_language(
55    context: RoutineContext<'_>,
56    types: &dyn RoutineTypeCatalog,
57    overloads: &RoutineOverloadContext<'_>,
58    body: SQLBody<'_>,
59    bound: &[Value],
60    record_target: Option<&[uqa_sql::routines::result_check::SQLFunctionResultColumn]>,
61    descriptions: Option<RoutineBodyDescriptions<'_>>,
62) -> Result<RoutineOutcome, SQLError> {
63    let SQLBody {
64        function,
65        definition: def,
66        plans,
67    } = body;
68    let resources = context.planning_resources()?;
69    let control = resources.control();
70    let params = parameters::body_parameters_with_control(
71        context.expressions,
72        def,
73        bound,
74        descriptions,
75        &control,
76    )?;
77    if plans.is_empty() {
78        check_sql_function_result(types, def, None)?;
79    }
80    let layout = RefCell::new(None);
81    let check_result = |result: &AnalyzedResult| {
82        *layout.borrow_mut() = Some(checked_body_result_layout(
83            types,
84            def,
85            result,
86            record_target,
87            descriptions,
88        )?);
89        Ok(())
90    };
91    let parameters = matches!(def.body, FunctionBody::Source(_))
92        .then(|| sql_body_parameter_scope_with_control(def, &params, &control))
93        .transpose()?;
94    let identity = inputs::SQLBodyIdentity::new(function)?;
95    let mut parameter_types = uqa_core::memory::ProductionVec::new(control);
96    parameter_types.reserve(params.len())?;
97    for parameter in params.iter() {
98        let ty = parameter
99            .declared_scalar_type()
100            .ok_or_else(|| SQLError::Internal("SQL body parameter has no concrete type".into()))?;
101        parameter_types.push_produced(ty.clone_with_control(&control)?)?;
102    }
103    let parameter_types = parameter_types.finish()?;
104    let statements = statements::SQLStatements {
105        control,
106        context,
107        types,
108        overloads,
109        params: &params,
110        parameters,
111        identity,
112        parameter_types: &parameter_types,
113        inputs: context.statements.body_input_context(),
114    };
115    let mut last = SQLResult::empty();
116    for (position, plan) in plans.iter().enumerate() {
117        control.check()?;
118        let check = (position + 1 == plans.len())
119            .then_some(&check_result as super::context::StatementResultCheck<'_>);
120        let frame = || {
121            uqa_sql::routines::diagnostics::sql_context(
122                def,
123                uqa_sql::routines::diagnostics::SQLRoutineStage::Statement(position + 1),
124            )
125        };
126        let statement = statements
127            .prepare(plan, position, check)
128            .map_err(|error| def.source_body_error(error).with_context(frame()))?;
129        let _direct_routine_command = matches!(
130            statement.plan(),
131            UnifiedPlan::Command(command)
132                if matches!(
133                    command.as_ref(),
134                    CommandPlan::Call { .. } | CommandPlan::DoBlock { .. }
135                )
136        )
137        .then(|| DirectRoutineCommandGuard::enter(context.session));
138        last = statement
139            .execute(context, &params, check)
140            .map_err(|error| def.source_body_error(error).with_context(frame()))?;
141    }
142    let layout = layout.into_inner().map_or_else(
143        || sql_function_result_layout(types, def, None).map(Cow::Owned),
144        Ok,
145    )?;
146    shape_result(
147        context.expressions,
148        types,
149        def,
150        &last,
151        &layout,
152        descriptions,
153    )
154    .map_err(|error| {
155        error.with_context(uqa_sql::routines::diagnostics::sql_context(
156            def,
157            uqa_sql::routines::diagnostics::SQLRoutineStage::Statement(plans.len()),
158        ))
159    })
160}
161
162fn checked_body_result_layout<'a>(
163    types: &dyn RoutineTypeCatalog,
164    definition: &CreateFunction,
165    result: &AnalyzedResult,
166    record_target: Option<&[uqa_sql::routines::result_check::SQLFunctionResultColumn]>,
167    descriptions: Option<RoutineBodyDescriptions<'a>>,
168) -> Result<Cow<'a, SQLFunctionResultLayout>, SQLError> {
169    let layout = match descriptions {
170        Some(saved) => saved.description.body_result_layout(
171            types,
172            definition,
173            Some(result),
174            saved.environment,
175        )?,
176        None => Cow::Owned(sql_function_result_layout(types, definition, Some(result))?),
177    };
178    if layout.kind == SQLFunctionResultKind::Tuple && routine_returns_anonymous_record(definition) {
179        if let Some(target) = record_target {
180            uqa_sql::routines::result_check::validate_anonymous_record_result(
181                types,
182                result.column_types().unwrap_or_default(),
183                target,
184                Some(SQLFunctionResultKind::Tuple),
185            )?;
186        }
187    }
188    Ok(layout)
189}
190
191#[cfg(test)]
192fn body_parameters(
193    expressions: &dyn uqa_sql::assignment::routines::RoutineValueContext,
194    def: &CreateFunction,
195    bound: &[Value],
196    descriptions: Option<RoutineBodyDescriptions<'_>>,
197) -> Result<Vec<SQLParam>, SQLError> {
198    parameters::body_parameters_with_control(
199        expressions,
200        def,
201        bound,
202        descriptions,
203        &uqa_core::memory::ProductionControl::uncontrolled(),
204    )
205    .map(|parameters| {
206        parameters
207            .into_uncontrolled()
208            .expect("ordinary SQL-body parameters")
209    })
210}
211
212fn shape_result(
213    expressions: &dyn uqa_sql::assignment::routines::RoutineValueContext,
214    types: &dyn RoutineTypeCatalog,
215    def: &CreateFunction,
216    last: &SQLResult,
217    layout: &SQLFunctionResultLayout,
218    descriptions: Option<RoutineBodyDescriptions<'_>>,
219) -> Result<RoutineOutcome, SQLError> {
220    let output_count = def.output_arity();
221    let anonymous = routine_returns_anonymous_record(def);
222    let record_types = anonymous
223        .then(|| {
224            if layout.kind == SQLFunctionResultKind::Value {
225                layout.source_record.clone()
226            } else {
227                Some(last.column_types.clone())
228            }
229        })
230        .flatten();
231    let shape = |values| result_value(expressions, types, layout, last, values, descriptions);
232    if def.returns_set() {
233        if layout.kind == SQLFunctionResultKind::Value {
234            uqa_sql::routines::result_check::validate_sql_function_record_rows(last)?;
235        }
236        let mut rows = Vec::with_capacity(last.rows.len());
237        for index in 0..last.rows.len() {
238            let value = shape(result_row_values(last, index).unwrap_or_default())?;
239            rows.push(output_values(def, value, output_count, Some(expressions))?);
240        }
241        return Ok(RoutineOutcome {
242            value: Value::Null,
243            out_values: vec![Value::Null; output_count],
244            set_rows: rows,
245            anonymous_record_column_types: record_types,
246            sql_result_kind: Some(layout.kind),
247        });
248    }
249    let value = result_row_values(last, 0)
250        .map(shape)
251        .transpose()?
252        .unwrap_or(Value::Null);
253    let (value, out_values) = if output_count == 0 {
254        (value, Vec::new())
255    } else {
256        (
257            Value::Null,
258            output_values(def, value, output_count, Some(expressions))?,
259        )
260    };
261    Ok(RoutineOutcome {
262        value,
263        out_values,
264        set_rows: Vec::new(),
265        anonymous_record_column_types: record_types,
266        sql_result_kind: Some(layout.kind),
267    })
268}
269
270fn result_value(
271    expressions: &dyn uqa_sql::assignment::routines::RoutineValueContext,
272    types: &dyn RoutineTypeCatalog,
273    layout: &SQLFunctionResultLayout,
274    last: &SQLResult,
275    mut values: Vec<Value>,
276    descriptions: Option<RoutineBodyDescriptions<'_>>,
277) -> Result<Value, SQLError> {
278    match layout.kind {
279        SQLFunctionResultKind::Void => Ok(Value::Null),
280        SQLFunctionResultKind::Value => {
281            let value = values.pop().unwrap_or(Value::Null);
282            if layout.declared_type == uqa_sql::ColumnType::Record {
283                if let Some(expected) = &layout.columns {
284                    if !matches!(value, Value::Null) {
285                        let target = expected
286                            .iter()
287                            .map(|column| column.ty.clone())
288                            .collect::<Vec<_>>();
289                        if let Value::Row(row) = &value {
290                            if let Some(source) = row.field_types() {
291                                uqa_sql::routines::result_check::validate_sql_function_record_identity(types, source, &target)?;
292                            } else if let Some(source) = &layout.source_record {
293                                validate_sql_function_record(types, source, &target)?;
294                            }
295                        } else if let Some(source) = &layout.source_record {
296                            validate_sql_function_record(types, source, &target)?;
297                        }
298                    }
299                    let fields = row_fields(value, expected.len(), Some(expressions))?;
300                    return Ok(Value::Record(
301                        expected
302                            .iter()
303                            .map(|column| column.name.clone())
304                            .zip(fields)
305                            .collect::<Vec<_>>()
306                            .into(),
307                    ));
308                }
309            }
310            let source = last.column_types.first().and_then(Option::as_ref);
311            match descriptions {
312                Some(saved) => saved.description.coerce_body_result(
313                    layout,
314                    0,
315                    &value,
316                    source,
317                    saved.environment,
318                ),
319                None => coerce_routine_value_from(
320                    expressions,
321                    &value,
322                    &layout.declared_type.catalog_name(),
323                    source,
324                ),
325            }
326        }
327        SQLFunctionResultKind::Tuple => {
328            let columns = if let Some(expected) = &layout.columns {
329                for (index, (value, column)) in values.iter_mut().zip(expected).enumerate() {
330                    let source = last.column_types.get(index).and_then(Option::as_ref);
331                    *value = match descriptions {
332                        Some(saved) => saved.description.coerce_body_result(
333                            layout,
334                            index,
335                            value,
336                            source,
337                            saved.environment,
338                        ),
339                        None => coerce_routine_value_from(
340                            expressions,
341                            value,
342                            &column.ty.catalog_name(),
343                            source,
344                        ),
345                    }?;
346                }
347                expected
348                    .iter()
349                    .map(|column| column.name.clone())
350                    .collect::<Vec<_>>()
351            } else {
352                last.columns.clone()
353            };
354            Ok(Value::Record(
355                columns.into_iter().zip(values).collect::<Vec<_>>().into(),
356            ))
357        }
358    }
359}
360
361/// A single composite OUT parameter is a value for a function, but remains one independently assigned output column for a procedure.
362fn output_values(
363    def: &CreateFunction,
364    value: Value,
365    output_count: usize,
366    engine: Option<&dyn uqa_sql::expr::EngineHook>,
367) -> Result<Vec<Value>, SQLError> {
368    if output_count == 0 || (output_count == 1 && !def.is_procedure) {
369        Ok(vec![value])
370    } else {
371        row_fields(value, output_count, engine)
372    }
373}
374
375pub(super) fn row_fields(
376    value: Value,
377    expected: usize,
378    engine: Option<&dyn uqa_sql::expr::EngineHook>,
379) -> Result<Vec<Value>, SQLError> {
380    let value = match value {
381        Value::Datum(datum) => uqa_sql::expr::datums::read_with_catalog(&datum, engine)?,
382        value => value,
383    };
384    let fields = match value {
385        Value::Record(fields) => fields.into_values(),
386        Value::Row(fields) => fields.into_values(),
387        Value::Null => return Ok(vec![Value::Null; expected]),
388        _ => {
389            return Err(SQLError::Internal(
390                "a SQL routine row result contained a scalar value".into(),
391            ));
392        }
393    };
394    if fields.len() == expected {
395        Ok(fields)
396    } else {
397        Err(SQLError::Diagnostic {
398            sqlstate: "42804".into(),
399            message: "function return row and query-specified return row do not match".into(),
400            detail: Some(format!(
401                "Returned row contains {} attribute{}, but query expects {expected}.",
402                fields.len(),
403                if fields.len() == 1 { "" } else { "s" }
404            )),
405            hint: None,
406        })
407    }
408}
409
410#[cfg(test)]
411mod tests;