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