Skip to main content

uqa_execution/query/scope/
subqueries.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Cached scalar results and SQL membership semantics for one query arena.
8
9use crate::physical::physical_exec_error;
10use crate::{RowSchemaExecution, ScalarExpr};
11use std::sync::Arc;
12use uqa_core::Value;
13use uqa_sql::{expr::RowLookup, SQLError};
14
15#[derive(Clone)]
16pub enum ScalarSubqueryCacheEntry {
17    Correlated,
18    CorrelatedExists(Arc<CachedCorrelatedExists>),
19    Materialized(CachedScalarSubquery),
20    Membership(Arc<CachedSubqueryMembership>),
21    ComparedMembership(CachedScalarSubquery),
22    Scalar(Value),
23    Row(Option<crate::OwnedPhysicalRow>),
24    Exists(bool),
25}
26
27pub struct CachedCorrelatedExists {
28    pub outer_keys: CorrelatedExistsOuterKeys,
29    pub keys: crate::CanonicalRowHashSet,
30}
31
32pub enum CorrelatedExistsOuterKeys {
33    Direct(Vec<DirectColumnKey>),
34    Evaluated(Vec<ScalarExpr>),
35}
36
37impl CorrelatedExistsOuterKeys {
38    pub fn compile(expressions: Vec<ScalarExpr>) -> Self {
39        let direct = expressions
40            .iter()
41            .map(DirectColumnKey::compile)
42            .collect::<Option<Vec<_>>>();
43        direct.map_or(Self::Evaluated(expressions), Self::Direct)
44    }
45}
46
47/// A scalar key expression that can be resolved as a borrowed physical value instead of cloning it through the general expression evaluator.
48pub enum DirectColumnKey {
49    Column(String),
50    Qualified { qualifier: String, column: String },
51}
52
53impl DirectColumnKey {
54    pub fn compile(expression: &ScalarExpr) -> Option<Self> {
55        match expression {
56            ScalarExpr::Column(column) => Some(Self::Column(column.to_string())),
57            ScalarExpr::QualifiedColumn { qualifier, column } => Some(Self::Qualified {
58                qualifier: qualifier.clone(),
59                column: column.to_string(),
60            }),
61            _ => None,
62        }
63    }
64
65    pub fn value<'a>(&self, row: &'a dyn RowLookup) -> Option<&'a Value> {
66        match self {
67            Self::Column(column) => row.column(column),
68            Self::Qualified { qualifier, column } => row.qualified_column(qualifier, column),
69        }
70    }
71}
72
73pub struct CachedSubqueryMembership {
74    values: parking_lot::Mutex<crate::ExactRowSet>,
75    has_column: bool,
76    saw_row: bool,
77    saw_null: bool,
78}
79
80impl CachedSubqueryMembership {
81    pub fn contains(
82        &self,
83        needle: &Value,
84        catalog: Option<&dyn uqa_sql::expr::SQLValueCatalog>,
85    ) -> Result<Option<bool>, SQLError> {
86        if !self.has_column {
87            return Ok(Some(false));
88        }
89        if !matches!(needle, Value::Null)
90            && self
91                .values
92                .lock()
93                .contains_sql_values(std::slice::from_ref(needle), catalog)
94                .map_err(physical_exec_error)?
95        {
96            return Ok(Some(true));
97        }
98        Ok(if !self.saw_row {
99            Some(false)
100        } else if matches!(needle, Value::Null) || self.saw_null {
101            None
102        } else {
103            Some(false)
104        })
105    }
106}
107
108#[derive(Clone)]
109pub struct CachedScalarSubquery {
110    pub columns: Vec<String>,
111    pub rows: crate::SharedSpill,
112}
113
114impl CachedScalarSubquery {
115    pub fn result(&self) -> Result<crate::SubqueryResult, SQLError> {
116        let rows = self
117            .rows
118            .read_rows()
119            .map_err(physical_exec_error)?
120            .map(|row| row.map_err(physical_exec_error));
121        Ok(crate::SubqueryResult {
122            columns: self.columns.clone(),
123            rows: Box::new(rows),
124        })
125    }
126
127    pub fn membership(
128        &self,
129        work_mem_bytes: usize,
130        catalog: Option<&dyn uqa_sql::expr::SQLValueCatalog>,
131    ) -> Result<CachedSubqueryMembership, SQLError> {
132        let Some(first_column) = self.columns.first() else {
133            return Ok(CachedSubqueryMembership {
134                values: parking_lot::Mutex::new(crate::ExactRowSet::new(work_mem_bytes)),
135                has_column: false,
136                saw_row: false,
137                saw_null: false,
138            });
139        };
140        let schema = self.rows.row_schema();
141        let position = schema.position(first_column).ok_or_else(|| {
142            SQLError::Internal(format!(
143                "cached subquery output column `{first_column}` is missing"
144            ))
145        })?;
146        let mut values = crate::ExactRowSet::with_sql_types(
147            work_mem_bytes,
148            vec![schema.column_type(position).cloned()],
149        );
150        let mut saw_row = false;
151        let mut saw_null = false;
152        for batch in self.rows.reader().map_err(physical_exec_error)? {
153            let batch = batch.map_err(physical_exec_error)?;
154            for row in &batch.rows {
155                saw_row = true;
156                match batch.schema.view(row).value_at(position) {
157                    Some(Value::Null) | None => saw_null = true,
158                    Some(value) => {
159                        values
160                            .insert_sql_values(std::slice::from_ref(value), catalog)
161                            .map_err(physical_exec_error)?;
162                    }
163                }
164            }
165        }
166        Ok(CachedSubqueryMembership {
167            values: parking_lot::Mutex::new(values),
168            has_column: true,
169            saw_row,
170            saw_null,
171        })
172    }
173}