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    closed: 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::with_schema(operators, ordinality, schema)
53    }
54
55    /// Reopen the same prepared members with their previously assembled physical layout.
56    pub(crate) fn with_schema(
57        operators: Vec<Box<dyn PhysicalOperator + 'a>>,
58        ordinality: bool,
59        schema: RowSchema,
60    ) -> Self {
61        debug_assert_eq!(
62            operators
63                .iter()
64                .map(|operator| operator.row_schema().len())
65                .sum::<usize>()
66                + usize::from(ordinality),
67            schema.len()
68        );
69        Self {
70            children: operators
71                .into_iter()
72                .map(|operator| RowsFromChild {
73                    operator,
74                    pending: VecDeque::new(),
75                    exhausted: false,
76                })
77                .collect(),
78            schema,
79            ordinality,
80            next_ordinality: 1,
81            closed: false,
82            exhausted: false,
83        }
84    }
85
86    fn next_child_row(
87        child: &mut RowsFromChild<'a>,
88        demanded: bool,
89    ) -> ExecResult<Option<PhysicalRow>> {
90        loop {
91            if let Some(row) = child.pending.pop_front() {
92                return Ok(Some(row));
93            }
94            if child.exhausted {
95                return Ok(None);
96            }
97            match if demanded {
98                child
99                    .operator
100                    .next_with_demand(crate::physical::demand::ONE)?
101            } else {
102                child.operator.next()?
103            } {
104                Some(batch) => child.pending.extend(batch.rows),
105                None => child.exhausted = true,
106            }
107        }
108    }
109
110    fn close_children(&mut self) -> ExecResult<()> {
111        let mut result = Ok(());
112        for child in &mut self.children {
113            child.pending.clear();
114            child.exhausted = true;
115            result = crate::physical::with_cleanup(
116                result,
117                child.operator.close(),
118                "close ROWS FROM member",
119            );
120        }
121        result
122    }
123}
124
125impl PhysicalOperator for RowsFromOperator<'_> {
126    fn row_schema(&self) -> &RowSchema {
127        &self.schema
128    }
129
130    fn estimated_cardinality(&self) -> Option<u64> {
131        self.children
132            .iter()
133            .filter_map(|child| child.operator.estimated_cardinality())
134            .max()
135    }
136
137    fn backward_scan_support(&self) -> crate::BackwardScanSupport {
138        crate::BackwardScanSupport::Materialize
139    }
140
141    fn open(&mut self) -> ExecResult<()> {
142        self.next_ordinality = 1;
143        self.exhausted = false;
144        self.closed = false;
145        for position in 0..self.children.len() {
146            self.children[position].pending.clear();
147            self.children[position].exhausted = false;
148            if let Err(open_error) = self.children[position].operator.open() {
149                return crate::physical::with_cleanup(
150                    Err(open_error),
151                    self.close(),
152                    "close ROWS FROM after open failure",
153                );
154            }
155        }
156        Ok(())
157    }
158
159    fn next(&mut self) -> ExecResult<Option<Batch>> {
160        self.pull(DEFAULT_BATCH_SIZE, false)
161    }
162    fn next_with_demand(&mut self, rows: std::num::NonZeroUsize) -> ExecResult<Option<Batch>> {
163        self.pull(rows.get().min(DEFAULT_BATCH_SIZE), true)
164    }
165
166    fn close(&mut self) -> ExecResult<()> {
167        self.exhausted = true;
168        if std::mem::replace(&mut self.closed, true) {
169            Ok(())
170        } else {
171            self.close_children()
172        }
173    }
174}
175
176impl RowsFromOperator<'_> {
177    fn pull(&mut self, rows: usize, demanded: bool) -> ExecResult<Option<Batch>> {
178        if self.exhausted {
179            return Ok(None);
180        }
181        let mut output = Vec::with_capacity(rows);
182        while output.len() < rows {
183            let mut any_member_produced = false;
184            let mut row = PhysicalRow::default();
185            for child in &mut self.children {
186                let member_row = Self::next_child_row(child, demanded)?;
187                any_member_produced |= member_row.is_some();
188                let member_row = member_row.unwrap_or_else(|| {
189                    PhysicalRow::nulls(child.operator.row_schema().physical_width())
190                });
191                row = PhysicalRow::concat_left_owned(row, &member_row);
192            }
193            if !any_member_produced {
194                self.exhausted = true;
195                break;
196            }
197            if self.ordinality {
198                row = row.append_values(vec![Value::Int(self.next_ordinality)]);
199                self.next_ordinality = self.next_ordinality.checked_add(1).ok_or_else(|| {
200                    ExecError::Other("ROWS FROM ordinality exceeded bigint range".into())
201                })?;
202            }
203            output.push(row);
204        }
205        if output.is_empty() {
206            Ok(None)
207        } else {
208            Ok(Some(Batch::from_physical_rows(self.schema.clone(), output)))
209        }
210    }
211}