Skip to main content

uqa_execution/query/
table_functions.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Table-function call metadata and positional result transport.
8
9use crate::functions::{SQLTableFunctionResult, SQLTableFunctionStream};
10use crate::ScalarExpr;
11use uqa_core::Value;
12use uqa_sql::SQLError;
13
14#[derive(Clone, Copy)]
15pub struct TableFunctionCall<'a> {
16    pub name: &'a str,
17    pub binding: Option<&'a uqa_sql::ast::FunctionBinding>,
18    pub output_name: &'a str,
19    pub relations: Option<&'a uqa_sql::ast::OperatorJoinRelations>,
20    pub args: &'a [ScalarExpr],
21    /// State owned by the caller's already-bound argument expressions. A one-shot
22    /// caller may leave this absent and let the table-function entry bind them.
23    pub function_states: Option<&'a crate::scalar::FunctionCallStates>,
24    /// Metadata owned by the prepared table call, independently of argument expressions.
25    pub routine_descriptions:
26        Option<&'a uqa_sql::routines::invocation::descriptions::RoutineCallDescriptions>,
27    pub alias: Option<&'a str>,
28    pub column_aliases: &'a [String],
29    pub ordinality: bool,
30    pub column_types: &'a [String],
31}
32
33/// SQL-visible column metadata paired with positional table-function rows. Column names never participate in row transport, so duplicate and unnamed outputs remain distinct physical attributes.
34pub struct TableFunctionRows {
35    pub columns: Vec<String>,
36    pub rows: crate::PhysicalProjectRows,
37}
38
39fn validate_registered_columns(
40    name: &str,
41    declared: Option<&[String]>,
42    actual: &[String],
43) -> Result<(), SQLError> {
44    if declared.is_some_and(|declared| declared != actual) {
45        return Err(SQLError::TypeMismatch(format!(
46            "table function `{name}` returned columns different from its registered descriptor"
47        )));
48    }
49    Ok(())
50}
51
52impl TableFunctionRows {
53    pub fn new(columns: Vec<String>, rows: crate::PhysicalProjectRows) -> Self {
54        Self { columns, rows }
55    }
56
57    /// Transfer rows to an already described source, closing a mismatched scan
58    /// before rejecting its descriptor.
59    pub(crate) fn into_rows(
60        mut self,
61        width: usize,
62        source: &str,
63    ) -> Result<crate::PhysicalProjectRows, SQLError> {
64        if self.columns.len() != width {
65            let error = SQLError::Internal(format!(
66                "{source} produced {} columns for a {width}-column source",
67                self.columns.len(),
68            ));
69            return Err(self.rows.fail(error));
70        }
71        Ok(self.rows)
72    }
73
74    pub fn materialized(columns: Vec<String>, rows: Vec<Vec<Value>>) -> Self {
75        Self::new(
76            columns,
77            crate::SQLRowStream::new(
78                rows.into_iter()
79                    .map(|values| Ok(crate::PhysicalRow::from_values(values))),
80            ),
81        )
82    }
83}
84
85pub fn registered_table_function_rows(
86    name: &str,
87    result: SQLTableFunctionResult,
88    _alias: Option<&str>,
89    column_aliases: &[String],
90) -> Result<TableFunctionRows, SQLError> {
91    if result.columns.is_empty() {
92        return Err(SQLError::TypeMismatch(format!(
93            "table function `{name}` returned no columns"
94        )));
95    }
96    let columns: Vec<String> = result
97        .columns
98        .iter()
99        .enumerate()
100        .map(|(idx, column)| {
101            column_aliases
102                .get(idx)
103                .cloned()
104                .unwrap_or_else(|| column.clone())
105        })
106        .collect();
107    let mut out = Vec::with_capacity(result.rows.len());
108    for values in result.rows {
109        if values.len() != result.columns.len() {
110            return Err(SQLError::TypeMismatch(format!(
111                "table function `{name}` row has {} values for {} columns",
112                values.len(),
113                result.columns.len()
114            )));
115        }
116        out.push(values);
117    }
118    Ok(TableFunctionRows::materialized(columns, out))
119}
120
121pub fn registered_table_function_row_stream(
122    name: &str,
123    mut result: SQLTableFunctionStream,
124    _alias: Option<&str>,
125    column_aliases: &[String],
126) -> Result<TableFunctionRows, SQLError> {
127    if result.columns.is_empty() {
128        let error = SQLError::TypeMismatch(format!("table function `{name}` returned no columns"));
129        return Err(result.rows.fail(error));
130    }
131    let expected_width = result.columns.len();
132    let columns = result
133        .columns
134        .iter()
135        .enumerate()
136        .map(|(index, column)| {
137            column_aliases
138                .get(index)
139                .cloned()
140                .unwrap_or_else(|| column.clone())
141        })
142        .collect::<Vec<_>>();
143    let function_name = name.to_string();
144    Ok(TableFunctionRows::new(
145        columns,
146        result.rows.map_rows(move |values| {
147            if values.len() != expected_width {
148                return Err(SQLError::TypeMismatch(format!(
149                "table function `{function_name}` row has {} values for {expected_width} columns",
150                values.len()
151            )));
152            }
153            Ok(crate::PhysicalRow::from_values(values))
154        }),
155    ))
156}
157
158pub mod values;
159
160pub mod rows_from;
161
162mod acl;
163mod analyzers;
164pub use analyzers::analyze_text;
165pub mod context;
166mod deferred;
167pub use deferred::DeferredTableFunctionRows;
168mod dispatch;
169mod graphs;
170mod records;
171mod regular_expressions;
172mod stream;
173pub use stream::{build_table_function_row_stream_with_row, deferred_table_function_columns};