Skip to main content

uqa_execution/
join_output.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Positional output shaping for `JOIN ... USING` and `NATURAL JOIN`.
8
9use crate::RowSchemaExecution;
10use uqa_core::{
11    memory::{Produced, ProductionControl},
12    Value,
13};
14use uqa_sql::expr::cast_value;
15
16use crate::{Batch, ColumnIdentity, ExecError, ExecResult, PhysicalOperator, RowSchema};
17
18pub use uqa_sql::schema::join_output::JoinOutputSource;
19
20/// Reorder and merge join columns while retaining the joined physical row.
21/// Inner, left, and right joins are schema-only remaps; a full join appends
22/// only the merged values that cannot be represented by one existing slot.
23pub struct JoinOutput<'a> {
24    child: Box<dyn PhysicalOperator + 'a>,
25    input_pending: crate::physical::demand::PendingRows,
26    schema: RowSchema,
27    computed: Produced<Vec<JoinOutputSource>>,
28    _memory: Option<uqa_core::memory::MemoryReservation>,
29}
30
31impl<'a> JoinOutput<'a> {
32    /// Compile the positional schema of a qualified join without constructing or executing an operator. Binders use this to expose the exact same merged-column identities and hidden qualified aliases as execution.
33    pub fn try_schema(
34        input: &RowSchema,
35        columns: &[(String, ColumnIdentity, JoinOutputSource)],
36        aliases: &[(ColumnIdentity, JoinOutputSource)],
37    ) -> ExecResult<RowSchema> {
38        compile_layout(input, columns, aliases)
39            .map(|(schema, _)| schema)
40            .map_err(Into::into)
41    }
42
43    pub fn try_new(
44        child: Box<dyn PhysicalOperator + 'a>,
45        columns: Vec<(String, ColumnIdentity, JoinOutputSource)>,
46        aliases: Vec<(ColumnIdentity, JoinOutputSource)>,
47    ) -> ExecResult<Self> {
48        Self::with_control(
49            child,
50            &columns,
51            &aliases,
52            &ProductionControl::uncontrolled(),
53        )
54    }
55
56    pub fn with_control(
57        child: Box<dyn PhysicalOperator + 'a>,
58        columns: &[(String, ColumnIdentity, JoinOutputSource)],
59        aliases: &[(ColumnIdentity, JoinOutputSource)],
60        control: &ProductionControl<'_>,
61    ) -> ExecResult<Self> {
62        let (child, (schema, computed)) =
63            crate::physical::construction::OperatorBuild::run(child, |child| {
64                uqa_sql::schema::join_output::compile_layout_with_control(
65                    child.row_schema(),
66                    columns,
67                    aliases,
68                    control,
69                )
70            })?;
71        Ok(Self {
72            child,
73            input_pending: crate::physical::demand::PendingRows::default(),
74            schema,
75            computed,
76            _memory: None,
77        })
78    }
79
80    pub fn into_boxed(
81        self,
82        control: &ProductionControl<'_>,
83    ) -> Result<Box<dyn PhysicalOperator + 'a>, uqa_sql::SQLError> {
84        let Self {
85            child,
86            input_pending,
87            schema,
88            computed,
89            _memory: _,
90        } = self;
91        crate::physical::construction::OperatorBuild::build(child, |owner| {
92            let memory = control.reserve(size_of::<Self>())?;
93            owner.wrap(|child| {
94                Box::new(Self {
95                    child,
96                    input_pending,
97                    schema,
98                    computed,
99                    _memory: memory,
100                })
101            });
102            Ok(())
103        })
104    }
105}
106
107pub use uqa_sql::schema::join_output::compile_layout;
108
109impl JoinOutput<'_> {
110    fn pull(&mut self, demand: Option<std::num::NonZeroUsize>) -> ExecResult<Option<Batch>> {
111        let Some(batch) = self.input_pending.pull(self.child.as_mut(), demand)? else {
112            return Ok(None);
113        };
114        if self.computed.is_empty() {
115            return Ok(Some(Batch::from_physical_rows(
116                self.schema.clone(),
117                batch.rows,
118            )));
119        }
120        let rows = batch
121            .rows
122            .into_iter()
123            .map(|row| {
124                let values = {
125                    let view = batch.schema.view(&row);
126                    self.computed
127                        .iter()
128                        .map(|source| evaluate_source(source, &view))
129                        .collect::<ExecResult<Vec<_>>>()?
130                };
131                Ok(row.append_values(values))
132            })
133            .collect::<ExecResult<Vec<_>>>()?;
134        Ok(Some(Batch::from_physical_rows(self.schema.clone(), rows)))
135    }
136}
137
138impl PhysicalOperator for JoinOutput<'_> {
139    fn row_schema(&self) -> &RowSchema {
140        &self.schema
141    }
142
143    fn estimated_cardinality(&self) -> Option<u64> {
144        self.child.estimated_cardinality()
145    }
146
147    fn open(&mut self) -> ExecResult<()> {
148        self.input_pending.clear();
149        self.child.open()
150    }
151
152    fn next(&mut self) -> ExecResult<Option<Batch>> {
153        self.pull(None)
154    }
155
156    fn next_with_demand(&mut self, rows: std::num::NonZeroUsize) -> ExecResult<Option<Batch>> {
157        self.pull(Some(rows))
158    }
159
160    fn close(&mut self) -> ExecResult<()> {
161        self.input_pending.clear();
162        self.child.close()
163    }
164}
165
166pub use uqa_sql::schema::join_output::source_type;
167
168fn evaluate_source(
169    source: &JoinOutputSource,
170    view: &crate::PhysicalRowView<'_>,
171) -> ExecResult<Value> {
172    match source {
173        JoinOutputSource::Input(position) => {
174            Ok(view.value_at(*position).unwrap_or(&Value::Null).clone())
175        }
176        JoinOutputSource::Cast { input, ty } => cast_value(
177            view.value_at(*input).unwrap_or(&Value::Null),
178            &ty.sql_name(),
179        )
180        .map_err(ExecError::from),
181        JoinOutputSource::Coalesce { left, right, ty } => {
182            let target = ty.sql_name();
183            let left = cast_value(view.value_at(*left).unwrap_or(&Value::Null), &target)?;
184            if !matches!(left, Value::Null) {
185                return Ok(left);
186            }
187            cast_value(view.value_at(*right).unwrap_or(&Value::Null), &target)
188                .map_err(ExecError::from)
189        }
190    }
191}
192
193#[cfg(test)]
194mod tests {
195    use crate::RowSchemaExecution;
196    use std::collections::BTreeMap;
197    use uqa_sql::ast::ColumnType;
198
199    use super::*;
200    use crate::physical::run_to_rows;
201    use crate::TableScan;
202    use uqa_sql::expr::RowLookup;
203
204    #[test]
205    fn schema_only_merge_reuses_input_slots_and_keeps_qualified_aliases() {
206        let child = TableScan::from_rows(
207            vec![
208                "l.id".into(),
209                "l.name".into(),
210                "r.id".into(),
211                "r.note".into(),
212            ],
213            vec![BTreeMap::from([
214                ("l.id".into(), Value::Int(1)),
215                ("l.name".into(), Value::Str("left".into())),
216                ("r.id".into(), Value::Int(1)),
217                ("r.note".into(), Value::Str("right".into())),
218            ])],
219        );
220        let mut output = JoinOutput::try_new(
221            Box::new(child),
222            vec![
223                (
224                    "id".into(),
225                    ColumnIdentity::unqualified("id"),
226                    JoinOutputSource::Input(0),
227                ),
228                (
229                    "name".into(),
230                    ColumnIdentity::qualified("l", "name"),
231                    JoinOutputSource::Input(1),
232                ),
233                (
234                    "note".into(),
235                    ColumnIdentity::qualified("r", "note"),
236                    JoinOutputSource::Input(3),
237                ),
238            ],
239            vec![
240                (
241                    ColumnIdentity::qualified("l", "id"),
242                    JoinOutputSource::Input(0),
243                ),
244                (
245                    ColumnIdentity::qualified("r", "id"),
246                    JoinOutputSource::Input(2),
247                ),
248            ],
249        )
250        .unwrap();
251        output.open().unwrap();
252        let batch = output.next().unwrap().unwrap();
253        assert_eq!(batch.schema.columns(), ["id", "name", "note"]);
254        let view = batch.schema.view(&batch.rows[0]);
255        assert_eq!(view.qualified_column("l", "id"), Some(&Value::Int(1)));
256        assert_eq!(view.qualified_column("r", "id"), Some(&Value::Int(1)));
257        output.close().unwrap();
258    }
259
260    #[test]
261    fn full_merge_coalesces_only_the_requested_column() {
262        let child = TableScan::from_rows(
263            vec!["l.id".into(), "r.id".into()],
264            vec![BTreeMap::from([
265                ("l.id".into(), Value::Null),
266                ("r.id".into(), Value::Int(3)),
267            ])],
268        );
269        let mut output = JoinOutput::try_new(
270            Box::new(child),
271            vec![(
272                "id".into(),
273                ColumnIdentity::unqualified("id"),
274                JoinOutputSource::Coalesce {
275                    left: 0,
276                    right: 1,
277                    ty: ColumnType::Integer,
278                },
279            )],
280            Vec::new(),
281        )
282        .unwrap();
283        let (_, rows) = run_to_rows(&mut output).unwrap();
284        assert_eq!(rows[0]["id"], Value::Int(3));
285    }
286}
287
288#[cfg(test)]
289mod production_tests;