Skip to main content

uqa_execution/query/
subqueries.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Execute scalar subqueries with scope-local caches and correlated key probes.
8
9use super::scope::subqueries::ScalarSubqueryCacheEntry;
10use crate::scalar::plan::{PhysicalOuterRow, PhysicalSubqueryRunner};
11use std::sync::Arc;
12use uqa_core::Value;
13use uqa_sql::{
14    plan::QueryPlan, semantics::volatility::query_contains_volatile_function, SQLError, SQLParam,
15};
16
17mod analysis;
18pub mod context;
19mod execution;
20mod probe;
21mod single_row;
22pub use context::{SubqueryContext, SubqueryServices};
23pub use probe::prepare_correlated_exists_predicate;
24
25#[cfg(test)]
26mod test_support;
27#[cfg(test)]
28mod tests;
29
30impl<S: Clone + Send + Sync + 'static> PhysicalSubqueryRunner for SubqueryContext<'_, S> {
31    fn execute_subquery(
32        &self,
33        subquery: usize,
34        plan: &QueryPlan,
35        outer_row: PhysicalOuterRow<'_>,
36        params: &[SQLParam],
37    ) -> Result<crate::SubqueryResult, SQLError> {
38        let cached = self.ctes.cached_subquery(subquery);
39        if let Some(entry) = cached {
40            match entry {
41                ScalarSubqueryCacheEntry::Correlated => {
42                    return self.execute_correlated_subquery(plan, outer_row, params);
43                }
44                ScalarSubqueryCacheEntry::Materialized(result) => return result.result(),
45                ScalarSubqueryCacheEntry::Scalar(_)
46                | ScalarSubqueryCacheEntry::Row(_)
47                | ScalarSubqueryCacheEntry::Exists(_)
48                | ScalarSubqueryCacheEntry::Membership(_)
49                | ScalarSubqueryCacheEntry::ComparedMembership(_)
50                | ScalarSubqueryCacheEntry::CorrelatedExists(_) => {
51                    return Err(SQLError::Internal(
52                        "scalar subquery slot changed result consumer during execution".into(),
53                    ));
54                }
55            }
56        }
57
58        if analysis::query_depends_on_outer_row(&self.services, self.ctes, plan)? {
59            self.ctes
60                .cache_subquery(subquery, ScalarSubqueryCacheEntry::Correlated);
61            return self.execute_correlated_subquery(plan, outer_row, params);
62        }
63
64        let result = self.execute_uncorrelated_subquery(plan, params)?;
65        self.ctes.cache_subquery(
66            subquery,
67            ScalarSubqueryCacheEntry::Materialized(result.clone()),
68        );
69        result.result()
70    }
71
72    fn row_subquery_value(
73        &self,
74        subquery: usize,
75        plan: &QueryPlan,
76        outer_row: PhysicalOuterRow<'_>,
77        params: &[SQLParam],
78    ) -> Result<Option<crate::OwnedPhysicalRow>, SQLError> {
79        if let Some(entry) = self.ctes.cached_subquery(subquery) {
80            return match entry {
81                ScalarSubqueryCacheEntry::Correlated => {
82                    self.execute_correlated_single_row(plan, outer_row, params)
83                }
84                ScalarSubqueryCacheEntry::Row(row) => Ok(row),
85                ScalarSubqueryCacheEntry::Materialized(result) => {
86                    result.result()?.into_single_row()
87                }
88                _ => Err(SQLError::Internal(
89                    "scalar subquery slot changed result consumer during execution".into(),
90                )),
91            };
92        }
93        if analysis::query_depends_on_outer_row(&self.services, self.ctes, plan)? {
94            self.ctes
95                .cache_subquery(subquery, ScalarSubqueryCacheEntry::Correlated);
96            return self.execute_correlated_single_row(plan, outer_row, params);
97        }
98        let row = self.execute_single_row_subquery(plan, PhysicalOuterRow::Absent, params)?;
99        self.ctes
100            .cache_subquery(subquery, ScalarSubqueryCacheEntry::Row(row.clone()));
101        Ok(row)
102    }
103
104    fn scalar_subquery_value(
105        &self,
106        subquery: usize,
107        plan: &QueryPlan,
108        outer_row: PhysicalOuterRow<'_>,
109        params: &[SQLParam],
110    ) -> Result<Value, SQLError> {
111        let cached = self.ctes.cached_subquery(subquery);
112        if let Some(entry) = cached {
113            return match entry {
114                ScalarSubqueryCacheEntry::Correlated => self
115                    .execute_correlated_single_row(plan, outer_row, params)
116                    .map(single_row::scalar_value),
117                ScalarSubqueryCacheEntry::Scalar(value) => Ok(value),
118                ScalarSubqueryCacheEntry::Materialized(result) => {
119                    result.result()?.into_scalar_value()
120                }
121                ScalarSubqueryCacheEntry::Row(_)
122                | ScalarSubqueryCacheEntry::Exists(_)
123                | ScalarSubqueryCacheEntry::Membership(_)
124                | ScalarSubqueryCacheEntry::ComparedMembership(_)
125                | ScalarSubqueryCacheEntry::CorrelatedExists(_) => Err(SQLError::Internal(
126                    "scalar subquery slot changed result consumer during execution".into(),
127                )),
128            };
129        }
130        if analysis::query_depends_on_outer_row(&self.services, self.ctes, plan)? {
131            self.ctes
132                .cache_subquery(subquery, ScalarSubqueryCacheEntry::Correlated);
133            return self
134                .execute_correlated_single_row(plan, outer_row, params)
135                .map(single_row::scalar_value);
136        }
137        let value = single_row::scalar_value(self.execute_single_row_subquery(
138            plan,
139            PhysicalOuterRow::Absent,
140            params,
141        )?);
142        self.ctes
143            .cache_subquery(subquery, ScalarSubqueryCacheEntry::Scalar(value.clone()));
144        Ok(value)
145    }
146
147    fn subquery_exists(
148        &self,
149        subquery: usize,
150        plan: &QueryPlan,
151        outer_row: PhysicalOuterRow<'_>,
152        params: &[SQLParam],
153    ) -> Result<bool, SQLError> {
154        let cached = self.ctes.cached_subquery(subquery);
155        if let Some(entry) = cached {
156            return match entry {
157                ScalarSubqueryCacheEntry::Correlated => {
158                    self.execute_correlated_exists(plan, outer_row, params)
159                }
160                ScalarSubqueryCacheEntry::CorrelatedExists(lookup) => {
161                    self.correlated_exists_matches(&lookup, outer_row, params)
162                }
163                ScalarSubqueryCacheEntry::Exists(exists) => Ok(exists),
164                ScalarSubqueryCacheEntry::Materialized(result) => Ok(result.rows.rows() != 0),
165                ScalarSubqueryCacheEntry::Scalar(_)
166                | ScalarSubqueryCacheEntry::Row(_)
167                | ScalarSubqueryCacheEntry::Membership(_)
168                | ScalarSubqueryCacheEntry::ComparedMembership(_) => Err(SQLError::Internal(
169                    "scalar subquery slot changed result consumer during execution".into(),
170                )),
171            };
172        }
173        if analysis::query_depends_on_outer_row(&self.services, self.ctes, plan)? {
174            if outer_row.is_some()
175                && !query_contains_volatile_function(self.services.volatility, plan)?
176            {
177                if let Some(lookup) = self.build_correlated_exists(plan, params)? {
178                    let exists = self.correlated_exists_matches(&lookup, outer_row, params)?;
179                    self.ctes.cache_subquery(
180                        subquery,
181                        ScalarSubqueryCacheEntry::CorrelatedExists(lookup),
182                    );
183                    return Ok(exists);
184                }
185            }
186            self.ctes
187                .cache_subquery(subquery, ScalarSubqueryCacheEntry::Correlated);
188            return self.execute_correlated_exists(plan, outer_row, params);
189        }
190        let exists = self.execute_exists_subquery(plan, PhysicalOuterRow::Absent, params)?;
191        self.ctes
192            .cache_subquery(subquery, ScalarSubqueryCacheEntry::Exists(exists));
193        Ok(exists)
194    }
195
196    fn subquery_contains(
197        &self,
198        subquery: usize,
199        plan: &QueryPlan,
200        needle: &Value,
201        outer_row: PhysicalOuterRow<'_>,
202        params: &[SQLParam],
203    ) -> Result<Option<bool>, SQLError> {
204        // The legacy value-key callback retains its existing selected-key contract.
205        self.subquery_contains_selected(
206            subquery,
207            plan,
208            crate::scalar::SubqueryNeedle {
209                value: needle,
210                engine: Some(self.function_hook),
211                control: uqa_core::memory::ProductionControl::uncontrolled(),
212                can_hash: &mut |_| Ok(true),
213            },
214            outer_row,
215            params,
216        )
217    }
218
219    fn subquery_contains_selected(
220        &self,
221        subquery: usize,
222        plan: &QueryPlan,
223        needle: crate::scalar::SubqueryNeedle<'_>,
224        outer_row: PhysicalOuterRow<'_>,
225        params: &[SQLParam],
226    ) -> Result<Option<bool>, SQLError> {
227        needle.control.check()?;
228        let catalog = uqa_sql::expr::EngineValueCatalog(self.function_hook);
229        if let Some(entry) = self.ctes.cached_subquery(subquery) {
230            return match entry {
231                ScalarSubqueryCacheEntry::Correlated => self
232                    .execute_correlated_subquery(plan, outer_row, params)?
233                    .contains_with_engine_and_control(
234                        needle.value,
235                        Some(self.function_hook),
236                        &needle.control,
237                    ),
238                ScalarSubqueryCacheEntry::Membership(membership) => {
239                    membership.contains(needle.value, Some(&catalog))
240                }
241                ScalarSubqueryCacheEntry::ComparedMembership(result) => {
242                    result.result()?.contains_with_engine_and_control(
243                        needle.value,
244                        Some(self.function_hook),
245                        &needle.control,
246                    )
247                }
248                ScalarSubqueryCacheEntry::Materialized(result) => {
249                    self.select_membership(subquery, result, needle)
250                }
251                ScalarSubqueryCacheEntry::Scalar(_)
252                | ScalarSubqueryCacheEntry::Row(_)
253                | ScalarSubqueryCacheEntry::Exists(_)
254                | ScalarSubqueryCacheEntry::CorrelatedExists(_) => Err(SQLError::Internal(
255                    "scalar subquery slot changed result consumer during execution".into(),
256                )),
257            };
258        }
259        if analysis::query_depends_on_outer_row(&self.services, self.ctes, plan)? {
260            self.ctes
261                .cache_subquery(subquery, ScalarSubqueryCacheEntry::Correlated);
262            return self
263                .execute_correlated_subquery(plan, outer_row, params)?
264                .contains_with_engine_and_control(
265                    needle.value,
266                    Some(self.function_hook),
267                    &needle.control,
268                );
269        }
270        let result = self.execute_uncorrelated_subquery(plan, params)?;
271        self.select_membership(subquery, result, needle)
272    }
273}
274
275impl<S: Clone + Send + Sync + 'static> SubqueryContext<'_, S> {
276    fn select_membership(
277        &self,
278        subquery: usize,
279        result: super::scope::subqueries::CachedScalarSubquery,
280        needle: crate::scalar::SubqueryNeedle<'_>,
281    ) -> Result<Option<bool>, SQLError> {
282        let schema = result.rows.row_schema();
283        let output_type = result.columns.first().and_then(|column| {
284            schema
285                .position(column)
286                .and_then(|position| schema.column_type(position))
287        });
288        if !(needle.can_hash)(output_type)? {
289            let found = result.result()?.contains_with_engine_and_control(
290                needle.value,
291                Some(self.function_hook),
292                &needle.control,
293            )?;
294            self.ctes.cache_subquery(
295                subquery,
296                ScalarSubqueryCacheEntry::ComparedMembership(result),
297            );
298            return Ok(found);
299        }
300        let catalog = uqa_sql::expr::EngineValueCatalog(self.function_hook);
301        let membership =
302            Arc::new(result.membership(self.memory.work_mem_bytes()?, Some(&catalog))?);
303        let found = membership.contains(needle.value, Some(&catalog))?;
304        self.ctes
305            .cache_subquery(subquery, ScalarSubqueryCacheEntry::Membership(membership));
306        Ok(found)
307    }
308}