Skip to main content

uqa_execution/query/
consumer.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Row-delivery and directional-control protocol for physical query execution.
8
9use crate::{Batch, OwnedPhysicalRow, RowSchema};
10use uqa_sql::SQLError;
11
12pub trait QueryRowConsumer {
13    fn begin(&self, columns: &[String], schema: &RowSchema) -> Result<(), SQLError>;
14
15    /// Let a complete native result consumer collect borrowed values after `begin` and input `open`. The default declines without consuming input; arbitrary callbacks retain their ordinary row-delivery boundary.
16    fn collect_native_materialized(
17        &self,
18        _operator: &mut dyn crate::PhysicalOperator,
19        _cancellation: &uqa_core::CancellationToken,
20    ) -> crate::ExecResult<bool> {
21        Ok(false)
22    }
23
24    fn consume(&self, row: OwnedPhysicalRow) -> Result<QueryConsumerControl, SQLError>;
25
26    fn consume_batch(&self, batch: Batch) -> Result<QueryConsumerControl, SQLError> {
27        for row in batch.rows {
28            let control = self.consume(OwnedPhysicalRow::new(batch.schema.clone(), row))?;
29            if control != QueryConsumerControl::Continue {
30                return Ok(control);
31            }
32        }
33        Ok(QueryConsumerControl::Continue)
34    }
35
36    /// Requested output rows before this consumer receives control. The default retains row-level demand for stop and error boundaries. A consumer that accepts all input without per-row observable effects or failures may return `None`; native batches additionally require the producer's ordering guarantee.
37    fn input_demand(&self) -> Option<std::num::NonZeroUsize> {
38        Some(crate::physical::demand::ONE)
39    }
40
41    /// Whether UNION ALL may deliver directly from each child instead of its ordinary set operator.
42    fn streams_set_inputs(&self) -> bool {
43        true
44    }
45
46    fn uses_directional_scan(&self) -> bool {
47        false
48    }
49
50    fn directional_scan_prepared(
51        &self,
52        _support: crate::BackwardScanSupport,
53    ) -> Result<(), SQLError> {
54        Ok(())
55    }
56
57    fn scan_direction(&self) -> crate::PhysicalScanDirection {
58        crate::PhysicalScanDirection::Forward
59    }
60
61    fn direction_exhausted(&self) -> Result<QueryConsumerControl, SQLError> {
62        Ok(QueryConsumerControl::Stop)
63    }
64
65    fn rewound(&self) -> Result<QueryConsumerControl, SQLError> {
66        Ok(QueryConsumerControl::Continue)
67    }
68}
69
70#[derive(Clone, Copy, PartialEq, Eq)]
71pub enum QueryConsumerControl {
72    Continue,
73    Stop,
74    Rewind,
75}
76
77#[derive(Clone)]
78pub enum QueryOutputMode<'a> {
79    Rows,
80    SharedSpill,
81    ExistsKeySet(Option<&'a dyn uqa_sql::expr::SQLValueCatalog>),
82    RowConsumer(std::rc::Rc<dyn QueryRowConsumer + 'a>),
83}