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                Ok(())
120            }),
121            routine_descriptions,
122            schema,
123            evaluation_schema,
124            pass_through,
125            output_batch_size,
126            input: Vec::new().into_iter(),
127            expansion: None,
128            exhausted: false,
129        }
130    }
131
132    fn next_input(&mut self, demanded: bool) -> ExecResult<Option<OwnedPhysicalRow>> {
133        loop {
134            if let Some(row) = self.input.next() {
135                return Ok(Some(row));
136            }
137            let Some(batch) = (if demanded {
138                self.child.next_with_demand(crate::physical::demand::ONE)?
139            } else {
140                self.child.next()?
141            }) else {
142                return Ok(None);
143            };
144            self.input = batch.into_owned_rows().into_iter();
145        }
146    }
147
148    fn call_state(
149        &self,
150        call: &SetFunctionCall,
151        row: &OwnedPhysicalRow,
152        descriptions: &uqa_sql::routines::invocation::descriptions::RoutineCallDescriptions,
153    ) -> ExecResult<SetFunctionState> {
154        let identity = call.name.to_ascii_lowercase();
155        if uqa_sql::semantics::builtin_function_dispatch_name(&identity) == "unnest"
156            && call.args.len() != 1
157            && call.binding.as_ref().is_none_or(|binding| binding.builtin)
158        {
159            return Err(SQLError::UnknownFunction(
160                "unnest with multiple arrays is only valid in FROM".into(),
161            )
162            .into());
163        }
164        let runtime = self.runtime.as_ref();
165        let binding = call.binding.as_ref();
166        let has_sql_function =
167            runtime.has_user_function_with_descriptions(&call.name, binding, descriptions)?;
168        if !runtime.has_registered_table_function(&identity) && has_sql_function {
169            let subqueries = PlanSubqueryArena::new(runtime.subquery_plans(), Some(runtime));
170            let context = ScalarEvalContext::from_row_lookup(row, self.params)
171                .with_function_hook(runtime)
172                .with_function_states(self.plan.calls())
173                .with_subquery_runner(&subqueries)
174                .with_physical_outer_row(&row.schema, &row.row);
175            let arguments = eval_call_arguments(&call.args, &context)?;
176            let result = match runtime.invoke_projection_function(
177                &call.name,
178                binding,
179                &arguments,
180                descriptions,
181            )? {
182                crate::routines::invocation::RoutineProjectionResult::Scalar(value) => {
183                    return Ok(SetFunctionState::Scalar(value));
184                }
185                crate::routines::invocation::RoutineProjectionResult::Table(result) => result,
186            };
187            let output = super::registered_table_function_rows(&call.name, result, None, &[])?;
188            return Ok(SetFunctionState::Set {
189                columns: output.columns,
190                rows: output.rows,
191                exhausted: false,
192            });
193        }
194        let table_call = super::TableFunctionCall {
195            name: &call.name,
196            binding,
197            output_name: &call.name,
198            relations: None,
199            args: &call.args,
200            function_states: Some(self.plan.calls()),
201            routine_descriptions: Some(descriptions),
202            alias: None,
203            column_aliases: &[],
204            ordinality: false,
205            column_types: &[],
206        };
207        let output = runtime.table_function_rows(table_call, self.params, Some(row))?;
208        Ok(SetFunctionState::Set {
209            columns: output.columns,
210            rows: output.rows,
211            exhausted: false,
212        })
213    }
214
215    fn start_expansion(&self, input: OwnedPhysicalRow) -> ExecResult<SetExpansion> {
216        let mut calls = Vec::with_capacity(self.plan.calls.len());
217        for (call, descriptions) in self.plan.calls.iter().zip(&self.routine_descriptions) {
218            match self.call_state(call, &input, descriptions) {
219                Ok(state) => calls.push(state),
220                Err(error) => {
221                    return crate::physical::with_cleanup(
222                        Err(error),
223                        super::close_calls(&mut calls),
224                        "close earlier set-returning calls after initialization failure",
225                    )
226                }
227            }
228        }
229        let has_set = calls
230            .iter()
231            .any(|call| matches!(call, SetFunctionState::Set { .. }));
232        Ok(SetExpansion {
233            input,
234            calls,
235            has_set,
236            scalar_emitted: false,
237        })
238    }
239
240    fn next_projected(&mut self) -> ExecResult<Option<PhysicalRow>> {
241        let Some(expansion) = self.expansion.as_mut() else {
242            return Ok(None);
243        };
244        let Some(values) = expansion.next_values()? else {
245            return Ok(None);
246        };
247        let evaluation_row = expansion.input.row.clone().append_values(values);
248        if self.pass_through {
249            let mut output = (0..expansion.input.schema.physical_width())
250                .map(RowProjectionValue::InputSlot)
251                .collect::<Vec<_>>();
252            for (_, expression) in self
253                .plan
254                .projections
255                .iter()
256                .filter(|(_, expression)| !matches!(expression, ScalarExpr::Star))
257            {
258                if let Some(position) =
259                    crate::order_expression_position(&self.evaluation_schema, expression)
260                {
261                    output.push(self.evaluation_schema.physical_slot(position).map_or(
262                        RowProjectionValue::Owned(Value::Null),
263                        RowProjectionValue::InputSlot,
264                    ));
265                } else {
266                    output.push(RowProjectionValue::Owned(
267                        self.evaluator.evaluate_physical_with_function_states(
268                            expression,
269                            &self.evaluation_schema,
270                            &evaluation_row,
271                            self.plan.calls(),
272                        )?,
273                    ));
274                }
275            }
276            return Ok(Some(evaluation_row.project_with_values(output)));
277        }
278
279        let mut output = Vec::with_capacity(self.schema.len());
280        for (_, expression) in &self.plan.projections {
281            if matches!(expression, ScalarExpr::Star) {
282                for position in 0..expansion.input.schema.len() {
283                    if self
284                        .evaluator
285                        .star_position_visible(&expansion.input.schema, position)
286                    {
287                        output.push(expansion.input.schema.physical_slot(position).map_or(
288                            RowProjectionValue::Owned(Value::Null),
289                            RowProjectionValue::InputSlot,
290                        ));
291                    }
292                }
293            } else if let Some(position) =
294                crate::order_expression_position(&self.evaluation_schema, expression)
295            {
296                output.push(self.evaluation_schema.physical_slot(position).map_or(
297                    RowProjectionValue::Owned(Value::Null),
298                    RowProjectionValue::InputSlot,
299                ));
300            } else {
301                output.push(RowProjectionValue::Owned(
302                    self.evaluator.evaluate_physical_with_function_states(
303                        expression,
304                        &self.evaluation_schema,
305                        &evaluation_row,
306                        self.plan.calls(),
307                    )?,
308                ));
309            }
310        }
311        Ok(Some(
312            evaluation_row
313                .project_with_values(output)
314                .without_lock_origins(),
315        ))
316    }
317}
318
319impl SetProjection<'_> {
320    fn close_expansion(&mut self) -> ExecResult<()> {
321        self.expansion
322            .take()
323            .map_or(Ok(()), |mut expansion| expansion.close())
324    }
325
326    fn pull(&mut self, demand: Option<std::num::NonZeroUsize>) -> ExecResult<Option<Batch>> {
327        let batch_size = demand.map_or(self.output_batch_size, |rows| {
328            rows.get().min(self.output_batch_size)
329        });
330        if self.exhausted && self.expansion.is_none() {
331            return Ok(None);
332        }
333        let mut output = Vec::with_capacity(batch_size);
334        while output.len() < batch_size {
335            if let Some(row) = self.next_projected()? {
336                output.push(row);
337                continue;
338            }
339            self.close_expansion()?;
340            if let Some(input) = self.next_input(demand.is_some())? {
341                self.expansion = Some(self.start_expansion(input)?);
342            } else {
343                self.exhausted = true;
344                break;
345            }
346        }
347        if output.is_empty() {
348            return Ok(None);
349        }
350        Ok(Some(Batch::from_physical_rows(self.schema.clone(), output)))
351    }
352}
353
354impl PhysicalOperator for SetProjection<'_> {
355    fn row_schema(&self) -> &RowSchema {
356        &self.schema
357    }
358
359    fn open(&mut self) -> ExecResult<()> {
360        self.input = Vec::new().into_iter();
361        self.close_expansion()?;
362        self.exhausted = false;
363        self.child.open()
364    }
365
366    fn next(&mut self) -> ExecResult<Option<Batch>> {
367        self.pull(None)
368    }
369
370    fn next_with_demand(&mut self, rows: std::num::NonZeroUsize) -> ExecResult<Option<Batch>> {
371        self.pull(Some(rows))
372    }
373
374    fn close(&mut self) -> ExecResult<()> {
375        self.input = Vec::new().into_iter();
376        let expansion = self.close_expansion();
377        self.exhausted = true;
378        crate::physical::with_cleanup(expansion, self.child.close(), "close set projection input")
379    }
380}