Skip to main content

uqa_execution/join/
production.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Join construction retains immutable scalar producers through physical execution.
8
9use super::{presence, HashJoin, SpillState};
10use crate::physical::construction::OperatorBuild;
11use crate::scalar::PreparedExpressions;
12use crate::{
13    PhysicalOperator, PhysicalRow, ProjectedPredicate, RowSchema, ScalarExpr,
14    SharedExpressionEvaluator,
15};
16use uqa_core::memory::{Produced, ProductionControl, ProductionVec};
17use uqa_sql::{ast::JoinKind, ResultRow, SQLError, SQLParam};
18
19fn simple_key_positions(
20    schema: &RowSchema,
21    expressions: &[ScalarExpr],
22    control: &ProductionControl<'_>,
23) -> Result<Option<Produced<Vec<usize>>>, SQLError> {
24    let mut positions = ProductionVec::new(*control);
25    for expression in expressions {
26        control.check()?;
27        let position = match expression {
28            ScalarExpr::Column(column) => schema.position(column),
29            ScalarExpr::QualifiedColumn { qualifier, column } => {
30                schema.qualified_position(qualifier, column)
31            }
32            _ => None,
33        };
34        let Some(position) = position else {
35            return Ok(None);
36        };
37        positions.push_copy(position)?;
38    }
39    Ok(Some(positions.finish()?))
40}
41
42fn compile_predicate(
43    predicate: Option<&ScalarExpr>,
44    schema: &RowSchema,
45    params: Option<&[SQLParam]>,
46    control: &ProductionControl<'_>,
47) -> Result<Option<ProjectedPredicate>, SQLError> {
48    let compiled = predicate
49        .map(|predicate| {
50            ProjectedPredicate::compile_with_schema_with_control(
51                predicate,
52                schema,
53                params.unwrap_or(&[]),
54                control,
55            )
56        })
57        .transpose();
58    match compiled {
59        Ok(predicate) => Ok(predicate.flatten()),
60        Err(error) if params.is_some() || matches!(error.sqlstate(), Some("53200" | "57014")) => {
61            Err(error)
62        }
63        Err(_) => Ok(None),
64    }
65}
66
67impl<'a> HashJoin<'a> {
68    #[expect(
69        clippy::too_many_arguments,
70        reason = "retains join inputs, predicates and their original resource owner"
71    )]
72    pub fn with_owned_expressions(
73        left: Box<dyn PhysicalOperator + 'a>,
74        right: Box<dyn PhysicalOperator + 'a>,
75        kind: JoinKind,
76        left_keys: Produced<Vec<ScalarExpr>>,
77        right_keys: Produced<Vec<ScalarExpr>>,
78        predicate: Option<Produced<ScalarExpr>>,
79        evaluator: SharedExpressionEvaluator<'a>,
80        left_nulls: ResultRow,
81        right_nulls: ResultRow,
82        work_mem_bytes: usize,
83        params: &[SQLParam],
84        control: &ProductionControl<'_>,
85    ) -> Result<Self, SQLError> {
86        Self::build_with_owned_expressions(
87            left,
88            right,
89            kind,
90            left_keys,
91            right_keys,
92            predicate,
93            evaluator,
94            left_nulls,
95            right_nulls,
96            work_mem_bytes,
97            Some(params),
98            control,
99        )
100    }
101
102    #[expect(
103        clippy::too_many_arguments,
104        reason = "ordinary and controlled joins share one construction boundary"
105    )]
106    pub(super) fn build_with_owned_expressions(
107        left: Box<dyn PhysicalOperator + 'a>,
108        right: Box<dyn PhysicalOperator + 'a>,
109        kind: JoinKind,
110        left_keys: Produced<Vec<ScalarExpr>>,
111        right_keys: Produced<Vec<ScalarExpr>>,
112        predicate: Option<Produced<ScalarExpr>>,
113        evaluator: SharedExpressionEvaluator<'a>,
114        left_nulls: ResultRow,
115        right_nulls: ResultRow,
116        work_mem_bytes: usize,
117        params: Option<&[SQLParam]>,
118        control: &ProductionControl<'_>,
119    ) -> Result<Self, SQLError> {
120        let (
121            left,
122            right,
123            (
124                left_keys,
125                right_keys,
126                left_key_positions,
127                right_key_positions,
128                predicate,
129                prepared_predicate,
130                schema,
131            ),
132        ) = OperatorBuild::pair(left, right, |left, right| {
133            control.check()?;
134            presence::join_inputs(left, right, kind, control)?;
135            let left_key_positions = simple_key_positions(left.row_schema(), &left_keys, control)?;
136            let right_key_positions =
137                simple_key_positions(right.row_schema(), &right_keys, control)?;
138            let schema = RowSchema::join_borrowed_columns_with_control(
139                left.row_schema(),
140                right.row_schema(),
141                left_nulls
142                    .keys()
143                    .chain(right_nulls.keys())
144                    .map(String::as_str),
145                control,
146            )?;
147            let prepared_predicate =
148                compile_predicate(predicate.as_deref(), &schema, params, control)?;
149            let left_keys = PreparedExpressions::produced_scalars(left_keys, control)?;
150            let right_keys = PreparedExpressions::produced_scalars(right_keys, control)?;
151            let predicate = predicate
152                .map(|predicate| PreparedExpressions::produced_scalar(predicate, control))
153                .transpose()?;
154            Ok((
155                left_keys,
156                right_keys,
157                left_key_positions,
158                right_key_positions,
159                predicate,
160                prepared_predicate,
161                schema,
162            ))
163        })?;
164        let left_nulls = PhysicalRow::nulls(left.row_schema().physical_width());
165        let right_nulls = PhysicalRow::nulls(right.row_schema().physical_width());
166        let left_cardinality = left.estimated_cardinality();
167        let right_cardinality = right.estimated_cardinality();
168        let build_left = matches!(kind, JoinKind::Inner)
169            && left_cardinality
170                .zip(right_cardinality)
171                .is_some_and(|(left, right)| left < right);
172        let estimated_cardinality = left_cardinality
173            .zip(right_cardinality)
174            .map(|(left, right)| match kind {
175                JoinKind::Inner => left.max(right),
176                JoinKind::Left => left,
177                JoinKind::Right => right,
178                JoinKind::Full => left.saturating_add(right),
179                JoinKind::Cross => left.saturating_mul(right),
180            });
181        Ok(Self {
182            left,
183            right,
184            kind,
185            left_keys,
186            right_keys,
187            left_key_types: Vec::new(),
188            right_key_types: Vec::new(),
189            left_key_positions,
190            right_key_positions,
191            predicate,
192            prepared_predicate,
193            evaluator,
194            left_nulls,
195            right_nulls,
196            schema,
197            estimated_cardinality,
198            build_left,
199            work_mem_bytes,
200            output: None,
201            streaming_unique: None,
202            streaming: None,
203            probe_pending: crate::physical::demand::PendingRows::default(),
204            initialized: false,
205            prefetched_left: None,
206            output_spilled: SpillState::InMemory,
207            right_input_spilled: SpillState::InMemory,
208            hash_index_spilled: SpillState::InMemory,
209            memory: None,
210        })
211    }
212
213    pub fn into_boxed(mut self, control: &ProductionControl<'_>) -> Result<Box<Self>, SQLError> {
214        match control.reserve(size_of::<Self>()) {
215            Ok(memory) => {
216                self.memory = memory;
217                Ok(Box::new(self))
218            }
219            Err(error) => {
220                let left = self.left.close();
221                let right = self.right.close();
222                let cleanup = crate::physical::with_cleanup(
223                    left,
224                    right,
225                    "close right hash join input after construction failure",
226                );
227                Err(match cleanup {
228                    Ok(()) => error.into(),
229                    Err(cleanup) => SQLError::from(error).with_cleanup(
230                        crate::physical::physical_exec_error(cleanup),
231                        "close hash join after wrapper admission failure",
232                    ),
233                })
234            }
235        }
236    }
237}
238
239#[cfg(test)]
240mod tests;