Skip to main content

uqa_sql/semantics/
table_functions.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Table-function binding, declared result types, and source aliases.
8
9use crate::ast::{
10    ColumnType, FunctionBinding, FunctionParamMode, FunctionReturns, RoutineInvocationBinding,
11};
12use crate::routines::{RoutineResolution, SQLUserFunction};
13use crate::type_resolution::{BuiltinFunctionOverload, FunctionTypeResolver};
14use crate::{RowSchema, SQLError, SQLParam, ScalarExpr};
15use std::sync::Arc;
16
17mod columns;
18pub use columns::table_function_empty_schema_with_control;
19mod production;
20mod selection;
21mod types;
22pub use production::{
23    apply_table_function_aliases_with_control, user_function_composite_result_with_control,
24    user_function_declared_columns_with_control, user_function_output_columns_with_control,
25    user_table_function_columns_with_control, validate_table_function_alias_count_with_control,
26};
27pub(crate) use selection::resolve_table_function_binding_for_types_with_control;
28pub use types::table_function_column_types_with_control;
29
30mod column_definitions;
31pub use column_definitions::{
32    validate_table_function_column_definition,
33    validate_table_function_column_definition_with_control, ColumnDefinitionRequest,
34    SETOF_COLUMN_DEFINITION_PREFIX,
35};
36
37pub struct ResolvedUserTableFunction {
38    pub function: Arc<SQLUserFunction>,
39    pub binding: FunctionBinding,
40}
41
42/// Correct the old integer series declaration, which recorded a nonexistent default on the three-argument overload. This only accepts the exact builtin catalog shape; it never resolves a persisted call by its display name.
43pub(crate) fn upgrade_legacy_table_function_binding(
44    binding: &mut Option<FunctionBinding>,
45    argument_count: usize,
46) -> bool {
47    let Some(binding) = binding else {
48        return false;
49    };
50    if argument_count != 2
51        || !binding.builtin
52        || binding.object_id.is_some()
53        || binding.name != "pg_catalog.generate_series"
54        || binding.dispatch.is_some()
55        || binding.invocation.is_some()
56        || binding.resolution_error.is_some()
57    {
58        return false;
59    }
60    let [first, second, third] = binding.argument_types.as_slice() else {
61        return false;
62    };
63    if !matches!(first.as_str(), "integer" | "bigint") || first != second || first != third {
64        return false;
65    }
66    binding.argument_types.truncate(2);
67    true
68}
69
70pub fn user_function_output_columns_for(function: &SQLUserFunction) -> Option<Vec<String>> {
71    user_function_output_columns_with_control(
72        function,
73        &uqa_core::memory::ProductionControl::uncontrolled(),
74    )
75    .expect("ordinary function output columns")
76    .map(|columns| columns.into_uncontrolled().expect("ordinary output names"))
77}
78
79/// A named composite returned by a function expands to its live attributes in FROM, including a single composite OUT parameter.
80pub fn user_function_composite_result(
81    routines: &dyn RoutineResolution,
82    function: &SQLUserFunction,
83    invocation: Option<&RoutineInvocationBinding>,
84) -> Result<Option<Arc<crate::expr::composites::CompositeTypeDescriptor>>, SQLError> {
85    production::composite_result_oid_with_control(
86        routines,
87        function,
88        invocation,
89        &uqa_core::memory::ProductionControl::uncontrolled(),
90    )?
91    .map(|oid| crate::expr::composites::descriptor(routines.composite_types(), oid))
92    .transpose()
93}
94
95/// The columns a user function in FROM declares, before column aliases: a named composite result's attributes, including those of a single composite OUT parameter, or else the OUT parameters. `None` for a function with neither, whose single column the FROM item names.
96pub fn user_function_declared_columns(
97    routines: &dyn RoutineResolution,
98    function: &SQLUserFunction,
99    invocation: Option<&RoutineInvocationBinding>,
100) -> Result<Option<Vec<String>>, SQLError> {
101    user_function_declared_columns_with_control(
102        routines,
103        function,
104        invocation,
105        &uqa_core::memory::ProductionControl::uncontrolled(),
106    )
107    .map(|columns| {
108        columns.map(|columns| {
109            columns
110                .into_uncontrolled()
111                .expect("ordinary declared column names")
112        })
113    })
114}
115
116/// Derive a user FROM function's width from its result type before applying aliases. Only an anonymous record takes its shape from the column definition list; aliases never add fields to a scalar result.
117pub fn user_table_function_columns(
118    routines: &dyn RoutineResolution,
119    function: &SQLUserFunction,
120    invocation: Option<&RoutineInvocationBinding>,
121    output_name: &str,
122    alias: Option<&str>,
123    column_aliases: &[String],
124    ordinality: bool,
125) -> Result<Vec<String>, SQLError> {
126    user_table_function_columns_with_control(
127        routines,
128        function,
129        invocation,
130        output_name,
131        alias,
132        column_aliases,
133        ordinality,
134        &uqa_core::memory::ProductionControl::uncontrolled(),
135    )
136    .map(|columns| {
137        columns
138            .into_uncontrolled()
139            .expect("ordinary table function names")
140    })
141}
142
143pub fn resolve_user_table_function(
144    routines: &dyn RoutineResolution,
145    name: &str,
146    binding: Option<&FunctionBinding>,
147    args: &[ScalarExpr],
148    input_schema: &RowSchema,
149    params: &[SQLParam],
150    resolver: &dyn FunctionTypeResolver,
151) -> Result<Option<ResolvedUserTableFunction>, SQLError> {
152    resolve_user_table_function_with_control(
153        TableFunctionAnalysis {
154            routines,
155            types: resolver,
156        },
157        name,
158        binding,
159        args,
160        input_schema,
161        params,
162        &uqa_core::memory::ProductionControl::uncontrolled(),
163    )?
164    .map(|resolved| {
165        Ok(ResolvedUserTableFunction {
166            function: resolved.function,
167            binding: resolved
168                .binding
169                .into_uncontrolled()
170                .expect("ordinary table binding"),
171        })
172    })
173    .transpose()
174}
175
176pub struct ControlledUserTableFunction {
177    pub function: Arc<SQLUserFunction>,
178    pub binding: uqa_core::memory::Produced<FunctionBinding>,
179}
180
181pub fn resolve_user_table_function_with_control(
182    context: TableFunctionAnalysis<'_>,
183    name: &str,
184    binding: Option<&FunctionBinding>,
185    args: &[ScalarExpr],
186    input: &RowSchema,
187    params: &[SQLParam],
188    control: &uqa_core::memory::ProductionControl<'_>,
189) -> Result<Option<ControlledUserTableFunction>, SQLError> {
190    let Some(binding) = resolve_table_function_binding_with_control(
191        TableFunctionAnalysis { ..context },
192        name,
193        binding,
194        args,
195        input,
196        params,
197        control,
198    )?
199    else {
200        return Ok(None);
201    };
202    if binding.builtin {
203        return Ok(None);
204    }
205    let signature = crate::function_call_argument_signature_with_control(
206        args,
207        input,
208        params,
209        Some(context.types),
210        control,
211    )?;
212    let (argument_names, argument_types, explicit_variadic) = &*signature;
213    let Some(matched) = context
214        .routines
215        .resolve_static_sql_function_match_with_control(
216            name,
217            Some(&binding),
218            crate::type_resolution::RoutineCallDescriptor {
219                argument_names,
220                argument_types,
221                explicit_variadic: *explicit_variadic,
222            },
223            control,
224        )?
225    else {
226        return Ok(None);
227    };
228    let binding = crate::routines::resolution::selected_binding(
229        &matched.function,
230        matched.invocation,
231        control,
232    )?;
233    Ok(Some(ControlledUserTableFunction {
234        function: matched.function,
235        binding,
236    }))
237}
238
239pub struct TableFunctionAnalysis<'a> {
240    pub routines: &'a dyn RoutineResolution,
241    pub types: &'a dyn FunctionTypeResolver,
242}
243
244pub fn resolve_table_function_binding(
245    routines: &dyn RoutineResolution,
246    name: &str,
247    binding: Option<&FunctionBinding>,
248    args: &[ScalarExpr],
249    input_schema: &RowSchema,
250    params: &[SQLParam],
251    resolver: &dyn FunctionTypeResolver,
252) -> Result<Option<FunctionBinding>, SQLError> {
253    Ok(resolve_table_function_binding_with_control(
254        TableFunctionAnalysis {
255            routines,
256            types: resolver,
257        },
258        name,
259        binding,
260        args,
261        input_schema,
262        params,
263        &uqa_core::memory::ProductionControl::uncontrolled(),
264    )?
265    .map(|binding| binding.into_uncontrolled().expect("ordinary table binding")))
266}
267
268pub fn resolve_table_function_binding_with_control(
269    context: TableFunctionAnalysis<'_>,
270    name: &str,
271    binding: Option<&FunctionBinding>,
272    args: &[ScalarExpr],
273    input_schema: &RowSchema,
274    params: &[SQLParam],
275    control: &uqa_core::memory::ProductionControl<'_>,
276) -> Result<Option<uqa_core::memory::Produced<FunctionBinding>>, SQLError> {
277    control.check()?;
278    if let Some(binding) = binding {
279        return Ok(Some(binding.clone_with_control(control)?));
280    }
281    let signature = crate::function_call_argument_signature_with_control(
282        args,
283        input_schema,
284        params,
285        Some(context.types),
286        control,
287    )?;
288    let (argument_names, argument_types, explicit_variadic) = &*signature;
289    if crate::type_resolution::function_arguments_have_runtime_types_with_control(
290        args,
291        argument_types,
292        control,
293    )? {
294        return Ok(None);
295    }
296    resolve_table_function_binding_for_types_with_control(
297        context.routines,
298        name,
299        binding,
300        crate::type_resolution::RoutineCallDescriptor {
301            argument_names,
302            argument_types,
303            explicit_variadic: *explicit_variadic,
304        },
305        control,
306    )
307}
308
309/// Select a call whose dynamic inputs have now produced values, preserving every statically declared argument type and the original SQL unknown-literal rules.
310pub fn resolve_runtime_table_function_binding(
311    routines: &dyn RoutineResolution,
312    name: &str,
313    args: &[ScalarExpr],
314    values: &[(Option<String>, uqa_core::Value)],
315    input_schema: &RowSchema,
316    params: &[SQLParam],
317    resolver: &dyn FunctionTypeResolver,
318) -> Result<Option<FunctionBinding>, SQLError> {
319    let (argument_names, mut argument_types, explicit_variadic) =
320        crate::function_call_argument_signature(args, input_schema, params, Some(resolver))?;
321    let arguments = crate::scalar_call_arguments(args)?;
322    assert_eq!(arguments.len(), values.len());
323    for ((argument, ty), (_, value)) in arguments.iter().zip(&mut argument_types).zip(values) {
324        if crate::type_resolution::runtime_input(argument.value, ty.as_ref()) {
325            *ty = crate::type_resolution::value_type(value);
326        }
327    }
328    resolve_table_function_binding_for_types(
329        routines,
330        name,
331        None,
332        crate::type_resolution::RoutineCallDescriptor {
333            argument_names: &argument_names,
334            argument_types: &argument_types,
335            explicit_variadic,
336        },
337    )
338}
339
340/// Select a FROM call from arguments already analyzed in their owning scalar-subquery scope.
341pub(crate) fn resolve_table_function_binding_for_types(
342    routines: &dyn RoutineResolution,
343    name: &str,
344    binding: Option<&FunctionBinding>,
345    call: crate::type_resolution::RoutineCallDescriptor<'_>,
346) -> Result<Option<FunctionBinding>, SQLError> {
347    Ok(resolve_table_function_binding_for_types_with_control(
348        routines,
349        name,
350        binding,
351        call,
352        &uqa_core::memory::ProductionControl::uncontrolled(),
353    )?
354    .map(|binding| binding.into_uncontrolled().expect("ordinary table binding")))
355}
356
357fn has_builtin_table_function_overloads(name: &str) -> bool {
358    matches!(
359        name,
360        "generate_series"
361            | "pg_listening_channels"
362            | "unnest"
363            | "regexp_matches"
364            | "regexp_split_to_table"
365            | "string_to_table"
366            | "json_array_elements"
367            | "jsonb_array_elements"
368            | "json_array_elements_text"
369            | "jsonb_array_elements_text"
370            | "json_object_keys"
371            | "jsonb_object_keys"
372            | "json_each"
373            | "jsonb_each"
374            | "json_each_text"
375            | "jsonb_each_text"
376            | "pg_get_sequence_data"
377            | "pg_sequence_parameters"
378            | "aclexplode"
379    )
380}
381
382#[cfg(test)]
383fn builtin_table_function_overloads(
384    name: &str,
385    argument_types: &[Option<ColumnType>],
386) -> Vec<BuiltinFunctionOverload> {
387    selection::builtin_table_function_overloads_with_control(
388        name,
389        argument_types,
390        &uqa_core::memory::ProductionControl::uncontrolled(),
391    )
392    .expect("ordinary table declarations cannot be cancelled or limited")
393    .into_uncontrolled()
394    .expect("ordinary table declarations")
395}
396
397pub fn is_builtin_table_function(name: &str) -> bool {
398    matches!(
399        name,
400        "generate_series"
401            | "pg_listening_channels"
402            | "unnest"
403            | "regexp_matches"
404            | "regexp_split_to_table"
405            | "string_to_table"
406            | "json_array_elements"
407            | "jsonb_array_elements"
408            | "json_array_elements_text"
409            | "jsonb_array_elements_text"
410            | "json_object_keys"
411            | "jsonb_object_keys"
412            | "json_each"
413            | "jsonb_each"
414            | "json_each_text"
415            | "jsonb_each_text"
416            | "pg_get_sequence_data"
417            | "pg_sequence_parameters"
418            | "aclexplode"
419            | "create_analyzer"
420            | "drop_analyzer"
421            | "list_analyzers"
422            | "analyze_text"
423            | "fts_index_stats"
424            | "set_table_analyzer"
425            | "pagerank"
426            | "graph_pagerank"
427            | "hits"
428            | "graph_hits"
429            | "betweenness"
430            | "graph_betweenness"
431            | "graph_edges"
432            | "rpq"
433            | "cypher"
434    )
435}
436
437pub fn table_function_empty_schema(
438    name: &str,
439    output_name: &str,
440    alias: Option<&str>,
441    column_aliases: &[String],
442    output_width: usize,
443    ordinality: bool,
444) -> Vec<String> {
445    table_function_empty_schema_with_control(
446        name,
447        output_name,
448        alias,
449        column_aliases,
450        output_width,
451        ordinality,
452        &uqa_core::memory::ProductionControl::uncontrolled(),
453    )
454    .expect("ordinary table-function names")
455    .into_uncontrolled()
456    .expect("ordinary table-function owner")
457}
458
459pub fn apply_table_function_aliases(
460    mut columns: Vec<String>,
461    column_aliases: &[String],
462    ordinality: bool,
463) -> Vec<String> {
464    if ordinality {
465        columns.push("ordinality".into());
466    }
467    for (column, alias) in columns.iter_mut().zip(column_aliases) {
468        column.clone_from(alias);
469    }
470    columns
471}
472
473pub fn validate_table_function_alias_count(
474    table_alias: &str,
475    available: usize,
476    specified: usize,
477) -> Result<(), SQLError> {
478    validate_table_function_alias_count_with_control(
479        table_alias,
480        available,
481        specified,
482        &uqa_core::memory::ProductionControl::uncontrolled(),
483    )
484}
485
486pub struct TableFunctionTypeRequest<'a> {
487    pub name: &'a str,
488    pub binding: Option<&'a FunctionBinding>,
489    pub args: &'a [ScalarExpr],
490    pub user_function: Option<&'a SQLUserFunction>,
491    pub user_invocation: Option<&'a RoutineInvocationBinding>,
492    pub declared_types: &'a [String],
493    pub columns: &'a [String],
494    pub ordinality: bool,
495}
496
497pub fn table_function_column_types(
498    routines: &dyn RoutineResolution,
499    request: TableFunctionTypeRequest<'_>,
500    input_schema: &crate::RowSchema,
501    params: &[SQLParam],
502    resolver: &dyn FunctionTypeResolver,
503) -> Vec<Option<ColumnType>> {
504    table_function_column_types_with_control(
505        routines,
506        request,
507        input_schema,
508        params,
509        resolver,
510        &uqa_core::memory::ProductionControl::uncontrolled(),
511    )
512    .expect("ordinary table result types")
513    .into_uncontrolled()
514    .expect("ordinary table type fields")
515}
516
517pub fn is_json_array_table_function(name: &str) -> bool {
518    matches!(
519        name,
520        "json_array_elements"
521            | "jsonb_array_elements"
522            | "json_array_elements_text"
523            | "jsonb_array_elements_text"
524    )
525}
526
527pub fn scalar_table_function_default_column(
528    normalized_name: &str,
529    output_name: &str,
530    alias: Option<&str>,
531    column_aliases: &[String],
532) -> String {
533    column_aliases.first().cloned().unwrap_or_else(|| {
534        if is_json_array_table_function(normalized_name) {
535            "value".into()
536        } else {
537            alias.unwrap_or(output_name).to_string()
538        }
539    })
540}
541pub fn join_alias_columns(
542    schema: &crate::RowSchema,
543    alias: &str,
544    column_aliases: &[String],
545) -> Result<Vec<String>, SQLError> {
546    Ok(join_alias_columns_with_control(
547        schema,
548        alias,
549        column_aliases,
550        &uqa_core::memory::ProductionControl::uncontrolled(),
551    )?
552    .into_uncontrolled()
553    .expect("ordinary JOIN alias has no reservation"))
554}
555
556pub fn alias_join_schema(
557    schema: &crate::RowSchema,
558    alias: Option<&str>,
559    column_aliases: &[String],
560) -> Result<crate::RowSchema, SQLError> {
561    alias_join_schema_with_control(
562        schema,
563        alias,
564        column_aliases,
565        &uqa_core::memory::ProductionControl::uncontrolled(),
566    )
567}
568
569mod join_aliases;
570pub use join_aliases::{
571    alias_join_physical_schema_with_control, alias_join_schema_with_control,
572    join_alias_columns_with_control,
573};
574
575#[cfg(test)]
576mod tests;