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_core::memory::{MemoryReservation, ProductionControl};
15use uqa_sql::SQLError;
16
17#[derive(Clone)]
18pub enum CteRows {
19    Complete(SharedSpill),
20    Prefix(SharedPrefix),
21}
22impl CteRows {
23    pub fn row_schema(&self) -> &RowSchema {
24        match self {
25            Self::Complete(rows) => rows.row_schema(),
26            Self::Prefix(rows) => &rows.schema,
27        }
28    }
29    pub fn into_operator(self) -> Box<dyn PhysicalOperator> {
30        self.into_operator_with_control(&ProductionControl::uncontrolled())
31            .expect("ordinary CTE reader")
32    }
33    pub fn into_operator_with_control(
34        self,
35        control: &ProductionControl<'_>,
36    ) -> Result<Box<dyn PhysicalOperator>, SQLError> {
37        match self {
38            Self::Complete(rows) => Ok(crate::SharedSpillScan::boxed_with_control(rows, control)?),
39            Self::Prefix(rows) => {
40                let memory = control.reserve(size_of::<PrefixScan>())?;
41                Ok(Box::new(PrefixScan {
42                    rows,
43                    position: 0,
44                    _memory: memory,
45                }))
46            }
47        }
48    }
49    #[cfg(test)]
50    pub(crate) fn from_producer(input: Box<dyn PhysicalOperator>, budget: usize) -> Self {
51        Self::from_producer_with_control(input, budget, &ProductionControl::uncontrolled())
52            .expect("ordinary CTE producer")
53    }
54
55    pub(crate) fn from_producer_with_control(
56        input: Box<dyn PhysicalOperator>,
57        budget: usize,
58        control: &ProductionControl<'_>,
59    ) -> Result<Self, SQLError> {
60        let (input, memory) = crate::physical::construction::OperatorBuild::run(input, |_| {
61            Ok(control.reserve(size_of::<Mutex<PrefixState>>())?)
62        })?;
63        let schema = input.row_schema().clone();
64        Ok(Self::Prefix(SharedPrefix {
65            schema: schema.clone(),
66            state: Arc::new(Mutex::new(PrefixState {
67                rows: BufferedIndexedSpill::new(schema, budget),
68                input: Some(input),
69                opened: false,
70                failure: None,
71                _memory: memory,
72            })),
73        }))
74    }
75}
76
77#[derive(Clone)]
78pub struct SharedPrefix {
79    schema: RowSchema,
80    state: Arc<Mutex<PrefixState>>,
81}
82struct PrefixState {
83    rows: BufferedIndexedSpill,
84    input: Option<Box<dyn PhysicalOperator>>,
85    opened: bool,
86    failure: Option<SQLError>,
87    _memory: Option<MemoryReservation>,
88}
89impl PrefixState {
90    fn finish(&mut self) -> ExecResult<()> {
91        self.opened = false;
92        self.input.take().map_or(Ok(()), |mut input| input.close())
93    }
94    fn extend(&mut self, demand: NonZeroUsize) -> ExecResult<()> {
95        if let Some(error) = &self.failure {
96            return Err(ExecError::SQL(error.clone()));
97        }
98        let result = self.extend_input(demand);
99        if let Err(error) = result {
100            let error =
101                with_cleanup::<()>(Err(error), self.finish(), "close CTE producer").unwrap_err();
102            let error = physical_exec_error(error);
103            self.failure = Some(error.clone());
104            return Err(ExecError::SQL(error));
105        }
106        Ok(())
107    }
108    fn extend_input(&mut self, demand: NonZeroUsize) -> ExecResult<()> {
109        let Some(input) = self.input.as_mut() else {
110            return Ok(());
111        };
112        if !self.opened {
113            self.opened = true;
114            input.open()?;
115        }
116        let Some(batch) = input.next_with_demand(demand)? else {
117            return self.finish();
118        };
119        if &batch.schema != self.rows.row_schema() {
120            return Err(ExecError::Other(
121                "CTE producer changed its row schema".into(),
122            ));
123        }
124        for row in batch.rows {
125            self.rows.push(&row)?;
126        }
127        Ok(())
128    }
129}
130
131impl SharedPrefix {
132    /// End the producer at its owning query boundary, independently of how many readers still retain its cached rows.
133    pub(crate) fn close(&self) -> ExecResult<()> {
134        let mut state = self.state.lock();
135        state.finish().map_err(|error| {
136            let error = physical_exec_error(error);
137            state.failure = Some(error.clone());
138            ExecError::SQL(error)
139        })
140    }
141}
142impl Drop for PrefixState {
143    fn drop(&mut self) {
144        let _ = self.finish();
145    }
146}
147
148struct PrefixScan {
149    rows: SharedPrefix,
150    position: u64,
151    _memory: Option<MemoryReservation>,
152}
153impl PrefixScan {
154    fn pull(&mut self, demand: NonZeroUsize) -> ExecResult<Option<Batch>> {
155        let mut state = self.rows.state.lock();
156        while self.position == state.rows.len()
157            && (state.input.is_some() || state.failure.is_some())
158        {
159            state.extend(demand)?;
160        }
161        if self.position == state.rows.len() {
162            return Ok(None);
163        }
164        let count = (state.rows.len() - self.position).min(demand.get() as u64);
165        let mut rows = Vec::with_capacity(count as usize);
166        for _ in 0..count {
167            rows.push(state.rows.get(self.position)?);
168            self.position += 1;
169        }
170        Ok(Some(Batch::from_physical_rows(
171            self.rows.schema.clone(),
172            rows,
173        )))
174    }
175}
176impl PhysicalOperator for PrefixScan {
177    fn backward_scan_support(&self) -> crate::BackwardScanSupport {
178        crate::BackwardScanSupport::Materialize
179    }
180    fn row_schema(&self) -> &RowSchema {
181        &self.rows.schema
182    }
183    fn open(&mut self) -> ExecResult<()> {
184        self.position = 0;
185        Ok(())
186    }
187    fn next(&mut self) -> ExecResult<Option<Batch>> {
188        self.pull(NonZeroUsize::new(crate::DEFAULT_BATCH_SIZE).expect("nonzero batch size"))
189    }
190    fn next_with_demand(&mut self, rows: NonZeroUsize) -> ExecResult<Option<Batch>> {
191        self.pull(rows)
192    }
193    fn close(&mut self) -> ExecResult<()> {
194        Ok(())
195    }
196}
197
198#[cfg(test)]
199mod tests;