Skip to main content

uqa_execution/query/
set_projection.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Physical expansion of set-returning SELECT-list calls.
8
9use crate::query::routine_invocation::SQLRoutineInvoker;
10use crate::query::table_functions::{
11    registered_table_function_rows, TableFunctionCall, TableFunctionRows,
12};
13use crate::query::PhysicalProjection;
14use crate::scalar::plan::PlanSubqueryArena;
15use crate::{
16    eval_call_arguments, Batch, ExecResult, OwnedPhysicalRow, PhysicalOperator,
17    PhysicalProjectRows, PhysicalRow, Project, ProjectionTarget, RowSchema, ScalarEvalContext,
18    ScalarExpr, SharedExpressionEvaluator,
19};
20use std::sync::Arc;
21use uqa_core::Value;
22use uqa_sql::semantics::sets::{SetFunctionCall, SetFunctionCatalog, SetProjectionPlan};
23use uqa_sql::{ast::ColumnType, SQLError, SQLParam};
24
25/// Function invocation and scoped expression services consumed by a set-expansion operator.
26pub trait SetFunctionRuntime:
27    crate::query::expression::ScalarExpressionContext + SQLRoutineInvoker
28{
29    fn has_registered_table_function(&self, name: &str) -> bool;
30    fn table_function_rows(
31        &self,
32        call: TableFunctionCall<'_>,
33        params: &[SQLParam],
34        row: Option<&OwnedPhysicalRow>,
35    ) -> Result<TableFunctionRows, SQLError>;
36}
37
38enum SetFunctionState {
39    Scalar(Value),
40    Set {
41        columns: Vec<String>,
42        rows: PhysicalProjectRows,
43        exhausted: bool,
44    },
45}
46
47struct SetExpansion {
48    input: OwnedPhysicalRow,
49    calls: Vec<SetFunctionState>,
50    has_set: bool,
51    scalar_emitted: bool,
52}
53
54impl SetExpansion {
55    fn close(&mut self) -> ExecResult<()> {
56        close_calls(&mut self.calls)
57    }
58
59    fn next_values(&mut self) -> ExecResult<Option<Vec<Value>>> {
60        if !self.has_set {
61            if self.scalar_emitted {
62                return Ok(None);
63            }
64            self.scalar_emitted = true;
65            return Ok(Some(
66                self.calls
67                    .iter()
68                    .map(|call| match call {
69                        SetFunctionState::Scalar(value) => value.clone(),
70                        SetFunctionState::Set { .. } => unreachable!("has_set is false"),
71                    })
72                    .collect(),
73            ));
74        }
75
76        let mut produced = false;
77        let mut values = Vec::with_capacity(self.calls.len());
78        for call in &mut self.calls {
79            match call {
80                SetFunctionState::Scalar(value) => values.push(value.clone()),
81                SetFunctionState::Set {
82                    columns,
83                    rows,
84                    exhausted,
85                } => {
86                    if *exhausted {
87                        values.push(Value::Null);
88                        continue;
89                    }
90                    if let Some(row) = rows.next() {
91                        produced = true;
92                        values.push(set_row_value(row?, columns));
93                    } else {
94                        *exhausted = true;
95                        values.push(Value::Null);
96                    }
97                }
98            }
99        }
100        Ok(produced.then_some(values))
101    }
102}
103
104fn close_calls(calls: &mut [SetFunctionState]) -> ExecResult<()> {
105    let mut result = Ok(());
106    for call in calls {
107        if let SetFunctionState::Set {
108            rows, exhausted, ..
109        } = call
110        {
111            *exhausted = true;
112            result = crate::physical::with_cleanup(
113                result,
114                rows.close().map_err(Into::into),
115                "close set-returning call",
116            );
117        }
118    }
119    result
120}
121
122fn set_row_value(row: PhysicalRow, columns: &[String]) -> Value {
123    let values = row.into_physical_values();
124    if values.len() == 1 {
125        return values.into_iter().next().unwrap_or(Value::Null);
126    }
127    debug_assert_eq!(columns.len(), values.len());
128    Value::Record(
129        columns
130            .iter()
131            .cloned()
132            .zip(values)
133            .collect::<Vec<_>>()
134            .into(),
135    )
136}
137
138/// Projection and output batching applied after set expansion.
139pub struct SetProjectionOutput {
140    pub projections: Vec<PhysicalProjection>,
141    pub pass_through: bool,
142    pub batch_size: usize,
143}
144
145pub fn build_set_projection<'a>(
146    mut operator: Box<dyn PhysicalOperator + 'a>,
147    catalog: &dyn SetFunctionCatalog,
148    runtime: Arc<dyn SetFunctionRuntime + 'a>,
149    params: &'a [SQLParam],
150    evaluator: SharedExpressionEvaluator<'a>,
151    work_mem: usize,
152    output: SetProjectionOutput,
153) -> Result<Box<dyn PhysicalOperator + 'a>, SQLError> {
154    let SetProjectionOutput {
155        projections,
156        pass_through,
157        batch_size: output_batch_size,
158    } = output;
159    let (input, plan) = crate::physical::construction::OperatorBuild::run(operator, |operator| {
160        SetProjectionPlan::new(
161            catalog,
162            runtime.as_ref(),
163            projections,
164            operator.row_schema(),
165            params,
166        )
167    })?;
168    operator = input;
169    let max_level = plan.calls.iter().map(|call| call.level).max().unwrap_or(0);
170    for level in 0..=max_level {
171        let calls = plan
172            .calls
173            .iter()
174            .filter(|call| call.level == level)
175            .cloned()
176            .collect::<Vec<_>>();
177        if calls.is_empty() {
178            continue;
179        }
180        let projections = calls
181            .iter()
182            .map(|call| {
183                (
184                    ProjectionTarget::Internal(call.placeholder),
185                    ScalarExpr::InternalColumn(call.placeholder),
186                )
187            })
188            .collect();
189        operator = Box::new(SetProjection::from_plan(
190            operator,
191            Arc::clone(&runtime),
192            params,
193            evaluator.clone(),
194            SetProjectionPlan { projections, calls },
195            true,
196            output_batch_size,
197        ));
198    }
199    if pass_through {
200        Ok(Box::new(
201            Project::appending_target_evaluator(operator, plan.projections, evaluator)
202                .with_memory_budget(work_mem),
203        ))
204    } else {
205        Ok(Box::new(
206            Project::with_target_evaluator(operator, plan.projections, evaluator)
207                .with_memory_budget(work_mem),
208        ))
209    }
210}
211
212mod operator;
213pub use operator::SetProjection;