Skip to main content

uqa_execution/query/set_projection/
operator.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Physical set-returning projection operator.
8
9use crate::RowProjectionValue;
10use uqa_sql::routines::invocation::descriptions::RoutineCallDescriptions;
11
12use super::{
13    eval_call_arguments, Arc, Batch, ColumnType, ExecResult, OwnedPhysicalRow, PhysicalOperator,
14    PhysicalRow, PlanSubqueryArena, ProjectionTarget, RowSchema, SQLError, SQLParam,
15    ScalarEvalContext, ScalarExpr, SetExpansion, SetFunctionCall, SetFunctionRuntime,
16    SetFunctionState, SetProjectionPlan, SharedExpressionEvaluator, Value,
17};
18
19pub struct SetProjection<'a> {
20    child: Box<dyn PhysicalOperator + 'a>,
21    runtime: Arc<dyn SetFunctionRuntime + 'a>,
22    params: &'a [SQLParam],
23    evaluator: SharedExpressionEvaluator<'a>,
24    plan: crate::scalar::PreparedExpressions<SetProjectionPlan>,
25    routine_descriptions: Vec<RoutineCallDescriptions>,
26    schema: RowSchema,
27    evaluation_schema: RowSchema,
28    pass_through: bool,
29    output_batch_size: usize,
30    input: std::vec::IntoIter<OwnedPhysicalRow>,
31    expansion: Option<SetExpansion>,
32    exhausted: bool,
33}
34
35fn set_call_output_type(
36    resolver: &dyn crate::FunctionTypeResolver,
37    call: &SetFunctionCall,
38    input_schema: &RowSchema,
39    params: &[SQLParam],
40) -> Option<ColumnType> {
41    let expression = ScalarExpr::Func {
42        order_syntax: uqa_sql::ast::FunctionOrderSyntax::Ordinary,
43        name: call.name.clone(),
44        binding: call.binding.clone(),
45        args: call.args.clone(),
46        distinct: false,
47        order_by: Vec::new(),
48        filter: None,
49    };
50    crate::scalar_type_with_resolver(&expression, input_schema, params, resolver)
51        .ok()
52        .flatten()
53}
54
55impl<'a> SetProjection<'a> {
56    pub fn from_plan(
57        child: Box<dyn PhysicalOperator + 'a>,
58        runtime: Arc<dyn SetFunctionRuntime + 'a>,
59        params: &'a [SQLParam],
60        evaluator: SharedExpressionEvaluator<'a>,
61        mut plan: SetProjectionPlan,
62        pass_through: bool,
63        output_batch_size: usize,
64    ) -> Self {
65        for call in &mut plan.calls {
66            for argument in &mut call.args {
67                *argument = evaluator.bind_type_introspection(argument.clone(), child.row_schema());
68            }
69        }
70        let projections = &plan.projections;
71        let resolver = runtime.as_ref();
72        let call_types = plan
73            .calls
74            .iter()
75            .map(|call| set_call_output_type(resolver, call, child.row_schema(), params))
76            .collect::<Vec<_>>();
77        let appended = projections
78            .iter()
79            .zip(&call_types)
80            .filter(|((_, expression), _)| !matches!(expression, ScalarExpr::Star))
81            .map(|((target, _), ty)| {
82                let ProjectionTarget::Internal(column) = target else {
83                    unreachable!("set-call expansion target must be an internal attribute");
84                };
85                (*column, ty.clone())
86            })
87            .collect::<Vec<_>>();
88        let schema = if pass_through {
89            RowSchema::append_internal_typed(child.row_schema(), &appended)
90        } else {
91            unreachable!("set-call expansion always preserves its input")
92        };
93        let evaluation_columns = plan
94            .calls
95            .iter()
96            .zip(call_types)
97            .map(|(call, ty)| (call.placeholder, ty))
98            .collect::<Vec<_>>();
99        let evaluation_schema =
100            RowSchema::append_internal_typed(child.row_schema(), &evaluation_columns);
101        let output_batch_size = output_batch_size.max(1);
102        let routine_descriptions = (0..plan.calls.len())
103            .map(|_| RoutineCallDescriptions::default())
104            .collect();
105        Self {
106            child,
107            runtime,
108            params,
109            evaluator,
110            plan: crate::scalar::PreparedExpressions::new(plan, |plan, visit| {
111                for call in &plan.calls {
112                    for argument in &call.args {
113                        visit(argument);
114                    }
115                }
116                for (_, expression) in &plan.projections {
117                    visit(expression);
118                }
119            }),
120            routine_descriptions,
121            schema,
122            evaluation_schema,
123            pass_through,
124            output_batch_size,
125            input: Vec::new().into_iter(),
126            expansion: None,
127            exhausted: false,
128        }
129    }
130
131    fn next_input(&mut self, demanded: bool) -> ExecResult<Option<OwnedPhysicalRow>> {
132        loop {
133            if let Some(row) = self.input.next() {
134                return Ok(Some(row));
135            }
136            let Some(batch) = (if demanded {
137                self.child.next_with_demand(crate::physical::demand::ONE)?
138            } else {
139                self.child.next()?
140            }) else {
141                return Ok(None);
142            };
143            self.input = batch.into_owned_rows().into_iter();
144        }
145    }
146
147    fn call_state(
148        &self,
149        call: &SetFunctionCall,
150        row: &OwnedPhysicalRow,
151        descriptions: &uqa_sql::routines::invocation::descriptions::RoutineCallDescriptions,
152    ) -> ExecResult<SetFunctionState> {
153        let identity = call.name.to_ascii_lowercase();
154        if uqa_sql::semantics::builtin_function_dispatch_name(&identity) == "unnest"
155            && call.args.len() != 1
156            && call.binding.as_ref().is_none_or(|binding| binding.builtin)
157        {
158            return Err(SQLError::UnknownFunction(
159                "unnest with multiple arrays is only valid in FROM".into(),
160            )
161            .into());
162        }
163        let runtime = self.runtime.as_ref();
164        let binding = call.binding.as_ref();
165        let has_sql_function =
166            runtime.has_user_function_with_descriptions(&call.name, binding, descriptions)?;
167        if !runtime.has_registered_table_function(&identity) && has_sql_function {
168            let subqueries = PlanSubqueryArena::new(runtime.subquery_plans(), Some(runtime));
169            let context = ScalarEvalContext::from_row_lookup(row, self.params)
170                .with_function_hook(runtime)
171                .with_function_states(self.plan.calls())
172                .with_subquery_runner(&subqueries)
173                .with_physical_outer_row(&row.schema, &row.row);
174            let arguments = eval_call_arguments(&call.args, &context)?;
175            let result = match runtime.invoke_projection_function(
176                &call.name,
177                binding,
178                &arguments,
179                descriptions,
180            )? {
181                crate::routines::invocation::RoutineProjectionResult::Scalar(value) => {
182                    return Ok(SetFunctionState::Scalar(value));
183                }
184                crate::routines::invocation::RoutineProjectionResult::Table(result) => result,
185            };
186            let output = super::registered_table_function_rows(&call.name, result, None, &[])?;
187            return Ok(SetFunctionState::Set {
188                columns: output.columns,
189                rows: output.rows,
190                exhausted: false,
191            });
192        }
193        let table_call = super::TableFunctionCall {
194            name: &call.name,
195            binding,
196            output_name: &call.name,
197            relations: None,
198            args: &call.args,
199            function_states: Some(self.plan.calls()),
200            routine_descriptions: Some(descriptions),
201            alias: None,
202            column_aliases: &[],
203            ordinality: false,
204            column_types: &[],
205        };
206        let output = runtime.table_function_rows(table_call, self.params, Some(row))?;
207        Ok(SetFunctionState::Set {
208            columns: output.columns,
209            rows: output.rows,
210            exhausted: false,
211        })
212    }
213
214    fn start_expansion(&self, input: OwnedPhysicalRow) -> ExecResult<SetExpansion> {
215        let mut calls = Vec::with_capacity(self.plan.calls.len());
216        for (call, descriptions) in self.plan.calls.iter().zip(&self.routine_descriptions) {
217            match self.call_state(call, &input, descriptions) {
218                Ok(state) => calls.push(state),
219                Err(error) => {
220                    return crate::physical::with_cleanup(
221                        Err(error),
222                        super::close_calls(&mut calls),
223                        "close earlier set-returning calls after initialization failure",
224                    )
225                }
226            }
227        }
228        let has_set = calls
229            .iter()
230            .any(|call| matches!(call, SetFunctionState::Set { .. }));
231        Ok(SetExpansion {
232            input,
233            calls,
234            has_set,
235            scalar_emitted: false,
236        })
237    }
238
239    fn next_projected(&mut self) -> ExecResult<Option<PhysicalRow>> {
240        let Some(expansion) = self.expansion.as_mut() else {
241            return Ok(None);
242        };
243        let Some(values) = expansion.next_values()? else {
244            return Ok(None);
245        };
246        let evaluation_row = expansion.input.row.clone().append_values(values);
247        if self.pass_through {
248            let mut output = (0..expansion.input.schema.physical_width())
249                .map(RowProjectionValue::InputSlot)
250                .collect::<Vec<_>>();
251            for (_, expression) in self
252                .plan
253                .projections
254                .iter()
255                .filter(|(_, expression)| !matches!(expression, ScalarExpr::Star))
256            {
257                if let Some(position) =
258                    crate::order_expression_position(&self.evaluation_schema, expression)
259                {
260                    output.push(self.evaluation_schema.physical_slot(position).map_or(
261                        RowProjectionValue::Owned(Value::Null),
262                        RowProjectionValue::InputSlot,
263                    ));
264                } else {
265                    output.push(RowProjectionValue::Owned(
266                        self.evaluator.evaluate_physical_with_function_states(
267                            expression,
268                            &self.evaluation_schema,
269                            &evaluation_row,
270                            self.plan.calls(),
271                        )?,
272                    ));
273                }
274            }
275            return Ok(Some(evaluation_row.project_with_values(output)));
276        }
277
278        let mut output = Vec::with_capacity(self.schema.len());
279        for (_, expression) in &self.plan.projections {
280            if matches!(expression, ScalarExpr::Star) {
281                for position in 0..expansion.input.schema.len() {
282                    if self
283                        .evaluator
284                        .star_position_visible(&expansion.input.schema, position)
285                    {
286                        output.push(expansion.input.schema.physical_slot(position).map_or(
287                            RowProjectionValue::Owned(Value::Null),
288                            RowProjectionValue::InputSlot,
289                        ));
290                    }
291                }
292            } else if let Some(position) =
293                crate::order_expression_position(&self.evaluation_schema, expression)
294            {
295                output.push(self.evaluation_schema.physical_slot(position).map_or(
296                    RowProjectionValue::Owned(Value::Null),
297                    RowProjectionValue::InputSlot,
298                ));
299            } else {
300                output.push(RowProjectionValue::Owned(
301                    self.evaluator.evaluate_physical_with_function_states(
302                        expression,
303                        &self.evaluation_schema,
304                        &evaluation_row,
305                        self.plan.calls(),
306                    )?,
307                ));
308            }
309        }
310        Ok(Some(
311            evaluation_row
312                .project_with_values(output)
313                .without_lock_origins(),
314        ))
315    }
316}
317
318impl SetProjection<'_> {
319    fn close_expansion(&mut self) -> ExecResult<()> {
320        self.expansion
321            .take()
322            .map_or(Ok(()), |mut expansion| expansion.close())
323    }
324
325    fn pull(&mut self, demand: Option<std::num::NonZeroUsize>) -> ExecResult<Option<Batch>> {
326        let batch_size = demand.map_or(self.output_batch_size, |rows| {
327            rows.get().min(self.output_batch_size)
328        });
329        if self.exhausted && self.expansion.is_none() {
330            return Ok(None);
331        }
332        let mut output = Vec::with_capacity(batch_size);
333        while output.len() < batch_size {
334            if let Some(row) = self.next_projected()? {
335                output.push(row);
336                continue;
337            }
338            self.close_expansion()?;
339            if let Some(input) = self.next_input(demand.is_some())? {
340                self.expansion = Some(self.start_expansion(input)?);
341            } else {
342                self.exhausted = true;
343                break;
344            }
345        }
346        if output.is_empty() {
347            return Ok(None);
348        }
349        Ok(Some(Batch::from_physical_rows(self.schema.clone(), output)))
350    }
351}
352
353impl PhysicalOperator for SetProjection<'_> {
354    fn row_schema(&self) -> &RowSchema {
355        &self.schema
356    }
357
358    fn open(&mut self) -> ExecResult<()> {
359        self.input = Vec::new().into_iter();
360        self.close_expansion()?;
361        self.exhausted = false;
362        self.child.open()
363    }
364
365    fn next(&mut self) -> ExecResult<Option<Batch>> {
366        self.pull(None)
367    }
368
369    fn next_with_demand(&mut self, rows: std::num::NonZeroUsize) -> ExecResult<Option<Batch>> {
370        self.pull(Some(rows))
371    }
372
373    fn close(&mut self) -> ExecResult<()> {
374        self.input = Vec::new().into_iter();
375        let expansion = self.close_expansion();
376        self.exhausted = true;
377        crate::physical::with_cleanup(expansion, self.child.close(), "close set projection input")
378    }
379}