Skip to main content

uqa_execution/query/relational/
ordering.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Projection placement around blocking ordering operators.
8
9use super::limit::attach_order_limit;
10use super::{build_set_projection, RelationalContext};
11use crate::physical::construction::OperatorBuild;
12use crate::query::projection::projection_set_batch_size;
13use crate::query::row_at_a_time::RowAtATime;
14use crate::query::runtime::QueryRuntimeView;
15use crate::query::{CteScope, OutputColumnMapping, PhysicalProjection};
16use crate::{ProjectionTarget, SharedExpressionEvaluator};
17use std::sync::Arc;
18use uqa_core::Value;
19use uqa_sql::semantics::sets::validation::projections_may_return_set;
20use uqa_sql::{plan::QueryBlockPlan, SQLError, SQLParam, ScalarExpr};
21
22pub struct FinalProjectionExecution<'context, 'scope, S: Clone + 'static> {
23    pub context: RelationalContext<'context, S>,
24    pub params: &'context [SQLParam],
25    pub ctes: &'scope CteScope<S>,
26    pub runtime: QueryRuntimeView<'context>,
27    pub evaluator: SharedExpressionEvaluator<'context>,
28}
29
30pub use crate::query::ordering::*;
31mod streaming;
32pub(super) use streaming::attach_streaming_order_projection;
33
34pub fn attach_final_projection_order<'a, S: Clone + 'static>(
35    operator: Box<dyn crate::PhysicalOperator + 'a>,
36    ordering: (&QueryBlockPlan, &[OutputColumnMapping]),
37    projections: Vec<PhysicalProjection>,
38    execution: FinalProjectionExecution<'a, '_, S>,
39) -> Result<Box<dyn crate::PhysicalOperator + 'a>, SQLError> {
40    OperatorBuild::build(operator, |operator| {
41        let (statement, output) = ordering;
42        let type_resolver = execution.context.expression_scope(execution.ctes)?;
43        let returns_set = projections_may_return_set(
44            execution.context.catalog,
45            type_resolver.as_ref(),
46            &projections,
47            operator.row_schema(),
48            execution.params,
49        )?;
50        if execution.ctes.streams_command_progress()
51            && !statement.order_by.is_empty()
52            && !returns_set
53        {
54            return operator.attach(|input| {
55                attach_deferred_order_projection(input, statement, output, projections, execution)
56            });
57        }
58        let FinalProjectionExecution {
59            context,
60            params,
61            ctes,
62            runtime,
63            evaluator,
64        } = execution;
65        let batch_size = projection_set_batch_size(statement, ctes);
66        if returns_set {
67            operator.attach(|input| {
68                build_set_projection(
69                    input,
70                    context,
71                    params,
72                    ctes,
73                    Arc::clone(&evaluator),
74                    crate::query::set_projection::SetProjectionOutput {
75                        projections,
76                        pass_through: false,
77                        batch_size,
78                    },
79                )
80            })?;
81        } else {
82            if batch_size == 1 {
83                operator.wrap(|input| Box::new(RowAtATime::new(input)));
84            }
85            let work_mem = runtime.work_mem_bytes()?;
86            operator.wrap(|input| {
87                Box::new(
88                    crate::Project::with_target_evaluator(
89                        input,
90                        projections,
91                        Arc::clone(&evaluator),
92                    )
93                    .with_memory_budget(work_mem),
94                )
95            });
96        }
97        operator.attach(|input| {
98            attach_order_limit(
99                input, statement, output, context, params, ctes, runtime, evaluator, None,
100            )
101        })
102    })
103}
104
105fn attach_deferred_order_projection<'a, S: Clone + 'static>(
106    operator: Box<dyn crate::PhysicalOperator + 'a>,
107    statement: &QueryBlockPlan,
108    output: &[OutputColumnMapping],
109    projections: Vec<PhysicalProjection>,
110    execution: FinalProjectionExecution<'a, '_, S>,
111) -> Result<Box<dyn crate::PhysicalOperator + 'a>, SQLError> {
112    OperatorBuild::build(operator, |operator| {
113        let FinalProjectionExecution {
114            context,
115            params,
116            ctes,
117            runtime,
118            evaluator,
119        } = execution;
120        let (sort_statement, sort_projections, projections) =
121            prepare_deferred_order_projection(statement, output, projections)?;
122        let work_mem = runtime.work_mem_bytes()?;
123        operator.wrap(|input| {
124            Box::new(
125                crate::Project::appending_target_evaluator(
126                    input,
127                    sort_projections,
128                    Arc::clone(&evaluator),
129                )
130                .with_memory_budget(work_mem),
131            )
132        });
133        operator.attach(|input| {
134            attach_order_limit(
135                input,
136                &sort_statement,
137                &[],
138                context,
139                params,
140                ctes,
141                runtime,
142                Arc::clone(&evaluator),
143                None,
144            )
145        })?;
146        operator.wrap(|input| Box::new(RowAtATime::new(input)));
147        let work_mem = runtime.work_mem_bytes()?;
148        operator.wrap(|input| {
149            Box::new(
150                crate::Project::with_target_evaluator(input, projections, evaluator)
151                    .with_memory_budget(work_mem),
152            )
153        });
154        Ok(())
155    })
156}
157
158type PreparedDeferredOrderProjection = (
159    QueryBlockPlan,
160    Vec<PhysicalProjection>,
161    Vec<PhysicalProjection>,
162);
163
164pub(super) fn prepare_deferred_order_projection(
165    statement: &QueryBlockPlan,
166    output: &[OutputColumnMapping],
167    mut projections: Vec<PhysicalProjection>,
168) -> Result<PreparedDeferredOrderProjection, SQLError> {
169    let mut sort_statement = statement.clone();
170    let sort_relation = uqa_sql::ast::InternalRelationId::allocate();
171    let mut sort_projections =
172        Vec::<(Option<usize>, ScalarExpr, uqa_sql::ast::InternalColumnRef)>::new();
173    for (order_index, order) in statement.order_by.iter().enumerate() {
174        let resolved = resolve_order_expression(&order.expr, output)?;
175        let direct_target = match &order.expr {
176            ScalarExpr::Literal(Value::Int(position)) => usize::try_from(*position)
177                .ok()
178                .and_then(|position| position.checked_sub(1)),
179            ScalarExpr::Column(name) => output.iter().position(|(label, _)| label == name),
180            _ => None,
181        };
182        let target = direct_target
183            .or_else(|| {
184                projections.iter().position(|(target, projected)| {
185                    matches!(
186                        (target, &resolved),
187                        (ProjectionTarget::Internal(column), ScalarExpr::InternalColumn(required))
188                            if column == required
189                    ) || uqa_sql::semantics::aggregates::exprs_match(projected, &resolved)
190                })
191            })
192            .filter(|position| *position < projections.len());
193        let expression = target
194            .map(|position| projections[position].1.clone())
195            .unwrap_or(resolved);
196        let existing_column = sort_projections
197            .iter()
198            .find(|(existing_target, existing, _)| {
199                target == *existing_target
200                    && (target.is_some()
201                        || uqa_sql::semantics::aggregates::exprs_match(existing, &expression))
202            })
203            .map(|(_, _, column)| *column);
204        let column = if let Some(column) = existing_column {
205            column
206        } else {
207            let column = sort_relation.column(sort_projections.len());
208            sort_projections.push((target, expression, column));
209            column
210        };
211        sort_statement.order_by[order_index].expr = ScalarExpr::InternalColumn(column);
212        if let Some(target) = target {
213            projections[target].1 = ScalarExpr::InternalColumn(column);
214        }
215    }
216    let sort_projections = sort_projections
217        .into_iter()
218        .map(|(_, expression, column)| (ProjectionTarget::Internal(column), expression))
219        .collect();
220    Ok((sort_statement, sort_projections, projections))
221}