Skip to main content

uqa_execution/query/table_functions/
stream.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Lazy table-function evaluation, host callback streams, cancellation, and ordinality.
8
9use super::{
10    context::TableFunctionContext,
11    dispatch::build_table_function_rows_with_row,
12    registered_table_function_row_stream,
13    values::{
14        generate_series_values, json_array_values, json_each_rows, json_object_key_values,
15        string_to_table_values, unnest_rows,
16    },
17    TableFunctionCall, TableFunctionRows,
18};
19use crate::scalar::plan::PlanSubqueryArena;
20use crate::{eval_call_arguments, ScalarEvalContext};
21use uqa_core::Value;
22use uqa_sql::{semantics::scalar_table_function_default_column, SQLError};
23
24/// Build a table-function result as a fallible owned row stream. Built-in cardinality-producing functions are evaluated lazily; registered/user functions keep their existing vector-valued API and are adapted at this explicit extension boundary. A correlated lateral caller supplies its physical outer row so function arguments are evaluated in the same scope used during binding.
25#[allow(clippy::similar_names)]
26pub fn build_table_function_row_stream_with_row(
27    context: &TableFunctionContext<'_>,
28    call: TableFunctionCall<'_>,
29    row: Option<&crate::OwnedPhysicalRow>,
30) -> Result<TableFunctionRows, SQLError> {
31    if let Some(binding) = call.binding {
32        context.eval_hook.require_builtin_execute(binding)?;
33    }
34    let ordinality = call.ordinality;
35    let mut output = build_table_function_value_row_stream_with_row(context, call, row)?;
36    let cancellation = context.runtime.cancellation_token();
37    output.rows = crate::SQLRowStream::from_source(CancellableRows {
38        rows: output.rows,
39        cancellation,
40    });
41    if !ordinality {
42        return Ok(output);
43    }
44    output
45        .columns
46        .push(ordinality_column(&call, output.columns.len()));
47    let mut next = Some(1_i64);
48    output.rows = output.rows.map_rows(move |row| {
49        let ordinal = next.ok_or_else(|| SQLError::Routine {
50            sqlstate: "22003".into(),
51            message: "WITH ORDINALITY counter exceeds bigint".into(),
52        })?;
53        next = ordinal.checked_add(1);
54        Ok(row.append_values(vec![Value::Int(ordinal)]))
55    });
56    Ok(output)
57}
58
59struct CancellableRows {
60    rows: crate::PhysicalProjectRows,
61    cancellation: uqa_core::CancellationToken,
62}
63
64impl crate::SQLRowSource<crate::PhysicalRow> for CancellableRows {
65    fn next_row(&mut self) -> Result<Option<crate::PhysicalRow>, SQLError> {
66        self.cancellation.check()?;
67        self.rows.next().transpose()
68    }
69
70    fn close(&mut self) -> Result<(), SQLError> {
71        self.rows.close()
72    }
73}
74
75/// The output columns of a built-in set-returning call, including its ordinality column. They follow from the call's name, aliases and argument count, never from argument values, so a FROM item can describe its rows before it evaluates the call, as `PostgreSQL` does until the first row is requested. `None` for a function whose columns only its result reveals.
76pub fn deferred_table_function_columns(
77    call: &TableFunctionCall<'_>,
78) -> Option<Result<Vec<String>, SQLError>> {
79    let lower = streaming_builtin(call)?;
80    Some(builtin_value_columns(&lower, call).map(|mut columns| {
81        if call.ordinality {
82            let column = ordinality_column(call, columns.len());
83            columns.push(column);
84        }
85        columns
86    }))
87}
88
89fn ordinality_column(call: &TableFunctionCall<'_>, position: usize) -> String {
90    call.column_aliases
91        .get(position)
92        .cloned()
93        .unwrap_or_else(|| "ordinality".into())
94}
95
96/// The dispatch name of a built-in set-returning function that this module streams.
97fn streaming_builtin<'a>(call: &TableFunctionCall<'a>) -> Option<std::borrow::Cow<'a, str>> {
98    if call.binding.is_some_and(|binding| !binding.builtin) {
99        return None;
100    }
101    let lower = uqa_sql::semantics::builtin_function_dispatch_name(call.name);
102    matches!(
103        lower.as_ref(),
104        "generate_series"
105            | "pg_listening_channels"
106            | "unnest"
107            | "regexp_matches"
108            | "regexp_split_to_table"
109            | "string_to_table"
110            | "json_array_elements"
111            | "jsonb_array_elements"
112            | "json_array_elements_text"
113            | "jsonb_array_elements_text"
114            | "json_object_keys"
115            | "jsonb_object_keys"
116            | "json_each"
117            | "jsonb_each"
118            | "json_each_text"
119            | "jsonb_each_text"
120            | "aclexplode"
121    )
122    .then_some(lower)
123}
124
125/// The value columns of a streaming built-in, before any ordinality column.
126fn builtin_value_columns(
127    lower: &str,
128    call: &TableFunctionCall<'_>,
129) -> Result<Vec<String>, SQLError> {
130    Ok(match lower {
131        "unnest" => {
132            let aliases = if call.ordinality {
133                &call.column_aliases[..call.column_aliases.len().min(call.args.len())]
134            } else {
135                call.column_aliases
136            };
137            if call.args.is_empty() || aliases.len() > call.args.len() {
138                return Err(SQLError::BadArity {
139                    name: "unnest".into(),
140                    expected: "one output alias per array argument".into(),
141                    actual: call.args.len(),
142                });
143            }
144            uqa_sql::semantics::table_function_empty_schema(
145                "unnest",
146                call.output_name,
147                call.alias,
148                aliases,
149                call.args.len(),
150                false,
151            )
152        }
153        "json_each" | "jsonb_each" | "json_each_text" | "jsonb_each_text" => vec![
154            call.column_aliases
155                .first()
156                .cloned()
157                .unwrap_or_else(|| "key".into()),
158            call.column_aliases
159                .get(1)
160                .cloned()
161                .unwrap_or_else(|| "value".into()),
162        ],
163        "aclexplode" => super::acl::aclexplode_columns(call.column_aliases),
164        _ => vec![scalar_table_function_default_column(
165            lower,
166            call.output_name,
167            call.alias,
168            call.column_aliases,
169        )],
170    })
171}
172
173#[allow(clippy::similar_names)]
174fn build_table_function_value_row_stream_with_row(
175    context: &TableFunctionContext<'_>,
176    call: TableFunctionCall<'_>,
177    row: Option<&crate::OwnedPhysicalRow>,
178) -> Result<TableFunctionRows, SQLError> {
179    if let Some(lower) = streaming_builtin(&call) {
180        let call_args = evaluate_arguments(context, &call, row)?;
181        let empty = crate::RowSchema::default();
182        let selected = if call.binding.is_none() {
183            uqa_sql::semantics::resolve_runtime_table_function_binding(
184                context.routines.lookup,
185                call.name,
186                call.args,
187                &call_args,
188                row.map_or(&empty, |row| &row.schema),
189                context.params,
190                context.resolver,
191            )?
192        } else {
193            None
194        };
195        let binding = selected.as_ref().or(call.binding);
196        if let Some(binding) = binding.filter(|binding| !binding.builtin) {
197            let record =
198                (!call.column_types.is_empty()).then_some((call.column_aliases, call.column_types));
199            let result = crate::routines::invocation::call_bound_user_table_function(
200                &context.routines,
201                binding,
202                &call_args,
203                record,
204            )
205            .ok_or_else(|| SQLError::Internal("selected table function disappeared".into()))??;
206            return super::registered_table_function_rows(
207                call.name,
208                result,
209                call.alias,
210                call.column_aliases,
211            );
212        }
213        if let Some(binding) = selected.as_ref() {
214            context.eval_hook.require_builtin_execute(binding)?;
215        }
216        let columns = builtin_value_columns(&lower, &call)?;
217        let evaluated = builtin_arguments(&lower, call_args)?;
218        // The regular-expression functions read the call's input collation, `PostgreSQL`'s `inputcollid`.
219        let collation = uqa_sql::ast::FunctionBinding::selected_input_collation(binding);
220        let rows = builtin_value_rows(context, &lower, evaluated, collation, &columns)?;
221        return Ok(TableFunctionRows::new(columns, rows));
222    }
223    let TableFunctionCall {
224        name,
225        binding,
226        alias,
227        column_aliases,
228        ..
229    } = call;
230    let identity = name.to_ascii_lowercase();
231    let lower = uqa_sql::semantics::builtin_function_dispatch_name(&identity);
232    if binding.is_none_or(|binding| binding.builtin)
233        && context.runtime.has_table_function(&identity)
234    {
235        let call_args = evaluate_arguments(context, &call, row)?;
236        if call_args.iter().any(|(name, _)| name.is_some()) {
237            return Err(uqa_sql::expr::unknown_function_error(&lower, &call_args));
238        }
239        let evaluated = call_args
240            .into_iter()
241            .map(|(_, value)| value)
242            .collect::<Vec<_>>();
243        let evaluated = uqa_sql::expr::enums::render_host_arguments(
244            context.eval_hook.enum_labels(),
245            &evaluated,
246        )?;
247        let result = context
248            .runtime
249            .lookup_table_function(&identity)
250            .map(|registration| {
251                let mut result = registration
252                    .function
253                    .call_stream_with_context(context.runtime.function_context, &evaluated)?;
254                if let Err(error) = super::validate_registered_columns(
255                    name,
256                    registration.function.output_columns(),
257                    &result.columns,
258                ) {
259                    return Err(result.rows.fail(error));
260                }
261                Ok(result)
262            })
263            .ok_or_else(|| {
264                SQLError::Internal(format!(
265                    "registered table function `{name}` disappeared during execution"
266                ))
267            })??;
268        return registered_table_function_row_stream(name, result, alias, column_aliases);
269    }
270
271    build_table_function_rows_with_row(context, call, row)
272}
273
274/// Evaluate arguments once in their calling scope before choosing a dynamically typed overload.
275fn evaluate_arguments(
276    context: &TableFunctionContext<'_>,
277    call: &TableFunctionCall<'_>,
278    row: Option<&crate::OwnedPhysicalRow>,
279) -> Result<Vec<(Option<String>, Value)>, SQLError> {
280    let subquery_arena = PlanSubqueryArena::new(context.subqueries, Some(context.subquery_runner));
281    let scalar_context = match row {
282        Some(row) => ScalarEvalContext::from_row_lookup(row, context.params)
283            .with_physical_outer_row(&row.schema, &row.row),
284        None => ScalarEvalContext::new(None, context.params),
285    };
286    let mut scalar_context = scalar_context
287        .with_function_hook(context.eval_hook)
288        .with_subquery_runner(&subquery_arena);
289    if let Some(states) = call.function_states {
290        scalar_context = scalar_context.with_function_states(states);
291    }
292    // Arguments bind like any other expression: catalog-typed calls such as `enum_range(NULL::mood)` select their operation from declared types.
293    let empty = crate::RowSchema::default();
294    let schema = row.map_or(&empty, |row| &row.schema);
295    let bound = call.function_states.is_none().then(|| {
296        call.args
297            .iter()
298            .map(|argument| {
299                uqa_sql::bind_type_introspection_with_resolver(
300                    argument.clone(),
301                    schema,
302                    context.params,
303                    context.resolver,
304                )
305            })
306            .collect::<Vec<_>>()
307    });
308    eval_call_arguments(bound.as_deref().unwrap_or(call.args), &scalar_context)
309}
310
311fn builtin_arguments(
312    lower: &str,
313    call_args: Vec<(Option<String>, Value)>,
314) -> Result<Vec<Value>, SQLError> {
315    // Named arguments take their declared positions as in a scalar call; a function without such a signature is undefined.
316    if call_args.iter().any(|(name, _)| name.is_some()) {
317        return Ok(uqa_sql::expr::builtin_named_args(
318            lower,
319            &call_args,
320            &uqa_core::memory::ProductionControl::uncontrolled(),
321        )?
322        .ok_or_else(|| uqa_sql::expr::unknown_function_error(lower, &call_args))?
323        .into_parts()
324        .0);
325    }
326    Ok(call_args.into_iter().map(|(_, value)| value).collect())
327}
328
329/// The rows of a streaming built-in over its evaluated arguments and input collation, in the layout `columns` names.
330fn builtin_value_rows(
331    context: &TableFunctionContext<'_>,
332    lower: &str,
333    evaluated: Vec<Value>,
334    collation: u32,
335    columns: &[String],
336) -> Result<crate::PhysicalProjectRows, SQLError> {
337    let values: Box<dyn Iterator<Item = Value> + Send> = match lower {
338        "unnest" => return unnest_rows(evaluated),
339        "pg_listening_channels" => {
340            uqa_sql::semantics::table_function_arguments::require_no_arguments(lower, &evaluated)?;
341            Box::new(
342                context
343                    .session
344                    .listening_channels()
345                    .into_iter()
346                    .map(Value::Str),
347            )
348        }
349        "generate_series" => generate_series_values(evaluated)?,
350        "regexp_matches" => {
351            return super::regular_expressions::regexp_matches_row_stream(
352                &evaluated,
353                collation,
354                columns[0].clone(),
355            )
356            .map(|output| output.rows);
357        }
358        "regexp_split_to_table" => {
359            return super::regular_expressions::regexp_split_to_table_row_stream(
360                &evaluated,
361                collation,
362                columns[0].clone(),
363            )
364            .map(|output| output.rows);
365        }
366        "string_to_table" => string_to_table_values(evaluated)?,
367        "json_array_elements"
368        | "jsonb_array_elements"
369        | "json_array_elements_text"
370        | "jsonb_array_elements_text" => json_array_values(lower, evaluated)?,
371        "json_object_keys" | "jsonb_object_keys" => json_object_key_values(lower, evaluated)?,
372        "json_each" | "jsonb_each" | "json_each_text" | "jsonb_each_text" => {
373            return json_each_rows(lower, evaluated);
374        }
375        "aclexplode" => {
376            return super::acl::aclexplode_rows(&|name| context.session.role_oid(name), evaluated);
377        }
378        _ => {
379            return Err(SQLError::Internal(format!(
380                "streaming table function `{lower}` reached an unsupported dispatch branch"
381            )));
382        }
383    };
384    Ok(crate::SQLRowStream::new(values.map(|value| {
385        Ok(crate::PhysicalRow::from_values(vec![value]))
386    })))
387}