Skip to main content

uqa_sql/semantics/table_functions/
column_definitions.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Column definition lists of functions in FROM, checked against the class of each function's result.
8
9use crate::ast::{
10    ColumnType, FunctionBinding, FunctionParamMode, FunctionReturns, RoutineInvocationBinding,
11};
12use crate::routines::{routine_returns_anonymous_record, RoutineResolution, SQLUserFunction};
13use crate::type_resolution::FunctionTypeResolver;
14use crate::{RowSchema, SQLError, SQLParam, ScalarExpr};
15
16/// The marker a column definition list keeps for a column declared SETOF.
17pub const SETOF_COLUMN_DEFINITION_PREFIX: &str = "setof ";
18
19/// `PostgreSQL` limits a column definition list to `MaxHeapAttributeNumber` columns.
20const MAX_COLUMN_DEFINITIONS: usize = 1600;
21
22/// A function in FROM with the column definition list written for it.
23pub struct ColumnDefinitionRequest<'a> {
24    pub name: &'a str,
25    pub binding: Option<&'a FunctionBinding>,
26    pub user_function: Option<&'a SQLUserFunction>,
27    /// The concrete types the call selected for a user function, which give a polymorphic result its actual type.
28    pub user_invocation: Option<&'a RoutineInvocationBinding>,
29    pub args: &'a [ScalarExpr],
30    pub declared_types: &'a [String],
31    pub column_names: &'a [String],
32}
33
34/// The class of a FROM function's result, which decides whether a column definition list describes it, as `get_expr_result_type` classifies it.
35#[derive(Clone, Copy, PartialEq, Eq)]
36pub(super) enum ResultClass {
37    /// An anonymous record, which only a column definition list describes.
38    Record,
39    /// A record that OUT parameters describe.
40    OutParameters,
41    NamedComposite,
42    Scalar,
43    /// A UQA extension or host-registered table function, whose result the catalog does not classify.
44    Unclassified,
45}
46
47/// Check the column definition list of a function in FROM against the class of its result, as `addRangeTableEntryForFunction` does.
48pub fn validate_table_function_column_definition(
49    routines: &dyn RoutineResolution,
50    request: ColumnDefinitionRequest<'_>,
51    input_schema: &RowSchema,
52    params: &[SQLParam],
53    resolver: &dyn FunctionTypeResolver,
54) -> Result<(), SQLError> {
55    let class = match request.user_function {
56        Some(function) => user_function_result_class(routines, function, request.user_invocation)?,
57        None if request.binding.is_some_and(|binding| !binding.builtin) => {
58            ResultClass::Unclassified
59        }
60        None => builtin_result_class(&request, input_schema, params, resolver),
61    };
62    let syntax_error = |message: &str| SQLError::Routine {
63        sqlstate: "42601".into(),
64        message: message.into(),
65    };
66    if request.declared_types.is_empty() {
67        return if class == ResultClass::Record {
68            Err(syntax_error(
69                "a column definition list is required for functions returning \"record\"",
70            ))
71        } else {
72            Ok(())
73        };
74    }
75    match class {
76        ResultClass::Record => validate_record_column_definitions(routines, &request),
77        ResultClass::OutParameters => Err(redundant_out_column_definition_error()),
78        ResultClass::NamedComposite => Err(syntax_error(
79            "a column definition list is redundant for a function returning a named composite type",
80        )),
81        ResultClass::Scalar => Err(syntax_error(
82            "a column definition list is only allowed for functions returning \"record\"",
83        )),
84        ResultClass::Unclassified => Ok(()),
85    }
86}
87
88/// A column definition list describes an anonymous record with at most `MaxHeapAttributeNumber` ordinary columns.
89fn validate_record_column_definitions(
90    routines: &dyn RoutineResolution,
91    request: &ColumnDefinitionRequest<'_>,
92) -> Result<(), SQLError> {
93    if request.declared_types.len() > MAX_COLUMN_DEFINITIONS {
94        return Err(SQLError::Routine {
95            sqlstate: "54011".into(),
96            message: format!(
97                "column definition lists can have at most {MAX_COLUMN_DEFINITIONS} entries"
98            ),
99        });
100    }
101    let mut pseudo_types = Vec::new();
102    for (position, declared) in request.declared_types.iter().enumerate() {
103        let column = request
104            .column_names
105            .get(position)
106            .map_or("", String::as_str);
107        if declared.starts_with(SETOF_COLUMN_DEFINITION_PREFIX) {
108            return Err(SQLError::Routine {
109                sqlstate: "42P16".into(),
110                message: format!("column \"{column}\" cannot be declared SETOF"),
111            });
112        }
113        let pseudo = crate::catalog::type_metadata::routine_pseudo_type_name(
114            crate::catalog::type_metadata::routine_type_oid(declared),
115        );
116        if pseudo.is_none() {
117            let ty = routines.resolve_type_name(declared)?.map_or_else(
118                || {
119                    ColumnType::from_sql_name(declared).map_err(|_| SQLError::Routine {
120                        sqlstate: "42704".into(),
121                        message: format!("type \"{declared}\" does not exist"),
122                    })
123                },
124                Ok,
125            )?;
126            routines.require_type_usage(&ty)?;
127        }
128        pseudo_types.push(pseudo);
129    }
130    let mut names = std::collections::BTreeSet::new();
131    for name in request.column_names {
132        if !names.insert(name) {
133            return Err(SQLError::Routine {
134                sqlstate: "42701".into(),
135                message: format!("column name \"{name}\" specified more than once"),
136            });
137        }
138    }
139    for (column, pseudo) in request.column_names.iter().zip(pseudo_types) {
140        // Function result descriptions may contain anonymous records, unlike stored table rows.
141        if let Some(pseudo) = pseudo.filter(|pseudo| *pseudo != "record") {
142            return Err(SQLError::Routine {
143                sqlstate: "42P16".into(),
144                message: format!("column \"{column}\" has pseudo-type {pseudo}"),
145            });
146        }
147    }
148    Ok(())
149}
150
151/// The class of a user function's result for one call; a polymorphic result takes the type the call resolved for it, as `get_expr_result_type` resolves it from the actual arguments.
152pub(super) fn user_function_result_class(
153    routines: &dyn RoutineResolution,
154    function: &SQLUserFunction,
155    invocation: Option<&RoutineInvocationBinding>,
156) -> Result<ResultClass, SQLError> {
157    if routine_returns_anonymous_record(&function.def) {
158        return Ok(ResultClass::Record);
159    }
160    if function.def.output_params().nth(1).is_some() {
161        return Ok(ResultClass::OutParameters);
162    }
163    // A single OUT parameter, such as the one column of RETURNS TABLE, gives the result its type.
164    let output = function
165        .def
166        .params
167        .iter()
168        .enumerate()
169        .find(|(_, parameter)| {
170            matches!(
171                parameter.mode,
172                FunctionParamMode::Out | FunctionParamMode::InOut | FunctionParamMode::Table
173            )
174        });
175    let (declared, concrete) = match (output, &function.def.returns) {
176        (Some((position, output)), _) => (
177            output.type_name.as_str(),
178            invocation
179                .and_then(|invocation| invocation.parameter_types.get(position))
180                .map(String::as_str),
181        ),
182        (None, FunctionReturns::Scalar { type_name } | FunctionReturns::SetOf { type_name }) => (
183            type_name.as_str(),
184            invocation.and_then(|invocation| invocation.return_type.as_deref()),
185        ),
186        _ => return Ok(ResultClass::Scalar),
187    };
188    let type_name = concrete.unwrap_or(declared);
189    if crate::type_resolution::routine_polymorphic_type(type_name).is_some() {
190        return Ok(ResultClass::Unclassified);
191    }
192    Ok(match routines.resolve_type_name(type_name)? {
193        Some(ty) => type_result_class(&ty),
194        None => ResultClass::Scalar,
195    })
196}
197
198fn builtin_result_class(
199    request: &ColumnDefinitionRequest<'_>,
200    input_schema: &RowSchema,
201    params: &[SQLParam],
202    resolver: &dyn FunctionTypeResolver,
203) -> ResultClass {
204    let builtin = crate::semantics::builtin_function_dispatch_name(request.name);
205    match builtin.as_ref() {
206        "json_each"
207        | "jsonb_each"
208        | "json_each_text"
209        | "jsonb_each_text"
210        | "pg_get_sequence_data"
211        | "pg_sequence_parameters"
212        | "aclexplode" => ResultClass::OutParameters,
213        "generate_series"
214        | "pg_listening_channels"
215        | "regexp_matches"
216        | "regexp_split_to_table"
217        | "string_to_table"
218        | "json_array_elements"
219        | "jsonb_array_elements"
220        | "json_array_elements_text"
221        | "jsonb_array_elements_text"
222        | "json_object_keys"
223        | "jsonb_object_keys" => ResultClass::Scalar,
224        // `unnest` returns its array's element type; an array of anonymous records produces one record column, which this check leaves unclassified.
225        "unnest" => match request.args {
226            [argument] => {
227                crate::scalar_type_with_resolver(argument, input_schema, params, resolver)
228                    .ok()
229                    .flatten()
230                    .and_then(|ty| crate::type_resolution::array_element_type(&ty).cloned())
231                    .map_or(
232                        ResultClass::Unclassified,
233                        |element| match type_result_class(&element) {
234                            ResultClass::Record => ResultClass::Unclassified,
235                            class => class,
236                        },
237                    )
238            }
239            _ => ResultClass::Unclassified,
240        },
241        _ => ResultClass::Unclassified,
242    }
243}
244
245/// The class of a result of type `ty`; a domain takes its base type's class, as a domain over a composite type does.
246fn type_result_class(ty: &ColumnType) -> ResultClass {
247    match ty {
248        ColumnType::Domain { base, .. } => type_result_class(base),
249        ColumnType::Composite(_) => ResultClass::NamedComposite,
250        ColumnType::Record => ResultClass::Record,
251        _ => ResultClass::Scalar,
252    }
253}
254
255fn redundant_out_column_definition_error() -> SQLError {
256    SQLError::Routine {
257        sqlstate: "42601".into(),
258        message: "a column definition list is redundant for a function with OUT parameters".into(),
259    }
260}