Skip to main content

uqa_execution/query/statement/
consumer.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Bind output sinks to an opaque read generation before physical row delivery.
8use crate::query::consumer as physical;
9pub use physical::QueryConsumerControl;
10use std::{cell::Cell, rc::Rc};
11use uqa_core::Value;
12use uqa_sql::{type_resolution::coerce_common_context_value, SQLError};
13
14/// A row sink chooses its own services for the selected generation; query execution supplies no writable context.
15pub trait QueryConsumerFactory<'consumer, S: Clone + 'static> {
16    fn bind(
17        self: Rc<Self>,
18        generation: Option<&S>,
19    ) -> Result<Rc<dyn physical::QueryRowConsumer + 'consumer>, SQLError>;
20    fn uses_directional_scan(&self) -> bool {
21        false
22    }
23}
24
25pub(crate) struct SetOperationConsumerFactory<'consumer, S: Clone + 'static> {
26    downstream: Rc<dyn QueryConsumerFactory<'consumer, S> + 'consumer>,
27    state: Rc<SetOperationState>,
28}
29struct SetOperationState {
30    columns: Vec<String>,
31    schema: crate::RowSchema,
32    offset: Cell<u64>,
33    remaining: Cell<Option<u64>>,
34    begun: Cell<bool>,
35    stopped: Cell<bool>,
36}
37impl<'consumer, S: Clone + 'static> SetOperationConsumerFactory<'consumer, S> {
38    pub(crate) fn new(
39        downstream: Rc<dyn QueryConsumerFactory<'consumer, S> + 'consumer>,
40        schema: crate::RowSchema,
41        offset: u64,
42        limit: Option<u64>,
43    ) -> Self {
44        Self {
45            downstream,
46            state: Rc::new(SetOperationState {
47                columns: schema.columns().to_vec(),
48                schema,
49                offset: Cell::new(offset),
50                remaining: Cell::new(limit),
51                begun: Cell::new(false),
52                stopped: Cell::new(limit == Some(0)),
53            }),
54        }
55    }
56    pub(crate) fn stopped(&self) -> bool {
57        self.state.stopped.get()
58    }
59}
60impl<'consumer, S: Clone + 'static> QueryConsumerFactory<'consumer, S>
61    for SetOperationConsumerFactory<'consumer, S>
62{
63    fn bind(
64        self: Rc<Self>,
65        generation: Option<&S>,
66    ) -> Result<Rc<dyn physical::QueryRowConsumer + 'consumer>, SQLError> {
67        Ok(Rc::new(SetOperationRowConsumer {
68            downstream: Rc::clone(&self.downstream).bind(generation)?,
69            state: Rc::clone(&self.state),
70        }))
71    }
72}
73struct SetOperationRowConsumer<'consumer> {
74    downstream: Rc<dyn physical::QueryRowConsumer + 'consumer>,
75    state: Rc<SetOperationState>,
76}
77impl SetOperationRowConsumer<'_> {
78    fn stopped(&self) -> bool {
79        self.state.stopped.get()
80    }
81}
82impl physical::QueryRowConsumer for SetOperationRowConsumer<'_> {
83    fn begin(&self, columns: &[String], _schema: &crate::RowSchema) -> Result<(), SQLError> {
84        if columns.len() != self.state.columns.len() {
85            return Err(SQLError::TypeMismatch(format!(
86                "set-operation input width {} does not match output width {}",
87                columns.len(),
88                self.state.columns.len()
89            )));
90        }
91        if self.state.begun.replace(true) {
92            Ok(())
93        } else {
94            self.downstream
95                .begin(&self.state.columns, &self.state.schema)
96        }
97    }
98
99    fn consume(&self, row: crate::OwnedPhysicalRow) -> Result<QueryConsumerControl, SQLError> {
100        if self.stopped() {
101            return Ok(QueryConsumerControl::Stop);
102        }
103        if self.state.offset.get() > 0 {
104            self.state.offset.set(self.state.offset.get() - 1);
105            return Ok(QueryConsumerControl::Continue);
106        }
107        if self.state.remaining.get() == Some(0) {
108            self.state.stopped.set(true);
109            return Ok(QueryConsumerControl::Stop);
110        }
111        let projections = {
112            let view = row.view();
113            self.state
114                .schema
115                .column_types()
116                .iter()
117                .enumerate()
118                .map(|(position, target_type)| {
119                    let source_type = row.schema.column_type(position);
120                    if target_type
121                        .as_ref()
122                        .is_some_and(|target_type| source_type != Some(target_type))
123                    {
124                        let value = view.value_at(position).cloned().unwrap_or(Value::Null);
125                        return coerce_common_context_value(
126                            value,
127                            source_type,
128                            target_type.as_ref(),
129                        )
130                        .map(crate::RowProjectionValue::Owned);
131                    }
132                    Ok(row.schema.physical_slot(position).map_or(
133                        crate::RowProjectionValue::Owned(Value::Null),
134                        crate::RowProjectionValue::InputSlot,
135                    ))
136                })
137                .collect::<Result<Vec<_>, SQLError>>()?
138        };
139        let control = self.downstream.consume(crate::OwnedPhysicalRow::new(
140            self.state.schema.clone(),
141            row.row
142                .project_with_values(projections)
143                .without_lock_origins(),
144        ))?;
145        match control {
146            QueryConsumerControl::Continue => {}
147            QueryConsumerControl::Stop => {
148                self.state.stopped.set(true);
149                return Ok(control);
150            }
151            QueryConsumerControl::Rewind => {
152                return Err(SQLError::Internal(
153                    "set-operation consumer received a directional rewind".into(),
154                ));
155            }
156        }
157        if let Some(remaining) = self.state.remaining.get() {
158            let remaining = remaining - 1;
159            self.state.remaining.set(Some(remaining));
160            if remaining == 0 {
161                self.state.stopped.set(true);
162                return Ok(QueryConsumerControl::Stop);
163            }
164        }
165        Ok(QueryConsumerControl::Continue)
166    }
167}
168
169#[derive(Clone)]
170pub enum QueryOutputMode<'consumer, S: Clone + 'static> {
171    Rows,
172    SharedSpill,
173    ExistsKeySet,
174    RowConsumer(Rc<dyn QueryConsumerFactory<'consumer, S> + 'consumer>),
175}
176impl<'consumer, S: Clone + 'static> QueryOutputMode<'consumer, S> {
177    pub fn physical_consumer(consumer: Rc<dyn physical::QueryRowConsumer + 'consumer>) -> Self {
178        Self::RowConsumer(Rc::new(PhysicalConsumer(consumer)))
179    }
180}
181struct PhysicalConsumer<'consumer>(Rc<dyn physical::QueryRowConsumer + 'consumer>);
182impl<'consumer, S: Clone + 'static> QueryConsumerFactory<'consumer, S>
183    for PhysicalConsumer<'consumer>
184{
185    fn bind(
186        self: Rc<Self>,
187        _generation: Option<&S>,
188    ) -> Result<Rc<dyn physical::QueryRowConsumer + 'consumer>, SQLError> {
189        Ok(Rc::clone(&self.0))
190    }
191    fn uses_directional_scan(&self) -> bool {
192        self.0.uses_directional_scan()
193    }
194}