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 => self
158                    .execute_correlated_subquery(plan, outer_row, params)?
159                    .into_exists(),
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
189                .execute_correlated_subquery(plan, outer_row, params)?
190                .into_exists();
191        }
192        let exists = self
193            .execute_uncorrelated_subquery(plan, params)?
194            .rows
195            .rows()
196            != 0;
197        self.ctes
198            .cache_subquery(subquery, ScalarSubqueryCacheEntry::Exists(exists));
199        Ok(exists)
200    }
201
202    fn subquery_contains(
203        &self,
204        subquery: usize,
205        plan: &QueryPlan,
206        needle: &Value,
207        outer_row: PhysicalOuterRow<'_>,
208        params: &[SQLParam],
209    ) -> Result<Option<bool>, SQLError> {
210        // The legacy value-key callback retains its existing selected-key contract.
211        self.subquery_contains_selected(
212            subquery,
213            plan,
214            crate::scalar::SubqueryNeedle {
215                value: needle,
216                engine: Some(self.function_hook),
217                control: uqa_core::memory::ProductionControl::uncontrolled(),
218                can_hash: &mut |_| Ok(true),
219            },
220            outer_row,
221            params,
222        )
223    }
224
225    fn subquery_contains_selected(
226        &self,
227        subquery: usize,
228        plan: &QueryPlan,
229        needle: crate::scalar::SubqueryNeedle<'_>,
230        outer_row: PhysicalOuterRow<'_>,
231        params: &[SQLParam],
232    ) -> Result<Option<bool>, SQLError> {
233        needle.control.check()?;
234        let catalog = uqa_sql::expr::EngineValueCatalog(self.function_hook);
235        if let Some(entry) = self.ctes.cached_subquery(subquery) {
236            return match entry {
237                ScalarSubqueryCacheEntry::Correlated => self
238                    .execute_correlated_subquery(plan, outer_row, params)?
239                    .contains_with_engine_and_control(
240                        needle.value,
241                        Some(self.function_hook),
242                        &needle.control,
243                    ),
244                ScalarSubqueryCacheEntry::Membership(membership) => {
245                    membership.contains(needle.value, Some(&catalog))
246                }
247                ScalarSubqueryCacheEntry::ComparedMembership(result) => {
248                    result.result()?.contains_with_engine_and_control(
249                        needle.value,
250                        Some(self.function_hook),
251                        &needle.control,
252                    )
253                }
254                ScalarSubqueryCacheEntry::Materialized(result) => {
255                    self.select_membership(subquery, result, needle)
256                }
257                ScalarSubqueryCacheEntry::Scalar(_)
258                | ScalarSubqueryCacheEntry::Row(_)
259                | ScalarSubqueryCacheEntry::Exists(_)
260                | ScalarSubqueryCacheEntry::CorrelatedExists(_) => Err(SQLError::Internal(
261                    "scalar subquery slot changed result consumer during execution".into(),
262                )),
263            };
264        }
265        if analysis::query_depends_on_outer_row(&self.services, self.ctes, plan)? {
266            self.ctes
267                .cache_subquery(subquery, ScalarSubqueryCacheEntry::Correlated);
268            return self
269                .execute_correlated_subquery(plan, outer_row, params)?
270                .contains_with_engine_and_control(
271                    needle.value,
272                    Some(self.function_hook),
273                    &needle.control,
274                );
275        }
276        let result = self.execute_uncorrelated_subquery(plan, params)?;
277        self.select_membership(subquery, result, needle)
278    }
279}
280
281impl<S: Clone + Send + Sync + 'static> SubqueryContext<'_, S> {
282    fn select_membership(
283        &self,
284        subquery: usize,
285        result: super::scope::subqueries::CachedScalarSubquery,
286        needle: crate::scalar::SubqueryNeedle<'_>,
287    ) -> Result<Option<bool>, SQLError> {
288        let schema = result.rows.row_schema();
289        let output_type = result.columns.first().and_then(|column| {
290            schema
291                .position(column)
292                .and_then(|position| schema.column_type(position))
293        });
294        if !(needle.can_hash)(output_type)? {
295            let found = result.result()?.contains_with_engine_and_control(
296                needle.value,
297                Some(self.function_hook),
298                &needle.control,
299            )?;
300            self.ctes.cache_subquery(
301                subquery,
302                ScalarSubqueryCacheEntry::ComparedMembership(result),
303            );
304            return Ok(found);
305        }
306        let catalog = uqa_sql::expr::EngineValueCatalog(self.function_hook);
307        let membership =
308            Arc::new(result.membership(self.memory.work_mem_bytes()?, Some(&catalog))?);
309        let found = membership.contains(needle.value, Some(&catalog))?;
310        self.ctes
311            .cache_subquery(subquery, ScalarSubqueryCacheEntry::Membership(membership));
312        Ok(found)
313    }
314}