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 next_values(&mut self) -> ExecResult<Option<Vec<Value>>> {
56        if !self.has_set {
57            if self.scalar_emitted {
58                return Ok(None);
59            }
60            self.scalar_emitted = true;
61            return Ok(Some(
62                self.calls
63                    .iter()
64                    .map(|call| match call {
65                        SetFunctionState::Scalar(value) => value.clone(),
66                        SetFunctionState::Set { .. } => unreachable!("has_set is false"),
67                    })
68                    .collect(),
69            ));
70        }
71
72        let mut produced = false;
73        let mut values = Vec::with_capacity(self.calls.len());
74        for call in &mut self.calls {
75            match call {
76                SetFunctionState::Scalar(value) => values.push(value.clone()),
77                SetFunctionState::Set {
78                    columns,
79                    rows,
80                    exhausted,
81                } => {
82                    if *exhausted {
83                        values.push(Value::Null);
84                        continue;
85                    }
86                    if let Some(row) = rows.next() {
87                        produced = true;
88                        values.push(set_row_value(row?, columns));
89                    } else {
90                        *exhausted = true;
91                        values.push(Value::Null);
92                    }
93                }
94            }
95        }
96        Ok(produced.then_some(values))
97    }
98}
99
100fn set_row_value(row: PhysicalRow, columns: &[String]) -> Value {
101    let values = row.into_physical_values();
102    if values.len() == 1 {
103        return values.into_iter().next().unwrap_or(Value::Null);
104    }
105    debug_assert_eq!(columns.len(), values.len());
106    Value::Record(
107        columns
108            .iter()
109            .cloned()
110            .zip(values)
111            .collect::<Vec<_>>()
112            .into(),
113    )
114}
115
116/// Projection and output batching applied after set expansion.
117pub struct SetProjectionOutput {
118    pub projections: Vec<PhysicalProjection>,
119    pub pass_through: bool,
120    pub batch_size: usize,
121}
122
123pub fn build_set_projection<'a>(
124    mut operator: Box<dyn PhysicalOperator + 'a>,
125    catalog: &dyn SetFunctionCatalog,
126    runtime: Arc<dyn SetFunctionRuntime + 'a>,
127    params: &'a [SQLParam],
128    evaluator: SharedExpressionEvaluator<'a>,
129    work_mem: usize,
130    output: SetProjectionOutput,
131) -> Result<Box<dyn PhysicalOperator + 'a>, SQLError> {
132    let SetProjectionOutput {
133        projections,
134        pass_through,
135        batch_size: output_batch_size,
136    } = output;
137    let plan = SetProjectionPlan::new(
138        catalog,
139        runtime.as_ref(),
140        projections,
141        operator.row_schema(),
142        params,
143    )?;
144    let max_level = plan.calls.iter().map(|call| call.level).max().unwrap_or(0);
145    for level in 0..=max_level {
146        let calls = plan
147            .calls
148            .iter()
149            .filter(|call| call.level == level)
150            .cloned()
151            .collect::<Vec<_>>();
152        if calls.is_empty() {
153            continue;
154        }
155        let projections = calls
156            .iter()
157            .map(|call| {
158                (
159                    ProjectionTarget::Internal(call.placeholder),
160                    ScalarExpr::InternalColumn(call.placeholder),
161                )
162            })
163            .collect();
164        operator = Box::new(SetProjection::from_plan(
165            operator,
166            Arc::clone(&runtime),
167            params,
168            evaluator.clone(),
169            SetProjectionPlan { projections, calls },
170            true,
171            output_batch_size,
172        ));
173    }
174    if pass_through {
175        Ok(Box::new(
176            Project::appending_target_evaluator(operator, plan.projections, evaluator)
177                .with_memory_budget(work_mem),
178        ))
179    } else {
180        Ok(Box::new(
181            Project::with_target_evaluator(operator, plan.projections, evaluator)
182                .with_memory_budget(work_mem),
183        ))
184    }
185}
186
187mod operator;
188pub use operator::SetProjection;