Skip to main content

uqa_execution/mutation/
assignment.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Evaluate mutation defaults, typed assignments and view check options.
8mod grouped;
9mod subscripts;
10pub use grouped::{
11    eval_mutation_assignment_input, eval_typed_assignment_input, final_column_write,
12    AssignmentInput, AssignmentSource, ViewRuleAssignment,
13};
14
15use super::{
16    errors::dml_storage_error,
17    expressions::eval_mutation_expr,
18    rows::context::{MutationExpressionContext, MutationRowContext},
19};
20use crate::{
21    query::{locking::context::RowLockScopeSource, CteScope},
22    OwnedPhysicalRow,
23};
24use uqa_core::{DocId, Value};
25use uqa_sql::{
26    assignment::{columns::AssignmentColumnCatalog, AssignmentContext},
27    plan::{UpdatePlan, ViewCheckPlan},
28    RowSchema, SQLError, SQLParam, ScalarExpr,
29};
30use uqa_storage::document_store::Document;
31#[derive(Clone)]
32pub struct MutationAssignmentContext<'a, S: Clone + 'static> {
33    pub columns: &'a dyn AssignmentColumnCatalog,
34    pub assignment: &'a dyn AssignmentContext,
35    pub rows: MutationRowContext<'a>,
36    pub expressions: MutationExpressionContext<'a, S>,
37    pub scopes: &'a dyn RowLockScopeSource<S>,
38}
39impl<S: Clone + 'static> Copy for MutationAssignmentContext<'_, S> {}
40#[derive(Clone, Copy)]
41pub struct MutationAssignmentTarget<'a> {
42    pub table: &'a str,
43    pub target: &'a uqa_sql::ast::AssignmentTarget<ScalarExpr>,
44    pub current: Option<&'a Value>,
45    pub final_column_write: bool,
46    pub action: &'a str,
47    /// Whether the assignment builds a row an `INSERT` adds. `DEFAULT` leaves such a row's identity column out, for the identity generator to draw its value under the statement's `OVERRIDING` clause; it draws the next sequence value for a row an update assigns.
48    pub new_row: bool,
49}
50
51pub fn eval_mutation_assignment<S: Clone + 'static>(
52    services: MutationAssignmentContext<'_, S>,
53    ctes: &CteScope<S>,
54    target: MutationAssignmentTarget<'_>,
55    expression: &ScalarExpr,
56    row: Option<&OwnedPhysicalRow>,
57    params: &[SQLParam],
58) -> Result<Option<Value>, SQLError> {
59    let MutationAssignmentTarget {
60        table,
61        target: assignment_target,
62        action,
63        new_row,
64        ..
65    } = target;
66    let column = &assignment_target.column;
67    let generated =
68        uqa_sql::assignment::columns::generated_column_kind(services.columns, table, column)?;
69    if matches!(expression, ScalarExpr::Default) {
70        uqa_sql::assignment::targets::validate_assignment_default(assignment_target)?;
71        if generated.is_some() {
72            // UPDATE DEFAULT does not force a stored expression to run. Keep its old value until dependency selection or a BEFORE trigger requires recomputation.
73            if !new_row && generated == Some(uqa_sql::ast::GeneratedColumnKind::Stored) {
74                return Ok(target.current.cloned());
75            }
76            return Ok(None);
77        }
78        if let Some(sequence) =
79            uqa_sql::assignment::columns::identity_column_sequence(services.columns, table, column)?
80        {
81            if new_row {
82                return Ok(None);
83            }
84            return evaluate_column_default(
85                services,
86                table,
87                column,
88                Some(&uqa_sql::schema::sequences::implicit::sequence_next_value(
89                    &sequence,
90                )),
91                params,
92            )
93            .map(Some);
94        }
95        let default = services
96            .columns
97            .try_column_insert_default_expr(table, column)
98            .map_err(|error| dml_storage_error(action, error))?;
99        return evaluate_column_default(services, table, column, default.as_ref(), params)
100            .map(Some);
101    }
102    if generated.is_some() {
103        return Err(if new_row {
104            uqa_sql::semantics::generated_values::generated_column_insert_error(column)
105        } else {
106            uqa_sql::semantics::generated_values::generated_column_update_error(column)
107        });
108    }
109    let empty_schema = RowSchema::default();
110    let schema = row.map_or(&empty_schema, |row| &row.schema);
111    let hook = services.expressions.expressions.bind_scope(ctes)?;
112    let source = uqa_sql::type_resolution::assignment_source_type(
113        expression,
114        schema,
115        params,
116        hook.as_ref(),
117    )?;
118    subscripts::assign_value(
119        services,
120        ctes,
121        target,
122        || eval_mutation_expr(services.expressions, ctes, expression, row, params),
123        source.as_ref(),
124        row,
125        params,
126    )
127    .map(Some)
128}
129
130/// Keep a default's declared source type through assignment: a domain value has
131/// already passed its constraints when its expression returns it.
132fn evaluate_column_default<S: Clone + 'static>(
133    services: MutationAssignmentContext<'_, S>,
134    table: &str,
135    column: &str,
136    expression: Option<&uqa_sql::ast::Expr>,
137    params: &[SQLParam],
138) -> Result<Value, SQLError> {
139    let (value, source) = expression.map_or(Ok((Value::Null, None)), |expression| {
140        crate::query::catalog_expression::eval_lowered_expression_with_type(
141            services.expressions.expressions,
142            services.scopes.current_routine_scope()?,
143            expression,
144            None,
145            params,
146        )
147    })?;
148    uqa_sql::assignment::columns::coerce_to_column_type_from(
149        services.assignment,
150        services.columns,
151        table,
152        column,
153        value,
154        source.as_deref(),
155    )
156}
157
158/// Apply a value from INSERT SELECT using its declared source type and the original bound scope.
159pub fn coerce_mutation_assignment<S: Clone + 'static>(
160    services: MutationAssignmentContext<'_, S>,
161    ctes: &CteScope<S>,
162    target: MutationAssignmentTarget<'_>,
163    value: Value,
164    source: Option<&uqa_sql::ColumnType>,
165    row: Option<&OwnedPhysicalRow>,
166    params: &[SQLParam],
167) -> Result<Value, SQLError> {
168    subscripts::assign_value(services, ctes, target, || Ok(value), source, row, params)
169}
170
171#[derive(Clone, Copy)]
172pub struct TypedAssignmentTarget<'a> {
173    pub target: &'a uqa_sql::ast::AssignmentTarget<ScalarExpr>,
174    pub ty: Option<&'a uqa_sql::ColumnType>,
175    pub current: Option<&'a Value>,
176    pub final_column_write: bool,
177}
178
179pub fn eval_typed_assignment<S: Clone + 'static>(
180    services: MutationAssignmentContext<'_, S>,
181    ctes: &CteScope<S>,
182    target: TypedAssignmentTarget<'_>,
183    expression: &ScalarExpr,
184    row: Option<&OwnedPhysicalRow>,
185    params: &[SQLParam],
186) -> Result<Value, SQLError> {
187    let default = matches!(expression, ScalarExpr::Default);
188    if default {
189        uqa_sql::assignment::targets::validate_assignment_default(target.target)?;
190    }
191    uqa_sql::assignment::targets::validate_assignment_type(target.target, target.ty)?;
192    let schema = RowSchema::default();
193    let hook = services.expressions.expressions.bind_scope(ctes)?;
194    let source = uqa_sql::type_resolution::assignment_source_type(
195        expression,
196        row.map_or(&schema, |row| &row.schema),
197        params,
198        hook.as_ref(),
199    )?;
200    let value = || {
201        if default {
202            Ok(Value::Null)
203        } else {
204            eval_mutation_expr(services.expressions, ctes, expression, row, params)
205        }
206    };
207    match target.ty {
208        Some(ty) => subscripts::assign_typed_value(
209            services,
210            ctes,
211            TypedAssignmentTarget {
212                ty: Some(ty),
213                ..target
214            },
215            value,
216            source.as_ref(),
217            row,
218            params,
219        ),
220        None => value(),
221    }
222}
223
224pub fn coerce_typed_assignment<S: Clone + 'static>(
225    services: MutationAssignmentContext<'_, S>,
226    ctes: &CteScope<S>,
227    target: TypedAssignmentTarget<'_>,
228    value: Value,
229    source: Option<&uqa_sql::ColumnType>,
230    row: Option<&OwnedPhysicalRow>,
231    params: &[SQLParam],
232) -> Result<Value, SQLError> {
233    uqa_sql::assignment::targets::validate_assignment_type(target.target, target.ty)?;
234    match target.ty {
235        Some(ty) => subscripts::assign_typed_value(
236            services,
237            ctes,
238            TypedAssignmentTarget {
239                ty: Some(ty),
240                ..target
241            },
242            || Ok(value),
243            source,
244            row,
245            params,
246        ),
247        None => Ok(value),
248    }
249}
250
251pub fn eval_view_rule_update_assignment<S: Clone + 'static>(
252    services: MutationAssignmentContext<'_, S>,
253    ctes: &CteScope<S>,
254    stmt: &UpdatePlan,
255    input: ViewRuleAssignment<'_>,
256    row: Option<&OwnedPhysicalRow>,
257    params: &[SQLParam],
258) -> Result<Option<Value>, SQLError> {
259    for plan in &stmt.view_rule_update_plans {
260        let Some(column) = plan.assigned_columns.get(input.position) else {
261            continue;
262        };
263        let schema = services.rows.relations.view_schema(&plan.relation)?;
264        let Some(position) =
265            schema
266                .columns()
267                .iter()
268                .enumerate()
269                .find_map(|(position, internal)| {
270                    let public = schema.public_name(position).unwrap_or(internal);
271                    public.eq_ignore_ascii_case(column).then_some(position)
272                })
273        else {
274            return Err(SQLError::UnknownColumn(format!(
275                "{}.{}",
276                plan.relation, column
277            )));
278        };
279        return eval_typed_assignment_input(
280            services,
281            ctes,
282            TypedAssignmentTarget {
283                ty: schema.column_type(position),
284                ..input.target
285            },
286            input.input,
287            row,
288            params,
289        )
290        .map(Some);
291    }
292    eval_typed_assignment_input(services, ctes, input.target, input.input, row, params).map(Some)
293}
294
295pub struct ViewCheckContext<'a, S: Clone + 'static> {
296    pub services: MutationAssignmentContext<'a, S>,
297    /// The catalog and authority that describe a row a check option rejects.
298    pub constraints: super::constraints::ConstraintContext<'a>,
299    /// The statement that writes the row, whose relation and columns the description follows.
300    pub statement: super::constraints::ConstraintStatement<'a>,
301    pub table: &'a str,
302    pub storage_table: &'a str,
303    pub target_qualifier: &'a str,
304    pub doc_id: DocId,
305    pub document: &'a Document,
306    pub checks: &'a [ViewCheckPlan],
307    pub params: &'a [SQLParam],
308    pub scope: &'a CteScope<S>,
309}
310
311pub fn validate_view_checks<S: Clone + 'static>(
312    context: ViewCheckContext<'_, S>,
313) -> Result<(), SQLError> {
314    let ViewCheckContext {
315        services,
316        constraints,
317        statement,
318        table,
319        storage_table,
320        target_qualifier,
321        doc_id,
322        document,
323        checks,
324        params,
325        scope,
326    } = context;
327    if checks.is_empty() {
328        return Ok(());
329    }
330    let row = super::rows::new_target_row_for_storage(
331        services.rows,
332        table,
333        storage_table,
334        target_qualifier,
335        doc_id,
336        document,
337    )?;
338    for check in checks {
339        let value = eval_mutation_expr(
340            services.expressions,
341            scope,
342            &check.predicate,
343            Some(&row),
344            params,
345        )?;
346        if !uqa_sql::expr::truthy(&value) {
347            return Err(super::constraints::view_check_violation(
348                constraints,
349                statement,
350                &check.view,
351                storage_table,
352                document,
353            ));
354        }
355    }
356    Ok(())
357}
358
359pub fn refresh_stored_generated_columns<S: Clone + 'static>(
360    services: MutationAssignmentContext<'_, S>,
361    table: &str,
362    document: &mut Document,
363) -> Result<(), SQLError> {
364    refresh_selected_stored_generated_columns(services, table, document, None)
365}
366
367/// Recompute only the requested generated columns for a schema rewrite, retaining unrelated stored values.
368pub fn refresh_selected_stored_generated_columns<S: Clone + 'static>(
369    services: MutationAssignmentContext<'_, S>,
370    table: &str,
371    document: &mut Document,
372    selected: Option<&[String]>,
373) -> Result<(), SQLError> {
374    let columns = describe_generated_columns(services, table)?;
375    refresh_generated_columns(services, &columns, document, selected)
376}
377
378/// Retain stored values whose inputs the UPDATE does not assign. A BEFORE ROW trigger removes this restriction because it may assign any input.
379pub fn refresh_updated_stored_generated_columns<S: Clone + 'static>(
380    services: MutationAssignmentContext<'_, S>,
381    table: &str,
382    document: &mut Document,
383    updated_columns: Option<&[String]>,
384) -> Result<(), SQLError> {
385    let columns = describe_generated_columns(services, table)?;
386    let selected = updated_columns.map(|updated| {
387        uqa_sql::semantics::generated_values::stored_columns_for_update(&columns, updated)
388    });
389    refresh_generated_columns(services, &columns, document, selected.as_deref())
390}
391
392pub(crate) fn describe_generated_columns<S: Clone + 'static>(
393    services: MutationAssignmentContext<'_, S>,
394    table: &str,
395) -> Result<Vec<uqa_sql::ast::ColumnDef>, SQLError> {
396    services
397        .columns
398        .try_describe_table(table)
399        .map_err(|error| SQLError::Internal(format!("read generated columns: {error}")))?
400        .ok_or_else(|| SQLError::UnknownTable(table.to_string()))
401}
402
403fn refresh_generated_columns<S: Clone + 'static>(
404    services: MutationAssignmentContext<'_, S>,
405    columns: &[uqa_sql::ast::ColumnDef],
406    document: &mut Document,
407    selected: Option<&[String]>,
408) -> Result<(), SQLError> {
409    let resources = services.expressions.expressions.production_resources()?;
410    super::generated::refresh_stored_generated_columns(
411        services.assignment,
412        columns,
413        selected,
414        document,
415        &resources.control(),
416        &mut |expression, row, schema| {
417            crate::query::catalog_expression::eval_lowered_expression_with_schema_and_type(
418                services.expressions.expressions,
419                services.scopes.current_routine_scope()?,
420                expression,
421                row,
422                schema,
423                &[],
424            )
425        },
426    )
427}
428
429pub fn apply_missing_column_defaults<S: Clone + 'static>(
430    services: MutationAssignmentContext<'_, S>,
431    table: &str,
432    document: &mut Document,
433    params: &[SQLParam],
434) -> Result<(), SQLError> {
435    let columns = services
436        .columns
437        .try_describe_table(table)
438        .map_err(|err| dml_storage_error("INSERT defaults", err))?
439        .ok_or_else(|| SQLError::UnknownTable(table.to_string()))?;
440    for definition in columns {
441        let col = definition.name;
442        if document.contains_key(&col) {
443            continue;
444        }
445        if definition
446            .auto_increment
447            .as_ref()
448            .is_some_and(uqa_sql::ast::AutoIncrement::is_identity)
449        {
450            continue;
451        }
452        if let Some(default_expr) = services
453            .columns
454            .try_column_insert_default_expr(table, &col)
455            .map_err(|err| dml_storage_error("INSERT defaults", err))?
456        {
457            let value =
458                evaluate_column_default(services, table, &col, Some(&default_expr), params)?;
459            document.insert(col, value);
460        }
461    }
462    Ok(())
463}