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