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