Skip to main content

uqa_execution/query/cte/
rows.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Statement-owned CTE rows: completed command/recursive buffers or one demand-driven read-only producer.
8
9use crate::physical::{physical_exec_error, with_cleanup};
10use crate::spill::BufferedIndexedSpill;
11use crate::{Batch, ExecError, ExecResult, PhysicalOperator, RowSchema, SharedSpill};
12use parking_lot::Mutex;
13use std::{num::NonZeroUsize, sync::Arc};
14use uqa_sql::SQLError;
15
16#[derive(Clone)]
17pub enum CteRows {
18    Complete(SharedSpill),
19    Prefix(SharedPrefix),
20}
21impl CteRows {
22    pub fn row_schema(&self) -> &RowSchema {
23        match self {
24            Self::Complete(rows) => rows.row_schema(),
25            Self::Prefix(rows) => &rows.schema,
26        }
27    }
28    pub fn into_operator(self) -> Box<dyn PhysicalOperator> {
29        match self {
30            Self::Complete(rows) => Box::new(crate::SharedSpillScan::new(rows)),
31            Self::Prefix(rows) => Box::new(PrefixScan { rows, position: 0 }),
32        }
33    }
34    pub(crate) fn from_producer(input: Box<dyn PhysicalOperator>, budget: usize) -> Self {
35        let schema = input.row_schema().clone();
36        Self::Prefix(SharedPrefix {
37            schema: schema.clone(),
38            state: Arc::new(Mutex::new(PrefixState {
39                rows: BufferedIndexedSpill::new(schema, budget),
40                input: Some(input),
41                opened: false,
42                failure: None,
43            })),
44        })
45    }
46}
47
48#[derive(Clone)]
49pub struct SharedPrefix {
50    schema: RowSchema,
51    state: Arc<Mutex<PrefixState>>,
52}
53struct PrefixState {
54    rows: BufferedIndexedSpill,
55    input: Option<Box<dyn PhysicalOperator>>,
56    opened: bool,
57    failure: Option<SQLError>,
58}
59impl PrefixState {
60    fn finish(&mut self) -> ExecResult<()> {
61        self.opened = false;
62        self.input.take().map_or(Ok(()), |mut input| input.close())
63    }
64    fn extend(&mut self, demand: NonZeroUsize) -> ExecResult<()> {
65        if let Some(error) = &self.failure {
66            return Err(ExecError::SQL(error.clone()));
67        }
68        let result = self.extend_input(demand);
69        if let Err(error) = result {
70            let error =
71                with_cleanup::<()>(Err(error), self.finish(), "close CTE producer").unwrap_err();
72            let error = physical_exec_error(error);
73            self.failure = Some(error.clone());
74            return Err(ExecError::SQL(error));
75        }
76        Ok(())
77    }
78    fn extend_input(&mut self, demand: NonZeroUsize) -> ExecResult<()> {
79        let Some(input) = self.input.as_mut() else {
80            return Ok(());
81        };
82        if !self.opened {
83            self.opened = true;
84            input.open()?;
85        }
86        let Some(batch) = input.next_with_demand(demand)? else {
87            return self.finish();
88        };
89        if &batch.schema != self.rows.row_schema() {
90            return Err(ExecError::Other(
91                "CTE producer changed its row schema".into(),
92            ));
93        }
94        for row in batch.rows {
95            self.rows.push(&row)?;
96        }
97        Ok(())
98    }
99}
100
101impl SharedPrefix {
102    /// End the producer at its owning query boundary, independently of how many readers still retain its cached rows.
103    pub(crate) fn close(&self) -> ExecResult<()> {
104        let mut state = self.state.lock();
105        state.finish().map_err(|error| {
106            let error = physical_exec_error(error);
107            state.failure = Some(error.clone());
108            ExecError::SQL(error)
109        })
110    }
111}
112impl Drop for PrefixState {
113    fn drop(&mut self) {
114        let _ = self.finish();
115    }
116}
117
118struct PrefixScan {
119    rows: SharedPrefix,
120    position: u64,
121}
122impl PrefixScan {
123    fn pull(&mut self, demand: NonZeroUsize) -> ExecResult<Option<Batch>> {
124        let mut state = self.rows.state.lock();
125        while self.position == state.rows.len()
126            && (state.input.is_some() || state.failure.is_some())
127        {
128            state.extend(demand)?;
129        }
130        if self.position == state.rows.len() {
131            return Ok(None);
132        }
133        let count = (state.rows.len() - self.position).min(demand.get() as u64);
134        let mut rows = Vec::with_capacity(count as usize);
135        for _ in 0..count {
136            rows.push(state.rows.get(self.position)?);
137            self.position += 1;
138        }
139        Ok(Some(Batch::from_physical_rows(
140            self.rows.schema.clone(),
141            rows,
142        )))
143    }
144}
145impl PhysicalOperator for PrefixScan {
146    fn backward_scan_support(&self) -> crate::BackwardScanSupport {
147        crate::BackwardScanSupport::Materialize
148    }
149    fn row_schema(&self) -> &RowSchema {
150        &self.rows.schema
151    }
152    fn open(&mut self) -> ExecResult<()> {
153        self.position = 0;
154        Ok(())
155    }
156    fn next(&mut self) -> ExecResult<Option<Batch>> {
157        self.pull(NonZeroUsize::new(crate::DEFAULT_BATCH_SIZE).expect("nonzero batch size"))
158    }
159    fn next_with_demand(&mut self, rows: NonZeroUsize) -> ExecResult<Option<Batch>> {
160        self.pull(rows)
161    }
162    fn close(&mut self) -> ExecResult<()> {
163        Ok(())
164    }
165}
166
167#[cfg(test)]
168mod tests;