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::CorrelatedExists(_) => {
50                    return Err(SQLError::Internal(
51                        "scalar subquery slot changed result consumer during execution".into(),
52                    ));
53                }
54            }
55        }
56
57        if analysis::query_depends_on_outer_row(&self.services, plan)? {
58            self.ctes
59                .cache_subquery(subquery, ScalarSubqueryCacheEntry::Correlated);
60            return self.execute_correlated_subquery(plan, outer_row, params);
61        }
62
63        let result = self.execute_uncorrelated_subquery(plan, params)?;
64        self.ctes.cache_subquery(
65            subquery,
66            ScalarSubqueryCacheEntry::Materialized(result.clone()),
67        );
68        result.result()
69    }
70
71    fn row_subquery_value(
72        &self,
73        subquery: usize,
74        plan: &QueryPlan,
75        outer_row: PhysicalOuterRow<'_>,
76        params: &[SQLParam],
77    ) -> Result<Option<crate::OwnedPhysicalRow>, SQLError> {
78        if let Some(entry) = self.ctes.cached_subquery(subquery) {
79            return match entry {
80                ScalarSubqueryCacheEntry::Correlated => {
81                    self.execute_correlated_single_row(plan, outer_row, params)
82                }
83                ScalarSubqueryCacheEntry::Row(row) => Ok(row),
84                ScalarSubqueryCacheEntry::Materialized(result) => {
85                    result.result()?.into_single_row()
86                }
87                _ => Err(SQLError::Internal(
88                    "scalar subquery slot changed result consumer during execution".into(),
89                )),
90            };
91        }
92        if analysis::query_depends_on_outer_row(&self.services, plan)? {
93            self.ctes
94                .cache_subquery(subquery, ScalarSubqueryCacheEntry::Correlated);
95            return self.execute_correlated_single_row(plan, outer_row, params);
96        }
97        let row = self.execute_single_row_subquery(plan, PhysicalOuterRow::Absent, params)?;
98        self.ctes
99            .cache_subquery(subquery, ScalarSubqueryCacheEntry::Row(row.clone()));
100        Ok(row)
101    }
102
103    fn scalar_subquery_value(
104        &self,
105        subquery: usize,
106        plan: &QueryPlan,
107        outer_row: PhysicalOuterRow<'_>,
108        params: &[SQLParam],
109    ) -> Result<Value, SQLError> {
110        let cached = self.ctes.cached_subquery(subquery);
111        if let Some(entry) = cached {
112            return match entry {
113                ScalarSubqueryCacheEntry::Correlated => self
114                    .execute_correlated_single_row(plan, outer_row, params)
115                    .map(single_row::scalar_value),
116                ScalarSubqueryCacheEntry::Scalar(value) => Ok(value),
117                ScalarSubqueryCacheEntry::Materialized(result) => {
118                    result.result()?.into_scalar_value()
119                }
120                ScalarSubqueryCacheEntry::Row(_)
121                | ScalarSubqueryCacheEntry::Exists(_)
122                | ScalarSubqueryCacheEntry::Membership(_)
123                | ScalarSubqueryCacheEntry::CorrelatedExists(_) => Err(SQLError::Internal(
124                    "scalar subquery slot changed result consumer during execution".into(),
125                )),
126            };
127        }
128        if analysis::query_depends_on_outer_row(&self.services, plan)? {
129            self.ctes
130                .cache_subquery(subquery, ScalarSubqueryCacheEntry::Correlated);
131            return self
132                .execute_correlated_single_row(plan, outer_row, params)
133                .map(single_row::scalar_value);
134        }
135        let value = single_row::scalar_value(self.execute_single_row_subquery(
136            plan,
137            PhysicalOuterRow::Absent,
138            params,
139        )?);
140        self.ctes
141            .cache_subquery(subquery, ScalarSubqueryCacheEntry::Scalar(value.clone()));
142        Ok(value)
143    }
144
145    fn subquery_exists(
146        &self,
147        subquery: usize,
148        plan: &QueryPlan,
149        outer_row: PhysicalOuterRow<'_>,
150        params: &[SQLParam],
151    ) -> Result<bool, SQLError> {
152        let cached = self.ctes.cached_subquery(subquery);
153        if let Some(entry) = cached {
154            return match entry {
155                ScalarSubqueryCacheEntry::Correlated => self
156                    .execute_correlated_subquery(plan, outer_row, params)?
157                    .into_exists(),
158                ScalarSubqueryCacheEntry::CorrelatedExists(lookup) => {
159                    self.correlated_exists_matches(&lookup, outer_row, params)
160                }
161                ScalarSubqueryCacheEntry::Exists(exists) => Ok(exists),
162                ScalarSubqueryCacheEntry::Materialized(result) => Ok(result.rows.rows() != 0),
163                ScalarSubqueryCacheEntry::Scalar(_)
164                | ScalarSubqueryCacheEntry::Row(_)
165                | ScalarSubqueryCacheEntry::Membership(_) => Err(SQLError::Internal(
166                    "scalar subquery slot changed result consumer during execution".into(),
167                )),
168            };
169        }
170        if analysis::query_depends_on_outer_row(&self.services, plan)? {
171            if outer_row.is_some()
172                && !query_contains_volatile_function(self.services.volatility, plan)?
173            {
174                if let Some(lookup) = self.build_correlated_exists(plan, params)? {
175                    let exists = self.correlated_exists_matches(&lookup, outer_row, params)?;
176                    self.ctes.cache_subquery(
177                        subquery,
178                        ScalarSubqueryCacheEntry::CorrelatedExists(lookup),
179                    );
180                    return Ok(exists);
181                }
182            }
183            self.ctes
184                .cache_subquery(subquery, ScalarSubqueryCacheEntry::Correlated);
185            return self
186                .execute_correlated_subquery(plan, outer_row, params)?
187                .into_exists();
188        }
189        let exists = self
190            .execute_uncorrelated_subquery(plan, params)?
191            .rows
192            .rows()
193            != 0;
194        self.ctes
195            .cache_subquery(subquery, ScalarSubqueryCacheEntry::Exists(exists));
196        Ok(exists)
197    }
198
199    fn subquery_contains(
200        &self,
201        subquery: usize,
202        plan: &QueryPlan,
203        needle: &Value,
204        outer_row: PhysicalOuterRow<'_>,
205        params: &[SQLParam],
206    ) -> Result<Option<bool>, SQLError> {
207        let cached = self.ctes.cached_subquery(subquery);
208        if let Some(entry) = cached {
209            return match entry {
210                ScalarSubqueryCacheEntry::Correlated => self
211                    .execute_correlated_subquery(plan, outer_row, params)?
212                    .contains(needle),
213                ScalarSubqueryCacheEntry::Membership(membership) => membership.contains(needle),
214                ScalarSubqueryCacheEntry::Materialized(result) => {
215                    let membership = Arc::new(result.membership(self.memory.work_mem_bytes()?)?);
216                    let found = membership.contains(needle)?;
217                    self.ctes
218                        .cache_subquery(subquery, ScalarSubqueryCacheEntry::Membership(membership));
219                    Ok(found)
220                }
221                ScalarSubqueryCacheEntry::Scalar(_)
222                | ScalarSubqueryCacheEntry::Row(_)
223                | ScalarSubqueryCacheEntry::Exists(_)
224                | ScalarSubqueryCacheEntry::CorrelatedExists(_) => Err(SQLError::Internal(
225                    "scalar subquery slot changed result consumer during execution".into(),
226                )),
227            };
228        }
229        if analysis::query_depends_on_outer_row(&self.services, plan)? {
230            self.ctes
231                .cache_subquery(subquery, ScalarSubqueryCacheEntry::Correlated);
232            return self
233                .execute_correlated_subquery(plan, outer_row, params)?
234                .contains(needle);
235        }
236
237        let result = self.execute_uncorrelated_subquery(plan, params)?;
238        let membership = Arc::new(result.membership(self.memory.work_mem_bytes()?)?);
239        let found = membership.contains(needle)?;
240        self.ctes
241            .cache_subquery(subquery, ScalarSubqueryCacheEntry::Membership(membership));
242        Ok(found)
243    }
244}