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