Skip to main content

uqa_execution/catalog/index/value/cache/
probes.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Retained probes use the resident accelerator's eligibility and fallible SQL comparison rules.
8
9use super::{comparison, storage, ValueIndexCache};
10use std::ops::Bound::{self, Excluded, Included, Unbounded};
11use uqa_core::{DocId, PostingList, Predicate, Value};
12use uqa_sql::{expr::SQLValueCatalog, SQLError};
13use uqa_storage::read_control::StorageReadControl;
14
15impl ValueIndexCache {
16    pub fn visit_key_candidates_with_catalog(
17        &self,
18        predicate: &Predicate,
19        catalog: Option<&dyn SQLValueCatalog>,
20        control: &StorageReadControl,
21        visit: &mut dyn FnMut(DocId) -> Result<(), SQLError>,
22    ) -> Result<bool, SQLError> {
23        if !matches!(predicate, Predicate::Equals(_) | Predicate::IsNull) {
24            return Ok(false);
25        }
26        self.visit(predicate, catalog, control, visit)
27    }
28
29    fn visit(
30        &self,
31        predicate: &Predicate,
32        catalog: Option<&dyn SQLValueCatalog>,
33        control: &StorageReadControl,
34        visit: &mut dyn FnMut(DocId) -> Result<(), SQLError>,
35    ) -> Result<bool, SQLError> {
36        if self.is_carried() {
37            return Ok(false);
38        }
39        if comparison::needs_sql_comparison(predicate, self.policy.comparison.can_fail()) {
40            if let Some(values) = &self.retained {
41                let mut failure = None;
42                let result = values.visit_values(control, &mut |id, value| {
43                    let next = comparison::matches(&value, predicate, catalog)
44                        .and_then(|matched| if matched { visit(id) } else { Ok(()) });
45                    match next {
46                        Ok(()) => Ok(true),
47                        Err(error) => {
48                            failure = Some(error);
49                            Ok(false)
50                        }
51                    }
52                });
53                if let Some(error) = failure {
54                    return Err(error);
55                }
56                result.map_err(storage)?;
57            } else {
58                for (&id, value) in &self.policy.values {
59                    control.check().map_err(storage)?;
60                    if comparison::matches(value, predicate, catalog)? {
61                        visit(id)?;
62                    }
63                }
64            }
65            return Ok(true);
66        }
67        if !self.supports(predicate) {
68            return Ok(false);
69        }
70        let Some(values) = &self.retained else {
71            return self.policy.visit_observing_with_catalog(
72                predicate,
73                catalog,
74                || Ok(()),
75                &mut |id| {
76                    control.check().map_err(storage)?;
77                    visit(id)
78                },
79            );
80        };
81        ranges(predicate, &mut |low, high| {
82            let mut failure = None;
83            let result = values.visit_range(low, high, control, &mut |id| match visit(id) {
84                Ok(()) => Ok(true),
85                Err(error) => {
86                    failure = Some(error);
87                    Ok(false)
88                }
89            });
90            failure.map_or_else(|| result.map_err(storage), Err)
91        })?;
92        Ok(true)
93    }
94
95    pub fn visit_observing_with_catalog(
96        &self,
97        predicate: &Predicate,
98        catalog: Option<&dyn SQLValueCatalog>,
99        control: &StorageReadControl,
100        observe: impl FnOnce() -> Result<(), SQLError>,
101        visit: &mut dyn FnMut(DocId) -> Result<(), SQLError>,
102    ) -> Result<bool, SQLError> {
103        if self.is_carried()
104            || (!self.supports(predicate)
105                && !comparison::needs_sql_comparison(predicate, self.policy.comparison.can_fail()))
106        {
107            return Ok(false);
108        }
109        control.check().map_err(storage)?;
110        observe()?;
111        self.visit(predicate, catalog, control, visit)
112    }
113
114    pub fn scan_observing_with_catalog(
115        &self,
116        predicate: &Predicate,
117        catalog: Option<&dyn SQLValueCatalog>,
118        control: &StorageReadControl,
119        observe: impl FnOnce() -> Result<(), SQLError>,
120    ) -> Result<Option<PostingList>, SQLError> {
121        if self.retained.is_none() {
122            return self
123                .policy
124                .scan_observing_with_catalog(predicate, catalog, observe);
125        }
126        if self.is_carried()
127            || (!self.supports(predicate)
128                && !comparison::needs_sql_comparison(predicate, self.policy.comparison.can_fail()))
129        {
130            return Ok(None);
131        }
132        observe()?;
133        let mut ids = Vec::new();
134        self.visit(predicate, catalog, control, &mut |id| {
135            ids.push(id);
136            Ok(())
137        })?;
138        ids.sort_unstable();
139        ids.dedup();
140        Ok(Some(super::super::posting_list_from_sorted_ids(
141            ids.into_iter(),
142        )))
143    }
144
145    pub fn field_candidates(
146        &self,
147        value: &Value,
148        control: &StorageReadControl,
149    ) -> Result<Option<PostingList>, SQLError> {
150        if !super::super::field_is_index_safe(value) {
151            return Ok(None);
152        }
153        let predicate = if matches!(value, Value::Null) {
154            Predicate::IsNull
155        } else {
156            if self.policy.comparison.field_needs_evaluation() {
157                return Ok(None);
158            }
159            Predicate::Equals(value.clone())
160        };
161        self.scan_observing_with_catalog(&predicate, None, control, || Ok(()))
162    }
163
164    pub fn estimate_cardinality(
165        &self,
166        predicate: &Predicate,
167        control: &StorageReadControl,
168    ) -> Result<Option<usize>, SQLError> {
169        if !self.supports(predicate) {
170            return Ok(None);
171        }
172        let Some(values) = &self.retained else {
173            return Ok(self.policy.estimate_cardinality(predicate));
174        };
175        let mut count = 0_usize;
176        ranges(predicate, &mut |low, high| {
177            count = count.saturating_add(values.count_range(low, high, control).map_err(storage)?);
178            Ok(())
179        })?;
180        Ok(Some(count))
181    }
182}
183
184type RangeVisitor<'a> = dyn FnMut(Bound<&Value>, Bound<&Value>) -> Result<(), SQLError> + 'a;
185
186fn ranges(predicate: &Predicate, visit: &mut RangeVisitor<'_>) -> Result<(), SQLError> {
187    let non_null = Excluded(&Value::Null);
188    match predicate {
189        Predicate::Equals(Value::Null)
190        | Predicate::LessThan(Value::Null)
191        | Predicate::LessThanOrEqual(Value::Null) => Ok(()),
192        Predicate::Equals(value) => visit(Included(value), Included(value)),
193        Predicate::IsNull => visit(Included(&Value::Null), Included(&Value::Null)),
194        Predicate::IsNotNull | Predicate::GreaterThanOrEqual(Value::Null) => {
195            visit(non_null, Unbounded)
196        }
197        Predicate::GreaterThan(value) => visit(Excluded(value), Unbounded),
198        Predicate::GreaterThanOrEqual(value) => visit(Included(value), Unbounded),
199        Predicate::LessThan(value) => visit(non_null, Excluded(value)),
200        Predicate::LessThanOrEqual(value) => visit(non_null, Included(value)),
201        Predicate::Between { low, high } if low > high => Ok(()),
202        Predicate::Between { low, high } => visit(
203            if matches!(low, Value::Null) {
204                non_null
205            } else {
206                Included(low)
207            },
208            Included(high),
209        ),
210        Predicate::InSet(values) => {
211            // InSet already uses Core-ordered distinct values; posting results restore document order at their existing output boundary.
212            for value in values {
213                if !matches!(value, Value::Null) {
214                    visit(Included(value), Included(value))?;
215                }
216            }
217            Ok(())
218        }
219        Predicate::NotEquals(_) => unreachable!("unsupported complement predicate"),
220    }
221}