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