Skip to main content

uqa_execution/relational/
filter.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Pipelined WHERE filtering.
8
9use super::{
10    truthy, BackwardScanSupport, Batch, DefaultExpressionEvaluator, ExecError, ExecResult,
11    PhysicalOperator, PhysicalScanDirection, RowSchema, SQLParam, ScalarExpr,
12    SharedExpressionEvaluator, SharedRowPredicate,
13};
14
15/// Pipelined `WHERE` operator. Drops rows whose predicate evaluates
16/// to `false` or `NULL`; truthy rows pass through unchanged.
17pub struct Filter<'a> {
18    child: Box<dyn PhysicalOperator + 'a>,
19    input_pending: crate::physical::demand::PendingRows,
20    condition: FilterCondition<'a>,
21    schema: RowSchema,
22}
23
24enum FilterCondition<'a> {
25    Expression {
26        predicate: crate::scalar::PreparedExpressions<ScalarExpr>,
27        evaluator: SharedExpressionEvaluator<'a>,
28    },
29    Row(SharedRowPredicate<'a>),
30    /// A predicate that names a column its input does not produce. Reading that column would yield NULL for every row, so the first input row reports the defect instead.
31    Unresolved(String),
32}
33
34impl Filter<'static> {
35    pub fn new(
36        child: Box<dyn PhysicalOperator>,
37        predicate: ScalarExpr,
38        params: Vec<SQLParam>,
39    ) -> Self {
40        Self::with_evaluator(child, predicate, DefaultExpressionEvaluator::shared(params))
41    }
42}
43
44impl<'a> Filter<'a> {
45    pub fn with_evaluator(
46        child: Box<dyn PhysicalOperator + 'a>,
47        predicate: ScalarExpr,
48        evaluator: SharedExpressionEvaluator<'a>,
49    ) -> Self {
50        let schema = child.row_schema().clone();
51        let predicate = evaluator.bind_type_introspection(predicate, &schema);
52        Self {
53            child,
54            input_pending: crate::physical::demand::PendingRows::default(),
55            condition: FilterCondition::Expression {
56                predicate: crate::scalar::PreparedExpressions::scalar(predicate),
57                evaluator,
58            },
59            schema,
60        }
61    }
62
63    pub fn with_row_predicate(
64        child: Box<dyn PhysicalOperator + 'a>,
65        predicate: SharedRowPredicate<'a>,
66    ) -> Self {
67        let schema = child.row_schema().clone();
68        Self {
69            child,
70            input_pending: crate::physical::demand::PendingRows::default(),
71            condition: FilterCondition::Row(predicate),
72            schema,
73        }
74    }
75
76    /// A filter whose predicate reads `column`, which `child` does not produce. Statement validation reports a user's unknown column before execution, so a row reaching this filter exposes a predicate that was placed on the wrong input; it fails with an internal error instead of reading NULL.
77    pub fn unresolved(child: Box<dyn PhysicalOperator + 'a>, column: String) -> Self {
78        let schema = child.row_schema().clone();
79        Self {
80            child,
81            input_pending: crate::physical::demand::PendingRows::default(),
82            condition: FilterCondition::Unresolved(column),
83            schema,
84        }
85    }
86
87    fn filter_batch(&self, batch: Batch) -> ExecResult<Option<Batch>> {
88        let mut kept = Vec::with_capacity(batch.rows.len());
89        for row in batch.rows {
90            let keep = match &self.condition {
91                FilterCondition::Expression {
92                    predicate,
93                    evaluator,
94                } => truthy(&evaluator.evaluate_physical_with_function_states(
95                    predicate,
96                    &batch.schema,
97                    &row,
98                    predicate.calls(),
99                )?),
100                FilterCondition::Row(predicate) => predicate.keep_physical(&batch.schema, &row)?,
101                FilterCondition::Unresolved(column) => {
102                    return Err(ExecError::SQL(uqa_sql::SQLError::Internal(format!(
103                        "a predicate placed on its input reads {column}, which the input does not produce"
104                    ))));
105                }
106            };
107            if keep {
108                kept.push(row);
109            }
110        }
111        Ok((!kept.is_empty()).then(|| Batch::from_physical_rows(self.schema.clone(), kept)))
112    }
113}
114
115impl Filter<'_> {
116    fn pull(&mut self, demand: Option<std::num::NonZeroUsize>) -> ExecResult<Option<Batch>> {
117        let Some(demand) = demand else {
118            loop {
119                let Some(batch) = self.input_pending.pull(self.child.as_mut(), None)? else {
120                    return Ok(None);
121                };
122                if let Some(batch) = self.filter_batch(batch)? {
123                    return Ok(Some(batch));
124                }
125            }
126        };
127        let mut kept = Vec::new();
128        while kept.len() < demand.get() {
129            let Some(batch) = self
130                .input_pending
131                .pull(self.child.as_mut(), Some(crate::physical::demand::ONE))?
132            else {
133                break;
134            };
135            if let Some(batch) = self.filter_batch(batch)? {
136                kept.extend(batch.rows);
137            }
138        }
139        Ok((!kept.is_empty()).then(|| Batch::from_physical_rows(self.schema.clone(), kept)))
140    }
141}
142
143impl PhysicalOperator for Filter<'_> {
144    fn row_schema(&self) -> &RowSchema {
145        &self.schema
146    }
147
148    fn estimated_cardinality(&self) -> Option<u64> {
149        self.child.estimated_cardinality()
150    }
151
152    fn output_ordering(&self) -> &[crate::PhysicalOrder] {
153        self.child.output_ordering()
154    }
155
156    fn backward_scan_support(&self) -> BackwardScanSupport {
157        if self.child.backward_scan_support() == BackwardScanSupport::Native {
158            BackwardScanSupport::Native
159        } else {
160            BackwardScanSupport::Unsupported
161        }
162    }
163
164    fn open(&mut self) -> ExecResult<()> {
165        self.input_pending.clear();
166        self.child.open()
167    }
168
169    fn next(&mut self) -> ExecResult<Option<Batch>> {
170        self.pull(None)
171    }
172
173    fn next_with_demand(&mut self, rows: std::num::NonZeroUsize) -> ExecResult<Option<Batch>> {
174        self.pull(Some(rows))
175    }
176
177    fn next_direction(&mut self, direction: PhysicalScanDirection) -> ExecResult<Option<Batch>> {
178        loop {
179            let Some(batch) = self.child.next_direction(direction)? else {
180                return Ok(None);
181            };
182            if let Some(batch) = self.filter_batch(batch)? {
183                return Ok(Some(batch));
184            }
185        }
186    }
187
188    fn rewind(&mut self) -> ExecResult<()> {
189        self.input_pending.clear();
190        self.child.rewind()
191    }
192
193    fn close(&mut self) -> ExecResult<()> {
194        self.input_pending.clear();
195        self.child.close()
196    }
197}