uqa-execution 0.6.2

Volcano physical operators with row-batch pipelines
Documentation
//
// Unified Query Algebra
//
// Copyright (c) 2023-2026 Cognica, Inc.
//

//! Table-function call metadata and positional result transport.

use crate::functions::{SQLTableFunctionResult, SQLTableFunctionStream};
use crate::ScalarExpr;
use uqa_core::Value;
use uqa_sql::SQLError;

#[derive(Clone, Copy)]
pub struct TableFunctionCall<'a> {
    pub name: &'a str,
    pub binding: Option<&'a uqa_sql::ast::FunctionBinding>,
    pub output_name: &'a str,
    pub relations: Option<&'a uqa_sql::ast::OperatorJoinRelations>,
    pub args: &'a [ScalarExpr],
    /// State owned by the caller's already-bound argument expressions. A one-shot
    /// caller may leave this absent and let the table-function entry bind them.
    pub function_states: Option<&'a crate::scalar::FunctionCallStates>,
    /// Metadata owned by the prepared table call, independently of argument expressions.
    pub routine_descriptions:
        Option<&'a uqa_sql::routines::invocation::descriptions::RoutineCallDescriptions>,
    pub alias: Option<&'a str>,
    pub column_aliases: &'a [String],
    pub ordinality: bool,
    pub column_types: &'a [String],
}

/// 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.
pub struct TableFunctionRows {
    pub columns: Vec<String>,
    pub rows: crate::PhysicalProjectRows,
}

fn validate_registered_columns(
    name: &str,
    declared: Option<&[String]>,
    actual: &[String],
) -> Result<(), SQLError> {
    if declared.is_some_and(|declared| declared != actual) {
        return Err(SQLError::TypeMismatch(format!(
            "table function `{name}` returned columns different from its registered descriptor"
        )));
    }
    Ok(())
}

impl TableFunctionRows {
    pub fn new(columns: Vec<String>, rows: crate::PhysicalProjectRows) -> Self {
        Self { columns, rows }
    }

    /// Transfer rows to an already described source, closing a mismatched scan
    /// before rejecting its descriptor.
    pub(crate) fn into_rows(
        mut self,
        width: usize,
        source: &str,
    ) -> Result<crate::PhysicalProjectRows, SQLError> {
        if self.columns.len() != width {
            let error = SQLError::Internal(format!(
                "{source} produced {} columns for a {width}-column source",
                self.columns.len(),
            ));
            return Err(self.rows.fail(error));
        }
        Ok(self.rows)
    }

    pub fn materialized(columns: Vec<String>, rows: Vec<Vec<Value>>) -> Self {
        Self::new(
            columns,
            crate::SQLRowStream::new(
                rows.into_iter()
                    .map(|values| Ok(crate::PhysicalRow::from_values(values))),
            ),
        )
    }
}

pub fn registered_table_function_rows(
    name: &str,
    result: SQLTableFunctionResult,
    _alias: Option<&str>,
    column_aliases: &[String],
) -> Result<TableFunctionRows, SQLError> {
    if result.columns.is_empty() {
        return Err(SQLError::TypeMismatch(format!(
            "table function `{name}` returned no columns"
        )));
    }
    let columns: Vec<String> = result
        .columns
        .iter()
        .enumerate()
        .map(|(idx, column)| {
            column_aliases
                .get(idx)
                .cloned()
                .unwrap_or_else(|| column.clone())
        })
        .collect();
    let mut out = Vec::with_capacity(result.rows.len());
    for values in result.rows {
        if values.len() != result.columns.len() {
            return Err(SQLError::TypeMismatch(format!(
                "table function `{name}` row has {} values for {} columns",
                values.len(),
                result.columns.len()
            )));
        }
        out.push(values);
    }
    Ok(TableFunctionRows::materialized(columns, out))
}

pub fn registered_table_function_row_stream(
    name: &str,
    mut result: SQLTableFunctionStream,
    _alias: Option<&str>,
    column_aliases: &[String],
) -> Result<TableFunctionRows, SQLError> {
    if result.columns.is_empty() {
        let error = SQLError::TypeMismatch(format!("table function `{name}` returned no columns"));
        return Err(result.rows.fail(error));
    }
    let expected_width = result.columns.len();
    let columns = result
        .columns
        .iter()
        .enumerate()
        .map(|(index, column)| {
            column_aliases
                .get(index)
                .cloned()
                .unwrap_or_else(|| column.clone())
        })
        .collect::<Vec<_>>();
    let function_name = name.to_string();
    Ok(TableFunctionRows::new(
        columns,
        result.rows.map_rows(move |values| {
            if values.len() != expected_width {
                return Err(SQLError::TypeMismatch(format!(
                "table function `{function_name}` row has {} values for {expected_width} columns",
                values.len()
            )));
            }
            Ok(crate::PhysicalRow::from_values(values))
        }),
    ))
}

pub mod values;

pub mod rows_from;

mod acl;
mod analyzers;
pub use analyzers::analyze_text;
pub mod context;
mod deferred;
pub use deferred::DeferredTableFunctionRows;
mod dispatch;
mod graphs;
mod records;
mod regular_expressions;
mod stream;
pub use stream::{build_table_function_row_stream_with_row, deferred_table_function_columns};