Skip to main content

uqa_execution/query/
generated.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Physical/logical row conversion for `PostgreSQL` generated columns.
8
9use uqa_core::{
10    memory::{MemoryBudget, MemoryReservation, Produced, ProductionControl},
11    CancellationToken,
12};
13use uqa_sql::ast::{ColumnDef, GeneratedColumnKind};
14use uqa_sql::{
15    expr::RowLookup,
16    schema::{ColumnTypeSchema, ScalarTypeSchema},
17    SQLError,
18};
19use uqa_storage::document_store::Document;
20
21pub fn materialize_virtual_generated_columns(
22    columns: &[ColumnDef],
23    document: &mut Document,
24) -> Result<(), SQLError> {
25    materialize_matching_virtual_generated_columns(columns, document, |_| true)
26}
27
28pub fn materialize_selected_virtual_generated_columns(
29    columns: &[ColumnDef],
30    document: &mut Document,
31    selected: &std::collections::BTreeSet<String>,
32) -> Result<(), SQLError> {
33    materialize_matching_virtual_generated_columns(columns, document, |name| {
34        selected.contains(name)
35    })
36}
37
38pub fn materialize_projected_virtual_generated_columns(
39    columns: &[ColumnDef],
40    document: &mut Document,
41    projection: &[String],
42) -> Result<(), SQLError> {
43    materialize_matching_virtual_generated_columns(columns, document, |name| {
44        projection.iter().any(|projected| projected == name)
45    })
46}
47
48pub fn materialize_missing_generated_columns(
49    columns: &[ColumnDef],
50    document: &mut Document,
51) -> Result<(), SQLError> {
52    materialize_matching_missing_generated_columns(columns, document, None)
53}
54
55/// The original allowance and cancellation scopes follow generated expression preparation and value production; schema and row lookups borrow their existing owners.
56pub(crate) struct GeneratedControl<'a> {
57    pub(crate) budget: &'a MemoryBudget,
58    pub(crate) original: &'a CancellationToken,
59    pub(crate) invoking: &'a CancellationToken,
60}
61
62impl GeneratedControl<'_> {
63    fn production(&self) -> ProductionControl<'_> {
64        ProductionControl::new(self.budget, self.original, self.invoking)
65    }
66}
67
68pub(crate) fn materialize_missing_generated_columns_with_control(
69    columns: &[ColumnDef],
70    document: &mut Document,
71    memory: &mut MemoryReservation,
72    control: &GeneratedControl<'_>,
73) -> Result<(), SQLError> {
74    assert!(control.budget.shares_allowance(memory.budget()));
75    materialize_matching_missing_generated_columns(columns, document, Some((control, memory)))
76}
77
78fn materialize_matching_missing_generated_columns(
79    columns: &[ColumnDef],
80    document: &mut Document,
81    mut retained: Option<(&GeneratedControl<'_>, &mut MemoryReservation)>,
82) -> Result<(), SQLError> {
83    let production = retained
84        .as_ref()
85        .map_or_else(ProductionControl::uncontrolled, |(control, _)| {
86            control.production()
87        });
88    production.check()?;
89    let schema = ColumnTypeSchema::new(columns);
90    for column in columns {
91        production.check()?;
92        let Some(generated) = column.generated.as_ref() else {
93            continue;
94        };
95        if document.contains_key(&column.name) {
96            continue;
97        }
98        let value = if let Some((control, _)) = &retained {
99            let expression = prepare_generated_column_with_control(&schema, generated, control)?;
100            let source =
101                uqa_sql::scalar_type_with_control(&expression.scalar, &schema, &[], &production)?;
102            let value = evaluate_generated_expression_with_control(
103                &expression.scalar,
104                document,
105                &production,
106            )?;
107            uqa_sql::assignment::conversion::convert_value_to_column_type_from_with_control(
108                value,
109                &column.ty,
110                source.as_deref(),
111                &production,
112            )?
113        } else {
114            let (value, source) = evaluate_generated_column(&schema, generated, document)?;
115            production.finish(
116                uqa_sql::assignment::conversion::convert_value_to_column_type_from(
117                    value,
118                    &column.ty,
119                    source.as_ref(),
120                )?,
121                None,
122            )?
123        };
124        let name = production.copy_text(&column.name)?;
125        let entry_memory = production.reserve(size_of::<(String, uqa_core::Value)>())?;
126        let (value, value_memory) = value.into_parts();
127        let (name, name_memory) = name.into_parts();
128        let entry = production.finish(
129            (name, value),
130            production.combine(entry_memory, production.combine(value_memory, name_memory)),
131        )?;
132        let ((name, value), entry_memory) = entry.into_parts();
133        match (&mut retained, entry_memory) {
134            (Some((_, memory)), Some(entry_memory)) => memory.absorb(entry_memory),
135            (None, None) => (),
136            _ => unreachable!("generated field ownership matches its production control"),
137        }
138        document.insert(name, value);
139    }
140    production.check()?;
141    Ok(())
142}
143
144fn materialize_matching_virtual_generated_columns(
145    columns: &[ColumnDef],
146    document: &mut Document,
147    mut selected: impl FnMut(&str) -> bool,
148) -> Result<(), SQLError> {
149    let schema = ColumnTypeSchema::new(columns);
150    for column in columns {
151        let Some(generated) = column.generated.as_ref() else {
152            continue;
153        };
154        if generated.kind != GeneratedColumnKind::Virtual {
155            continue;
156        }
157        if !selected(&column.name) {
158            continue;
159        }
160        let (value, source) = evaluate_generated_column(&schema, generated, document)?;
161        document.insert(
162            column.name.clone(),
163            uqa_sql::assignment::conversion::convert_value_to_column_type_from(
164                value,
165                &column.ty,
166                source.as_ref(),
167            )?,
168        );
169    }
170    Ok(())
171}
172
173fn evaluate_generated_column(
174    schema: &dyn ScalarTypeSchema,
175    generated: &uqa_sql::ast::GeneratedColumn,
176    document: &Document,
177) -> Result<(uqa_core::Value, Option<uqa_sql::ColumnType>), SQLError> {
178    let expression = prepare_generated_column(schema, generated)?;
179    let source = uqa_sql::scalar_type(&expression, schema, &[])?;
180    evaluate_generated_expression(&expression, document).map(|value| (value, source))
181}
182
183pub(crate) fn prepare_generated_column(
184    schema: &dyn ScalarTypeSchema,
185    generated: &uqa_sql::ast::GeneratedColumn,
186) -> Result<crate::ScalarExpr, SQLError> {
187    let mut expression = uqa_sql::plan::ExpressionPlan::lower((*generated.expression).clone());
188    if !expression.subqueries.is_empty() {
189        return Err(SQLError::Internal(
190            "validated generated expression contains a subquery".into(),
191        ));
192    }
193    expression.scalar = crate::bind_type_introspection(expression.scalar, schema, &[]);
194    Ok(expression.scalar)
195}
196
197/// Keep every lowered and bound expression allocation through evaluation; evaluated values have their own result owner.
198pub(crate) struct GeneratedExpression {
199    pub(crate) scalar: crate::ScalarExpr,
200    _preparation_memory: MemoryReservation,
201}
202
203pub(crate) fn prepare_generated_column_with_control(
204    schema: &dyn ScalarTypeSchema,
205    generated: &uqa_sql::ast::GeneratedColumn,
206    control: &GeneratedControl<'_>,
207) -> Result<GeneratedExpression, SQLError> {
208    let lowered = uqa_sql::plan::ExpressionPlan::lower_column_budgeted(
209        &generated.expression,
210        control.budget,
211        control.original,
212        control.invoking,
213    )?;
214    let prepared = uqa_sql::bind_type_introspection_with_control(
215        lowered.into(),
216        schema,
217        &[],
218        &ProductionControl::new(control.budget, control.original, control.invoking),
219    )?
220    .into_budgeted()
221    .expect("controlled generated preparation retains its allowance");
222    let (scalar, memory) = prepared.into_parts();
223    Ok(GeneratedExpression {
224        scalar,
225        _preparation_memory: memory,
226    })
227}
228
229pub(crate) fn evaluate_generated_expression(
230    expression: &crate::ScalarExpr,
231    row: &dyn RowLookup,
232) -> Result<uqa_core::Value, SQLError> {
233    crate::eval_scalar(
234        expression,
235        &crate::ScalarEvalContext::from_row_lookup(row, &[]),
236    )
237}
238
239pub(crate) fn evaluate_generated_expression_with_control(
240    expression: &crate::ScalarExpr,
241    row: &dyn RowLookup,
242    control: &ProductionControl<'_>,
243) -> Result<Produced<uqa_core::Value>, SQLError> {
244    crate::eval_generated_scalar_with_control(expression, row, control)
245}
246
247pub fn strip_virtual_generated_columns(columns: &[ColumnDef], document: &mut Document) {
248    for column in columns {
249        if column
250            .generated
251            .as_ref()
252            .is_some_and(|generated| generated.kind == GeneratedColumnKind::Virtual)
253        {
254            document.remove(&column.name);
255        }
256    }
257}
258
259pub fn projection_contains_virtual_generated_column(
260    columns: &[ColumnDef],
261    projection: &[String],
262) -> bool {
263    columns.iter().any(|column| {
264        column
265            .generated
266            .as_ref()
267            .is_some_and(|generated| generated.kind == GeneratedColumnKind::Virtual)
268            && projection.iter().any(|name| name == &column.name)
269    })
270}
271
272#[cfg(test)]
273mod tests;