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    condition: FilterCondition<'a>,
20    schema: RowSchema,
21}
22
23enum FilterCondition<'a> {
24    Expression {
25        predicate: crate::scalar::PreparedExpressions<ScalarExpr>,
26        evaluator: SharedExpressionEvaluator<'a>,
27    },
28    Row(SharedRowPredicate<'a>),
29    /// 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.
30    Unresolved(String),
31}
32
33impl Filter<'static> {
34    pub fn new(
35        child: Box<dyn PhysicalOperator>,
36        predicate: ScalarExpr,
37        params: Vec<SQLParam>,
38    ) -> Self {
39        Self::with_evaluator(child, predicate, DefaultExpressionEvaluator::shared(params))
40    }
41}
42
43impl<'a> Filter<'a> {
44    pub fn with_evaluator(
45        child: Box<dyn PhysicalOperator + 'a>,
46        predicate: ScalarExpr,
47        evaluator: SharedExpressionEvaluator<'a>,
48    ) -> Self {
49        let schema = child.row_schema().clone();
50        let predicate = evaluator.bind_type_introspection(predicate, &schema);
51        Self {
52            child,
53            condition: FilterCondition::Expression {
54                predicate: crate::scalar::PreparedExpressions::scalar(predicate),
55                evaluator,
56            },
57            schema,
58        }
59    }
60
61    pub fn with_row_predicate(
62        child: Box<dyn PhysicalOperator + 'a>,
63        predicate: SharedRowPredicate<'a>,
64    ) -> Self {
65        let schema = child.row_schema().clone();
66        Self {
67            child,
68            condition: FilterCondition::Row(predicate),
69            schema,
70        }
71    }
72
73    /// 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.
74    pub fn unresolved(child: Box<dyn PhysicalOperator + 'a>, column: String) -> Self {
75        let schema = child.row_schema().clone();
76        Self {
77            child,
78            condition: FilterCondition::Unresolved(column),
79            schema,
80        }
81    }
82
83    fn filter_batch(&self, batch: Batch) -> ExecResult<Option<Batch>> {
84        let mut kept = Vec::with_capacity(batch.rows.len());
85        for row in batch.rows {
86            let keep = match &self.condition {
87                FilterCondition::Expression {
88                    predicate,
89                    evaluator,
90                } => truthy(&evaluator.evaluate_physical_with_function_states(
91                    predicate,
92                    &batch.schema,
93                    &row,
94                    predicate.calls(),
95                )?),
96                FilterCondition::Row(predicate) => predicate.keep_physical(&batch.schema, &row)?,
97                FilterCondition::Unresolved(column) => {
98                    return Err(ExecError::SQL(uqa_sql::SQLError::Internal(format!(
99                        "a predicate placed on its input reads {column}, which the input does not produce"
100                    ))));
101                }
102            };
103            if keep {
104                kept.push(row);
105            }
106        }
107        Ok((!kept.is_empty()).then(|| Batch::from_physical_rows(self.schema.clone(), kept)))
108    }
109}
110
111impl PhysicalOperator for Filter<'_> {
112    fn row_schema(&self) -> &RowSchema {
113        &self.schema
114    }
115
116    fn estimated_cardinality(&self) -> Option<u64> {
117        self.child.estimated_cardinality()
118    }
119
120    fn output_ordering(&self) -> &[crate::PhysicalOrder] {
121        self.child.output_ordering()
122    }
123
124    fn backward_scan_support(&self) -> BackwardScanSupport {
125        if self.child.backward_scan_support() == BackwardScanSupport::Native {
126            BackwardScanSupport::Native
127        } else {
128            BackwardScanSupport::Unsupported
129        }
130    }
131
132    fn open(&mut self) -> ExecResult<()> {
133        self.child.open()
134    }
135
136    fn next(&mut self) -> ExecResult<Option<Batch>> {
137        loop {
138            let Some(batch) = self.child.next()? else {
139                return Ok(None);
140            };
141            if let Some(batch) = self.filter_batch(batch)? {
142                return Ok(Some(batch));
143            }
144        }
145    }
146
147    fn next_direction(&mut self, direction: PhysicalScanDirection) -> ExecResult<Option<Batch>> {
148        loop {
149            let Some(batch) = self.child.next_direction(direction)? else {
150                return Ok(None);
151            };
152            if let Some(batch) = self.filter_batch(batch)? {
153                return Ok(Some(batch));
154            }
155        }
156    }
157
158    fn rewind(&mut self) -> ExecResult<()> {
159        self.child.rewind()
160    }
161
162    fn close(&mut self) -> ExecResult<()> {
163        self.child.close()
164    }
165}