Skip to main content

uqa_execution/query/table_functions/
rows_from.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Streaming zip-longest execution for `ROWS FROM` function groups.
8
9use std::collections::VecDeque;
10
11use crate::{
12    Batch, ExecError, ExecResult, PhysicalOperator, PhysicalRow, RowSchema, DEFAULT_BATCH_SIZE,
13};
14use uqa_core::Value;
15use uqa_sql::ast::ColumnType;
16
17struct RowsFromChild<'a> {
18    operator: Box<dyn PhysicalOperator + 'a>,
19    pending: VecDeque<PhysicalRow>,
20    exhausted: bool,
21}
22
23/// Pull one row from every member for each output position. Shorter members
24/// contribute NULLs after exhaustion, matching `PostgreSQL`'s `ROWS FROM`
25/// zip-and-pad contract without materialising any complete member result.
26pub struct RowsFromOperator<'a> {
27    children: Vec<RowsFromChild<'a>>,
28    schema: RowSchema,
29    ordinality: bool,
30    next_ordinality: i64,
31    opened: bool,
32    exhausted: bool,
33}
34
35impl<'a> RowsFromOperator<'a> {
36    pub fn new(operators: Vec<Box<dyn PhysicalOperator + 'a>>, ordinality: bool) -> Self {
37        debug_assert!(!operators.is_empty());
38        let mut schemas = operators
39            .iter()
40            .map(|operator| operator.row_schema().clone());
41        let mut schema = schemas.next().unwrap_or_default();
42        for child in schemas {
43            schema = RowSchema::join(&schema, &child, std::iter::empty());
44        }
45        if ordinality {
46            let ordinality_schema = RowSchema::with_types(
47                vec!["ordinality".into()],
48                vec![Some(ColumnType::BigInteger)],
49            );
50            schema = RowSchema::join(&schema, &ordinality_schema, std::iter::empty());
51        }
52        Self {
53            children: operators
54                .into_iter()
55                .map(|operator| RowsFromChild {
56                    operator,
57                    pending: VecDeque::new(),
58                    exhausted: false,
59                })
60                .collect(),
61            schema,
62            ordinality,
63            next_ordinality: 1,
64            opened: false,
65            exhausted: false,
66        }
67    }
68
69    fn next_child_row(child: &mut RowsFromChild<'a>) -> ExecResult<Option<PhysicalRow>> {
70        loop {
71            if let Some(row) = child.pending.pop_front() {
72                return Ok(Some(row));
73            }
74            if child.exhausted {
75                return Ok(None);
76            }
77            match child.operator.next()? {
78                Some(batch) => child.pending.extend(batch.rows),
79                None => child.exhausted = true,
80            }
81        }
82    }
83
84    fn close_opened_children(&mut self) -> ExecResult<()> {
85        let mut errors = Vec::new();
86        for child in &mut self.children {
87            child.pending.clear();
88            child.exhausted = true;
89            if let Err(error) = child.operator.close() {
90                errors.push(error.to_string());
91            }
92        }
93        self.opened = false;
94        if errors.is_empty() {
95            Ok(())
96        } else {
97            Err(ExecError::Other(format!(
98                "failed to close ROWS FROM members: {}",
99                errors.join("; ")
100            )))
101        }
102    }
103}
104
105impl PhysicalOperator for RowsFromOperator<'_> {
106    fn row_schema(&self) -> &RowSchema {
107        &self.schema
108    }
109
110    fn estimated_cardinality(&self) -> Option<u64> {
111        self.children
112            .iter()
113            .filter_map(|child| child.operator.estimated_cardinality())
114            .max()
115    }
116
117    fn backward_scan_support(&self) -> crate::BackwardScanSupport {
118        crate::BackwardScanSupport::Materialize
119    }
120
121    fn open(&mut self) -> ExecResult<()> {
122        self.next_ordinality = 1;
123        self.exhausted = false;
124        for position in 0..self.children.len() {
125            self.children[position].pending.clear();
126            self.children[position].exhausted = false;
127            if let Err(open_error) = self.children[position].operator.open() {
128                let mut close_errors = Vec::new();
129                for child in self.children.iter_mut().take(position + 1) {
130                    if let Err(close_error) = child.operator.close() {
131                        close_errors.push(close_error.to_string());
132                    }
133                }
134                self.opened = false;
135                return if close_errors.is_empty() {
136                    Err(open_error)
137                } else {
138                    Err(ExecError::Other(format!(
139                        "{open_error}; failed to close ROWS FROM members after open failure: {}",
140                        close_errors.join("; ")
141                    )))
142                };
143            }
144        }
145        self.opened = true;
146        Ok(())
147    }
148
149    fn next(&mut self) -> ExecResult<Option<Batch>> {
150        if self.exhausted {
151            return Ok(None);
152        }
153        let mut output = Vec::with_capacity(DEFAULT_BATCH_SIZE);
154        while output.len() < DEFAULT_BATCH_SIZE {
155            let mut any_member_produced = false;
156            let mut row = PhysicalRow::default();
157            for child in &mut self.children {
158                let member_row = Self::next_child_row(child)?;
159                any_member_produced |= member_row.is_some();
160                let member_row = member_row.unwrap_or_else(|| {
161                    PhysicalRow::nulls(child.operator.row_schema().physical_width())
162                });
163                row = PhysicalRow::concat_left_owned(row, &member_row);
164            }
165            if !any_member_produced {
166                self.exhausted = true;
167                break;
168            }
169            if self.ordinality {
170                row = row.append_values(vec![Value::Int(self.next_ordinality)]);
171                self.next_ordinality = self.next_ordinality.checked_add(1).ok_or_else(|| {
172                    ExecError::Other("ROWS FROM ordinality exceeded bigint range".into())
173                })?;
174            }
175            output.push(row);
176        }
177        if output.is_empty() {
178            Ok(None)
179        } else {
180            Ok(Some(Batch::from_physical_rows(self.schema.clone(), output)))
181        }
182    }
183
184    fn close(&mut self) -> ExecResult<()> {
185        self.exhausted = true;
186        if self.opened {
187            self.close_opened_children()
188        } else {
189            Ok(())
190        }
191    }
192}