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