Skip to main content

uqa_execution/relational/
project.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Scalar projection and star expansion.
8
9use uqa_core::Value;
10
11use super::{
12    BackwardScanSupport, Batch, DefaultExpressionEvaluator, ExecResult, PhysicalOperator,
13    PhysicalScanDirection, RowSchema, SQLParam, ScalarExpr, SharedExpressionEvaluator,
14};
15use crate::batch::ProjectedSlot;
16use crate::spill::{SpillBatchWriter, SpillDrain};
17
18pub use uqa_sql::plan::ProjectionTarget;
19
20#[cfg(test)]
21mod tests;
22
23/// Per-row scalar projection. Each `(alias, expr)` pair is evaluated
24/// against the input row and written under `alias` in the output. The
25/// child schema is replaced with the output aliases.
26pub struct Project<'a> {
27    child: Box<dyn PhysicalOperator + 'a>,
28    input_pending: crate::physical::demand::PendingRows,
29    computed: crate::scalar::PreparedExpressions<Vec<ScalarExpr>>,
30    evaluator: SharedExpressionEvaluator<'a>,
31    schema: RowSchema,
32    ordering: Vec<crate::PhysicalOrder>,
33    work_mem: Option<usize>,
34    pending: Option<SpillDrain>,
35}
36
37fn projection_layout(
38    input: &RowSchema,
39    projections: Vec<(ProjectionTarget, ScalarExpr)>,
40    evaluator: &SharedExpressionEvaluator<'_>,
41    pass_through: bool,
42) -> (RowSchema, Vec<ScalarExpr>) {
43    let mut projected = Vec::new();
44    let mut projected_internal = Vec::new();
45    let mut computed = Vec::new();
46    for (target, expression) in projections {
47        if let ScalarExpr::QualifiedStar(qualifier) = &expression {
48            let ProjectionTarget::Column(_) = target else {
49                unreachable!("an internal projection target cannot expand a qualified star");
50            };
51            if pass_through {
52                continue;
53            }
54            for (column, logical, _, ty) in input.qualified_star_position_layout(qualifier) {
55                if logical.is_some_and(|position| !evaluator.star_position_visible(input, position))
56                {
57                    continue;
58                }
59                let slot = logical
60                    .and_then(|logical| input.physical_slot(logical))
61                    .or_else(|| {
62                        input.physical_slot_for_identity(&crate::ColumnIdentity::qualified(
63                            qualifier, &column,
64                        ))
65                    });
66                let collation = logical.map_or_else(
67                    || input.qualified_collation(qualifier, &column),
68                    |position| input.column_collation(position),
69                );
70                projected.push((
71                    column,
72                    ty,
73                    ProjectedSlot::BoundInput {
74                        physical: slot,
75                        collation,
76                    },
77                ));
78            }
79            continue;
80        }
81        if matches!(expression, ScalarExpr::Star) {
82            let ProjectionTarget::Column(_) = target else {
83                unreachable!("an internal projection target cannot expand a star");
84            };
85            if pass_through {
86                continue;
87            }
88            for (logical, column) in input.iter().enumerate() {
89                if !evaluator.star_position_visible(input, logical) {
90                    continue;
91                }
92                projected.push((
93                    input.public_name(logical).unwrap_or(column).to_string(),
94                    input.column_type(logical).cloned(),
95                    ProjectedSlot::BoundInput {
96                        physical: input.physical_slot(logical),
97                        collation: input.column_collation(logical),
98                    },
99                ));
100            }
101            continue;
102        }
103
104        let ty = evaluator.expression_type(&expression, input).ok().flatten();
105        let source = if let Some(source) = input.projection_input(&expression) {
106            source
107        } else {
108            let position = computed.len();
109            let collation = input.input_collation(&expression);
110            computed.push(expression);
111            ProjectedSlot::Computed {
112                position,
113                collation,
114            }
115        };
116        match target {
117            ProjectionTarget::Column(name) => projected.push((name, ty, source)),
118            ProjectionTarget::Internal(column) => {
119                projected_internal.push((column, ty, source));
120            }
121        }
122    }
123    let computed_count = computed.len();
124    (
125        RowSchema::project_with_sources(
126            input,
127            projected,
128            projected_internal,
129            computed_count,
130            pass_through,
131        ),
132        computed,
133    )
134}
135
136impl Project<'static> {
137    pub fn new(
138        child: Box<dyn PhysicalOperator>,
139        projections: Vec<(String, ScalarExpr)>,
140        params: Vec<SQLParam>,
141    ) -> Self {
142        Self::with_evaluator(
143            child,
144            projections,
145            DefaultExpressionEvaluator::shared(params),
146        )
147    }
148
149    pub fn with_targets(
150        child: Box<dyn PhysicalOperator>,
151        projections: Vec<(ProjectionTarget, ScalarExpr)>,
152        params: Vec<SQLParam>,
153    ) -> Self {
154        Self::with_target_evaluator(
155            child,
156            projections,
157            DefaultExpressionEvaluator::shared(params),
158        )
159    }
160
161    /// Variant that keeps every input column in the output and appends
162    /// the projections at the end. Used by aggregate / window paths.
163    pub fn appending(
164        child: Box<dyn PhysicalOperator>,
165        projections: Vec<(String, ScalarExpr)>,
166        params: Vec<SQLParam>,
167    ) -> Self {
168        Self::appending_with_evaluator(
169            child,
170            projections,
171            DefaultExpressionEvaluator::shared(params),
172        )
173    }
174
175    pub fn appending_targets(
176        child: Box<dyn PhysicalOperator>,
177        projections: Vec<(ProjectionTarget, ScalarExpr)>,
178        params: Vec<SQLParam>,
179    ) -> Self {
180        Self::appending_target_evaluator(
181            child,
182            projections,
183            DefaultExpressionEvaluator::shared(params),
184        )
185    }
186}
187
188impl<'a> Project<'a> {
189    pub fn with_evaluator(
190        child: Box<dyn PhysicalOperator + 'a>,
191        projections: Vec<(String, ScalarExpr)>,
192        evaluator: SharedExpressionEvaluator<'a>,
193    ) -> Self {
194        Self::with_target_evaluator(
195            child,
196            projections
197                .into_iter()
198                .map(|(name, expression)| (ProjectionTarget::Column(name), expression))
199                .collect(),
200            evaluator,
201        )
202    }
203
204    pub fn with_target_evaluator(
205        child: Box<dyn PhysicalOperator + 'a>,
206        projections: Vec<(ProjectionTarget, ScalarExpr)>,
207        evaluator: SharedExpressionEvaluator<'a>,
208    ) -> Self {
209        let projections = projections
210            .into_iter()
211            .map(|(target, expression)| {
212                (
213                    target,
214                    evaluator.bind_type_introspection(expression, child.row_schema()),
215                )
216            })
217            .collect::<Vec<_>>();
218        let (schema, computed) =
219            projection_layout(child.row_schema(), projections, &evaluator, false);
220        Self {
221            child,
222            input_pending: crate::physical::demand::PendingRows::default(),
223            computed: crate::scalar::PreparedExpressions::scalars(computed),
224            evaluator,
225            schema,
226            ordering: Vec::new(),
227            work_mem: None,
228            pending: None,
229        }
230    }
231
232    pub fn appending_with_evaluator(
233        child: Box<dyn PhysicalOperator + 'a>,
234        projections: Vec<(String, ScalarExpr)>,
235        evaluator: SharedExpressionEvaluator<'a>,
236    ) -> Self {
237        Self::appending_target_evaluator(
238            child,
239            projections
240                .into_iter()
241                .map(|(name, expression)| (ProjectionTarget::Column(name), expression))
242                .collect(),
243            evaluator,
244        )
245    }
246
247    pub fn appending_target_evaluator(
248        child: Box<dyn PhysicalOperator + 'a>,
249        projections: Vec<(ProjectionTarget, ScalarExpr)>,
250        evaluator: SharedExpressionEvaluator<'a>,
251    ) -> Self {
252        let projections = projections
253            .into_iter()
254            .map(|(target, expression)| {
255                (
256                    target,
257                    evaluator.bind_type_introspection(expression, child.row_schema()),
258                )
259            })
260            .collect::<Vec<_>>();
261        let ordering = child
262            .output_ordering()
263            .iter()
264            .take_while(|order| {
265                projections.iter().all(|(target, expression)| {
266                    let ProjectionTarget::Column(name) = target else {
267                        return true;
268                    };
269                    child
270                        .row_schema()
271                        .columns()
272                        .iter()
273                        .position(|column| column == name)
274                        != Some(order.position)
275                        || matches!(expression, ScalarExpr::Star | ScalarExpr::QualifiedStar(_))
276                        || crate::order_expression_position(child.row_schema(), expression)
277                            == Some(order.position)
278                })
279            })
280            .cloned()
281            .collect();
282        let (schema, computed) =
283            projection_layout(child.row_schema(), projections, &evaluator, true);
284        Self {
285            child,
286            input_pending: crate::physical::demand::PendingRows::default(),
287            computed: crate::scalar::PreparedExpressions::scalars(computed),
288            evaluator,
289            schema,
290            ordering,
291            work_mem: None,
292            pending: None,
293        }
294    }
295
296    /// Retain a scalar evaluation boundary without splitting batches for a slot-only projection.
297    pub(crate) fn with_row_at_a_time_input(mut self) -> Self {
298        if !self.computed.is_empty() {
299            self.child = Box::new(crate::query::row_at_a_time::RowAtATime::new(self.child));
300        }
301        self
302    }
303
304    /// Bound evaluated output while retaining the original input-batch evaluation boundary.
305    pub fn with_memory_budget(mut self, bytes: usize) -> Self {
306        self.work_mem = Some(bytes);
307        self
308    }
309
310    fn prepare_batch(&mut self, batch: Batch) -> ExecResult<Option<Batch>> {
311        let Some(budget) = self
312            .work_mem
313            .filter(|_| !self.computed.is_empty() && batch.rows.len() > 1)
314        else {
315            return self.project_batch(batch).map(Some);
316        };
317        self.project_spilled_batch(batch, budget)
318    }
319
320    fn project_spilled_batch(&mut self, batch: Batch, budget: usize) -> ExecResult<Option<Batch>> {
321        // Finish every expression in this input batch before exposing its first result. Only the storage of those evaluated rows changes.
322        let mut output = crate::SpillBuffer::new(budget / 2);
323        let mut writer = SpillBatchWriter::new(self.schema.clone())?;
324        for row in batch.rows {
325            let values = self.project_values(&batch.schema, &row)?;
326            writer.push(&mut output, row.append_values(values))?;
327        }
328        writer.finish(&mut output)?;
329        self.pending = Some(output.drain()?);
330        self.next_pending()
331    }
332
333    fn next_pending(&mut self) -> ExecResult<Option<Batch>> {
334        if self.pending.is_some() {
335            if let Err(error) = uqa_sql::expr::check_statement_cancellation() {
336                self.pending = None;
337                return Err(uqa_sql::SQLError::from(error).into());
338            }
339        }
340        let batch = self.pending.as_mut().and_then(Iterator::next).transpose();
341        if !matches!(batch, Ok(Some(_))) {
342            self.pending = None;
343        }
344        batch
345    }
346
347    fn project_values(
348        &self,
349        schema: &RowSchema,
350        row: &crate::PhysicalRow,
351    ) -> ExecResult<Vec<Value>> {
352        let mut values = Vec::with_capacity(self.computed.len());
353        for expression in self.computed.iter() {
354            values.push(self.evaluator.evaluate_physical_with_function_states(
355                expression,
356                schema,
357                row,
358                self.computed.calls(),
359            )?);
360        }
361        Ok(values)
362    }
363
364    fn project_batch(&self, batch: Batch) -> ExecResult<Batch> {
365        if self.computed.is_empty() {
366            return Ok(Batch::from_physical_rows(self.schema.clone(), batch.rows));
367        }
368        let mut out = Vec::with_capacity(batch.rows.len());
369        for row in batch.rows {
370            let values = self.project_values(&batch.schema, &row)?;
371            out.push(row.append_values(values));
372        }
373        Ok(Batch::from_physical_rows(self.schema.clone(), out))
374    }
375}
376
377impl Project<'_> {
378    fn pull(&mut self, demand: Option<std::num::NonZeroUsize>) -> ExecResult<Option<Batch>> {
379        if let Some(batch) = self.next_pending()? {
380            return Ok(Some(batch));
381        }
382        let Some(batch) = self.input_pending.pull(self.child.as_mut(), demand)? else {
383            return Ok(None);
384        };
385        self.prepare_batch(batch)
386    }
387}
388
389impl PhysicalOperator for Project<'_> {
390    fn row_schema(&self) -> &RowSchema {
391        &self.schema
392    }
393
394    fn supports_batched_consumption(&self) -> bool {
395        self.computed.is_empty() && self.child.supports_batched_consumption()
396    }
397
398    fn collect_materialized(
399        &mut self,
400        sink: &mut crate::query::output::MaterializedResultSink<'_>,
401    ) -> ExecResult<bool> {
402        if !self.computed.is_empty()
403            || self.schema.physical_width() != self.child.row_schema().physical_width()
404        {
405            return Ok(false);
406        }
407        self.child.collect_materialized(sink)
408    }
409
410    fn output_ordering(&self) -> &[crate::PhysicalOrder] {
411        &self.ordering
412    }
413
414    fn backward_scan_support(&self) -> BackwardScanSupport {
415        let child = self.child.backward_scan_support();
416        if child == BackwardScanSupport::Native || self.computed.is_empty() {
417            child
418        } else {
419            BackwardScanSupport::Unsupported
420        }
421    }
422
423    fn open(&mut self) -> ExecResult<()> {
424        self.input_pending.clear();
425        self.pending = None;
426        self.child.open()
427    }
428
429    fn next(&mut self) -> ExecResult<Option<Batch>> {
430        self.pull(None)
431    }
432
433    fn next_with_demand(&mut self, rows: std::num::NonZeroUsize) -> ExecResult<Option<Batch>> {
434        self.pull(Some(rows))
435    }
436
437    fn next_direction(&mut self, direction: PhysicalScanDirection) -> ExecResult<Option<Batch>> {
438        if let Some(batch) = self.next_pending()? {
439            return Ok(Some(batch));
440        }
441        let Some(batch) = self.child.next_direction(direction)? else {
442            return Ok(None);
443        };
444        self.prepare_batch(batch)
445    }
446
447    fn rewind(&mut self) -> ExecResult<()> {
448        self.input_pending.clear();
449        self.pending = None;
450        self.child.rewind()
451    }
452
453    fn close(&mut self) -> ExecResult<()> {
454        self.input_pending.clear();
455        self.pending = None;
456        self.child.close()
457    }
458}
459
460// -------------------------------------------------------------------------
461// Sort
462// -------------------------------------------------------------------------