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(&self, needle: &Value) -> Result<Option<bool>, SQLError> {
81        if !self.has_column {
82            return Ok(Some(false));
83        }
84        if !matches!(needle, Value::Null)
85            && self
86                .values
87                .lock()
88                .contains_values(std::slice::from_ref(needle))
89                .map_err(physical_exec_error)?
90        {
91            return Ok(Some(true));
92        }
93        Ok(if !self.saw_row {
94            Some(false)
95        } else if matches!(needle, Value::Null) || self.saw_null {
96            None
97        } else {
98            Some(false)
99        })
100    }
101}
102
103#[derive(Clone)]
104pub struct CachedScalarSubquery {
105    pub columns: Vec<String>,
106    pub rows: crate::SharedSpill,
107}
108
109impl CachedScalarSubquery {
110    pub fn result(&self) -> Result<crate::SubqueryResult, SQLError> {
111        let rows = self
112            .rows
113            .read_rows()
114            .map_err(physical_exec_error)?
115            .map(|row| row.map_err(physical_exec_error));
116        Ok(crate::SubqueryResult {
117            columns: self.columns.clone(),
118            rows: Box::new(rows),
119        })
120    }
121
122    pub fn membership(&self, work_mem_bytes: usize) -> Result<CachedSubqueryMembership, SQLError> {
123        let Some(first_column) = self.columns.first() else {
124            return Ok(CachedSubqueryMembership {
125                values: parking_lot::Mutex::new(crate::ExactRowSet::new(work_mem_bytes)),
126                has_column: false,
127                saw_row: false,
128                saw_null: false,
129            });
130        };
131        let mut values = crate::ExactRowSet::new(work_mem_bytes);
132        let mut saw_row = false;
133        let mut saw_null = false;
134        for batch in self.rows.reader().map_err(physical_exec_error)? {
135            let batch = batch.map_err(physical_exec_error)?;
136            let position = batch.schema.position(first_column).ok_or_else(|| {
137                SQLError::Internal(format!(
138                    "cached subquery output column `{first_column}` is missing"
139                ))
140            })?;
141            for row in &batch.rows {
142                saw_row = true;
143                match batch.schema.view(row).value_at(position) {
144                    Some(Value::Null) | None => saw_null = true,
145                    Some(value) => {
146                        values
147                            .insert_values(std::slice::from_ref(value))
148                            .map_err(physical_exec_error)?;
149                    }
150                }
151            }
152        }
153        Ok(CachedSubqueryMembership {
154            values: parking_lot::Mutex::new(values),
155            has_column: true,
156            saw_row,
157            saw_null,
158        })
159    }
160}