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;
16
17pub use uqa_sql::plan::ProjectionTarget;
18
19/// Per-row scalar projection. Each `(alias, expr)` pair is evaluated
20/// against the input row and written under `alias` in the output. The
21/// child schema is replaced with the output aliases.
22pub struct Project<'a> {
23    child: Box<dyn PhysicalOperator + 'a>,
24    computed: crate::scalar::PreparedExpressions<Vec<ScalarExpr>>,
25    evaluator: SharedExpressionEvaluator<'a>,
26    schema: RowSchema,
27    ordering: Vec<crate::PhysicalOrder>,
28}
29
30fn projection_layout(
31    input: &RowSchema,
32    projections: Vec<(ProjectionTarget, ScalarExpr)>,
33    evaluator: &SharedExpressionEvaluator<'_>,
34    pass_through: bool,
35) -> (RowSchema, Vec<ScalarExpr>) {
36    let mut projected = Vec::new();
37    let mut projected_internal = Vec::new();
38    let mut computed = Vec::new();
39    for (target, expression) in projections {
40        if let ScalarExpr::QualifiedStar(qualifier) = &expression {
41            let ProjectionTarget::Column(_) = target else {
42                unreachable!("an internal projection target cannot expand a qualified star");
43            };
44            if pass_through {
45                continue;
46            }
47            for (column, logical, _, ty) in input.qualified_star_position_layout(qualifier) {
48                if logical.is_some_and(|position| !evaluator.star_position_visible(input, position))
49                {
50                    continue;
51                }
52                let slot = logical
53                    .and_then(|logical| input.physical_slot(logical))
54                    .or_else(|| {
55                        input.physical_slot_for_identity(&crate::ColumnIdentity::qualified(
56                            qualifier, &column,
57                        ))
58                    });
59                let collation = logical.map_or_else(
60                    || input.qualified_collation(qualifier, &column),
61                    |position| input.column_collation(position),
62                );
63                projected.push((
64                    column,
65                    ty,
66                    ProjectedSlot::BoundInput {
67                        physical: slot,
68                        collation,
69                    },
70                ));
71            }
72            continue;
73        }
74        if matches!(expression, ScalarExpr::Star) {
75            let ProjectionTarget::Column(_) = target else {
76                unreachable!("an internal projection target cannot expand a star");
77            };
78            if pass_through {
79                continue;
80            }
81            for (logical, column) in input.iter().enumerate() {
82                if !evaluator.star_position_visible(input, logical) {
83                    continue;
84                }
85                projected.push((
86                    input.public_name(logical).unwrap_or(column).to_string(),
87                    input.column_type(logical).cloned(),
88                    ProjectedSlot::BoundInput {
89                        physical: input.physical_slot(logical),
90                        collation: input.column_collation(logical),
91                    },
92                ));
93            }
94            continue;
95        }
96
97        let ty = evaluator.expression_type(&expression, input).ok().flatten();
98        let source = if let Some(source) = input.projection_input(&expression) {
99            source
100        } else {
101            let position = computed.len();
102            let collation = input.input_collation(&expression);
103            computed.push(expression);
104            ProjectedSlot::Computed {
105                position,
106                collation,
107            }
108        };
109        match target {
110            ProjectionTarget::Column(name) => projected.push((name, ty, source)),
111            ProjectionTarget::Internal(column) => {
112                projected_internal.push((column, ty, source));
113            }
114        }
115    }
116    let computed_count = computed.len();
117    (
118        RowSchema::project_with_sources(
119            input,
120            projected,
121            projected_internal,
122            computed_count,
123            pass_through,
124        ),
125        computed,
126    )
127}
128
129impl Project<'static> {
130    pub fn new(
131        child: Box<dyn PhysicalOperator>,
132        projections: Vec<(String, ScalarExpr)>,
133        params: Vec<SQLParam>,
134    ) -> Self {
135        Self::with_evaluator(
136            child,
137            projections,
138            DefaultExpressionEvaluator::shared(params),
139        )
140    }
141
142    pub fn with_targets(
143        child: Box<dyn PhysicalOperator>,
144        projections: Vec<(ProjectionTarget, ScalarExpr)>,
145        params: Vec<SQLParam>,
146    ) -> Self {
147        Self::with_target_evaluator(
148            child,
149            projections,
150            DefaultExpressionEvaluator::shared(params),
151        )
152    }
153
154    /// Variant that keeps every input column in the output and appends
155    /// the projections at the end. Used by aggregate / window paths.
156    pub fn appending(
157        child: Box<dyn PhysicalOperator>,
158        projections: Vec<(String, ScalarExpr)>,
159        params: Vec<SQLParam>,
160    ) -> Self {
161        Self::appending_with_evaluator(
162            child,
163            projections,
164            DefaultExpressionEvaluator::shared(params),
165        )
166    }
167
168    pub fn appending_targets(
169        child: Box<dyn PhysicalOperator>,
170        projections: Vec<(ProjectionTarget, ScalarExpr)>,
171        params: Vec<SQLParam>,
172    ) -> Self {
173        Self::appending_target_evaluator(
174            child,
175            projections,
176            DefaultExpressionEvaluator::shared(params),
177        )
178    }
179}
180
181impl<'a> Project<'a> {
182    pub fn with_evaluator(
183        child: Box<dyn PhysicalOperator + 'a>,
184        projections: Vec<(String, ScalarExpr)>,
185        evaluator: SharedExpressionEvaluator<'a>,
186    ) -> Self {
187        Self::with_target_evaluator(
188            child,
189            projections
190                .into_iter()
191                .map(|(name, expression)| (ProjectionTarget::Column(name), expression))
192                .collect(),
193            evaluator,
194        )
195    }
196
197    pub fn with_target_evaluator(
198        child: Box<dyn PhysicalOperator + 'a>,
199        projections: Vec<(ProjectionTarget, ScalarExpr)>,
200        evaluator: SharedExpressionEvaluator<'a>,
201    ) -> Self {
202        let projections = projections
203            .into_iter()
204            .map(|(target, expression)| {
205                (
206                    target,
207                    evaluator.bind_type_introspection(expression, child.row_schema()),
208                )
209            })
210            .collect::<Vec<_>>();
211        let (schema, computed) =
212            projection_layout(child.row_schema(), projections, &evaluator, false);
213        Self {
214            child,
215            computed: crate::scalar::PreparedExpressions::scalars(computed),
216            evaluator,
217            schema,
218            ordering: Vec::new(),
219        }
220    }
221
222    pub fn appending_with_evaluator(
223        child: Box<dyn PhysicalOperator + 'a>,
224        projections: Vec<(String, ScalarExpr)>,
225        evaluator: SharedExpressionEvaluator<'a>,
226    ) -> Self {
227        Self::appending_target_evaluator(
228            child,
229            projections
230                .into_iter()
231                .map(|(name, expression)| (ProjectionTarget::Column(name), expression))
232                .collect(),
233            evaluator,
234        )
235    }
236
237    pub fn appending_target_evaluator(
238        child: Box<dyn PhysicalOperator + 'a>,
239        projections: Vec<(ProjectionTarget, ScalarExpr)>,
240        evaluator: SharedExpressionEvaluator<'a>,
241    ) -> Self {
242        let projections = projections
243            .into_iter()
244            .map(|(target, expression)| {
245                (
246                    target,
247                    evaluator.bind_type_introspection(expression, child.row_schema()),
248                )
249            })
250            .collect::<Vec<_>>();
251        let ordering = child
252            .output_ordering()
253            .iter()
254            .take_while(|order| {
255                projections.iter().all(|(target, expression)| {
256                    let ProjectionTarget::Column(name) = target else {
257                        return true;
258                    };
259                    child
260                        .row_schema()
261                        .columns()
262                        .iter()
263                        .position(|column| column == name)
264                        != Some(order.position)
265                        || matches!(expression, ScalarExpr::Star | ScalarExpr::QualifiedStar(_))
266                        || crate::order_expression_position(child.row_schema(), expression)
267                            == Some(order.position)
268                })
269            })
270            .cloned()
271            .collect();
272        let (schema, computed) =
273            projection_layout(child.row_schema(), projections, &evaluator, true);
274        Self {
275            child,
276            computed: crate::scalar::PreparedExpressions::scalars(computed),
277            evaluator,
278            schema,
279            ordering,
280        }
281    }
282
283    fn project_batch(&self, batch: Batch) -> ExecResult<Batch> {
284        if self.computed.is_empty() {
285            return Ok(Batch::from_physical_rows(self.schema.clone(), batch.rows));
286        }
287        let mut out = Vec::with_capacity(batch.rows.len());
288        for row in batch.rows {
289            let values = self
290                .computed
291                .iter()
292                .map(|expression| {
293                    self.evaluator.evaluate_physical_with_function_states(
294                        expression,
295                        &batch.schema,
296                        &row,
297                        self.computed.calls(),
298                    )
299                })
300                .collect::<ExecResult<Vec<Value>>>()?;
301            out.push(row.append_values(values));
302        }
303        Ok(Batch::from_physical_rows(self.schema.clone(), out))
304    }
305}
306
307impl PhysicalOperator for Project<'_> {
308    fn row_schema(&self) -> &RowSchema {
309        &self.schema
310    }
311
312    fn output_ordering(&self) -> &[crate::PhysicalOrder] {
313        &self.ordering
314    }
315
316    fn backward_scan_support(&self) -> BackwardScanSupport {
317        let child = self.child.backward_scan_support();
318        if child == BackwardScanSupport::Native || self.computed.is_empty() {
319            child
320        } else {
321            BackwardScanSupport::Unsupported
322        }
323    }
324
325    fn open(&mut self) -> ExecResult<()> {
326        self.child.open()
327    }
328
329    fn next(&mut self) -> ExecResult<Option<Batch>> {
330        let Some(batch) = self.child.next()? else {
331            return Ok(None);
332        };
333        self.project_batch(batch).map(Some)
334    }
335
336    fn next_direction(&mut self, direction: PhysicalScanDirection) -> ExecResult<Option<Batch>> {
337        let Some(batch) = self.child.next_direction(direction)? else {
338            return Ok(None);
339        };
340        self.project_batch(batch).map(Some)
341    }
342
343    fn rewind(&mut self) -> ExecResult<()> {
344        self.child.rewind()
345    }
346
347    fn close(&mut self) -> ExecResult<()> {
348        self.child.close()
349    }
350}
351
352// -------------------------------------------------------------------------
353// Sort
354// -------------------------------------------------------------------------