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