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::Value;
11use uqa_sql::expr::cast_value;
12
13use crate::{Batch, ColumnIdentity, ExecError, ExecResult, PhysicalOperator, RowSchema};
14
15pub use uqa_sql::schema::join_output::JoinOutputSource;
16
17/// Reorder and merge join columns while retaining the joined physical row.
18/// Inner, left, and right joins are schema-only remaps; a full join appends
19/// only the merged values that cannot be represented by one existing slot.
20pub struct JoinOutput<'a> {
21    child: Box<dyn PhysicalOperator + 'a>,
22    input_pending: crate::physical::demand::PendingRows,
23    schema: RowSchema,
24    computed: Vec<JoinOutputSource>,
25}
26
27impl<'a> JoinOutput<'a> {
28    /// 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.
29    pub fn try_schema(
30        input: &RowSchema,
31        columns: &[(String, ColumnIdentity, JoinOutputSource)],
32        aliases: &[(ColumnIdentity, JoinOutputSource)],
33    ) -> ExecResult<RowSchema> {
34        compile_layout(input, columns, aliases)
35            .map(|(schema, _)| schema)
36            .map_err(Into::into)
37    }
38
39    pub fn try_new(
40        child: Box<dyn PhysicalOperator + 'a>,
41        columns: Vec<(String, ColumnIdentity, JoinOutputSource)>,
42        aliases: Vec<(ColumnIdentity, JoinOutputSource)>,
43    ) -> ExecResult<Self> {
44        let (child, (schema, computed)) =
45            crate::physical::construction::OperatorBuild::run(child, |child| {
46                compile_layout(child.row_schema(), &columns, &aliases)
47                    .map_err(|error| crate::physical::physical_exec_error(error.into()))
48            })?;
49        Ok(Self {
50            child,
51            input_pending: crate::physical::demand::PendingRows::default(),
52            schema,
53            computed,
54        })
55    }
56}
57
58pub use uqa_sql::schema::join_output::compile_layout;
59
60impl JoinOutput<'_> {
61    fn pull(&mut self, demand: Option<std::num::NonZeroUsize>) -> ExecResult<Option<Batch>> {
62        let Some(batch) = self.input_pending.pull(self.child.as_mut(), demand)? else {
63            return Ok(None);
64        };
65        if self.computed.is_empty() {
66            return Ok(Some(Batch::from_physical_rows(
67                self.schema.clone(),
68                batch.rows,
69            )));
70        }
71        let rows = batch
72            .rows
73            .into_iter()
74            .map(|row| {
75                let values = {
76                    let view = batch.schema.view(&row);
77                    self.computed
78                        .iter()
79                        .map(|source| evaluate_source(source, &view))
80                        .collect::<ExecResult<Vec<_>>>()?
81                };
82                Ok(row.append_values(values))
83            })
84            .collect::<ExecResult<Vec<_>>>()?;
85        Ok(Some(Batch::from_physical_rows(self.schema.clone(), rows)))
86    }
87}
88
89impl PhysicalOperator for JoinOutput<'_> {
90    fn row_schema(&self) -> &RowSchema {
91        &self.schema
92    }
93
94    fn estimated_cardinality(&self) -> Option<u64> {
95        self.child.estimated_cardinality()
96    }
97
98    fn open(&mut self) -> ExecResult<()> {
99        self.input_pending.clear();
100        self.child.open()
101    }
102
103    fn next(&mut self) -> ExecResult<Option<Batch>> {
104        self.pull(None)
105    }
106
107    fn next_with_demand(&mut self, rows: std::num::NonZeroUsize) -> ExecResult<Option<Batch>> {
108        self.pull(Some(rows))
109    }
110
111    fn close(&mut self) -> ExecResult<()> {
112        self.input_pending.clear();
113        self.child.close()
114    }
115}
116
117pub use uqa_sql::schema::join_output::source_type;
118
119fn evaluate_source(
120    source: &JoinOutputSource,
121    view: &crate::PhysicalRowView<'_>,
122) -> ExecResult<Value> {
123    match source {
124        JoinOutputSource::Input(position) => {
125            Ok(view.value_at(*position).unwrap_or(&Value::Null).clone())
126        }
127        JoinOutputSource::Cast { input, ty } => cast_value(
128            view.value_at(*input).unwrap_or(&Value::Null),
129            &ty.sql_name(),
130        )
131        .map_err(ExecError::from),
132        JoinOutputSource::Coalesce { left, right, ty } => {
133            let target = ty.sql_name();
134            let left = cast_value(view.value_at(*left).unwrap_or(&Value::Null), &target)?;
135            if !matches!(left, Value::Null) {
136                return Ok(left);
137            }
138            cast_value(view.value_at(*right).unwrap_or(&Value::Null), &target)
139                .map_err(ExecError::from)
140        }
141    }
142}
143
144#[cfg(test)]
145mod tests {
146    use crate::RowSchemaExecution;
147    use std::collections::BTreeMap;
148    use uqa_sql::ast::ColumnType;
149
150    use super::*;
151    use crate::physical::run_to_rows;
152    use crate::TableScan;
153    use uqa_sql::expr::RowLookup;
154
155    #[test]
156    fn schema_only_merge_reuses_input_slots_and_keeps_qualified_aliases() {
157        let child = TableScan::from_rows(
158            vec![
159                "l.id".into(),
160                "l.name".into(),
161                "r.id".into(),
162                "r.note".into(),
163            ],
164            vec![BTreeMap::from([
165                ("l.id".into(), Value::Int(1)),
166                ("l.name".into(), Value::Str("left".into())),
167                ("r.id".into(), Value::Int(1)),
168                ("r.note".into(), Value::Str("right".into())),
169            ])],
170        );
171        let mut output = JoinOutput::try_new(
172            Box::new(child),
173            vec![
174                (
175                    "id".into(),
176                    ColumnIdentity::unqualified("id"),
177                    JoinOutputSource::Input(0),
178                ),
179                (
180                    "name".into(),
181                    ColumnIdentity::qualified("l", "name"),
182                    JoinOutputSource::Input(1),
183                ),
184                (
185                    "note".into(),
186                    ColumnIdentity::qualified("r", "note"),
187                    JoinOutputSource::Input(3),
188                ),
189            ],
190            vec![
191                (
192                    ColumnIdentity::qualified("l", "id"),
193                    JoinOutputSource::Input(0),
194                ),
195                (
196                    ColumnIdentity::qualified("r", "id"),
197                    JoinOutputSource::Input(2),
198                ),
199            ],
200        )
201        .unwrap();
202        output.open().unwrap();
203        let batch = output.next().unwrap().unwrap();
204        assert_eq!(batch.schema.columns(), ["id", "name", "note"]);
205        let view = batch.schema.view(&batch.rows[0]);
206        assert_eq!(view.qualified_column("l", "id"), Some(&Value::Int(1)));
207        assert_eq!(view.qualified_column("r", "id"), Some(&Value::Int(1)));
208        output.close().unwrap();
209    }
210
211    #[test]
212    fn full_merge_coalesces_only_the_requested_column() {
213        let child = TableScan::from_rows(
214            vec!["l.id".into(), "r.id".into()],
215            vec![BTreeMap::from([
216                ("l.id".into(), Value::Null),
217                ("r.id".into(), Value::Int(3)),
218            ])],
219        );
220        let mut output = JoinOutput::try_new(
221            Box::new(child),
222            vec![(
223                "id".into(),
224                ColumnIdentity::unqualified("id"),
225                JoinOutputSource::Coalesce {
226                    left: 0,
227                    right: 1,
228                    ty: ColumnType::Integer,
229                },
230            )],
231            Vec::new(),
232        )
233        .unwrap();
234        let (_, rows) = run_to_rows(&mut output).unwrap();
235        assert_eq!(rows[0]["id"], Value::Int(3));
236    }
237}