Skip to main content

uqa_execution/mutation/insert/
source.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Streaming INSERT SELECT row preparation, with scopes bound by the statement owner.
8use super::{
9    codec::{prepared_insert_spill_schema, push_prepared_insert_spill_row, PreparedInsertSpillRow},
10    rows::{attach_prepared_insert_identity, stage_prepared_insert_row, PreparedInsertRowContext},
11};
12use crate::mutation::{
13    assignment::apply_missing_column_defaults,
14    conflict::update::{InsertConflictLocks, InsertConflictPreparation},
15    constraints::{lock_document_key_dependencies, partition_insert_target, ConstraintStatement},
16    errors::dml_storage_error,
17    identity::{
18        prepare_auto_increment_identity, prepare_insert_identity,
19        refresh_insert_identity_after_trigger, InsertIdentityContext,
20    },
21    prepared::PreparedInsertConflict,
22};
23use crate::query::{projection::physical_work_mem_bytes, runtime::QueryRuntimeView, CteScope};
24use std::cell::RefCell;
25use uqa_sql::{plan::InsertPlan, SQLError, SQLParam};
26use uqa_storage::document_store::Document;
27#[derive(Clone)]
28pub struct InsertSourceContext<'a, S: Clone + 'static> {
29    pub rows: MutationPreparationContext<'a, S>,
30    pub identities: InsertIdentityContext<'a>,
31    pub runtime: QueryRuntimeView<'a>,
32}
33impl<S: Clone + 'static> Copy for InsertSourceContext<'_, S> {}
34pub fn insert_source_expression_rows(
35    result: uqa_sql::SQLResult,
36) -> Result<Vec<Vec<crate::ScalarExpr>>, SQLError> {
37    let values = match result.positional_rows {
38        Some(rows) => rows,
39        None => result
40            .rows
41            .into_iter()
42            .map(|row| {
43                result
44                    .columns
45                    .iter()
46                    .map(|column| {
47                        row.get(column).cloned().ok_or_else(|| {
48                            SQLError::Internal(format!(
49                                "INSERT SELECT result omitted output column `{column}`"
50                            ))
51                        })
52                    })
53                    .collect::<Result<Vec<_>, SQLError>>()
54            })
55            .collect::<Result<Vec<_>, SQLError>>()?,
56    };
57    Ok(values
58        .into_iter()
59        .map(|row| row.into_iter().map(crate::ScalarExpr::Literal).collect())
60        .collect())
61}
62
63pub struct InsertSelectConsumer<S: Clone + 'static> {
64    pub state: RefCell<InsertSelectConsumerState<S>>,
65}
66
67pub struct InsertSelectIdentity {
68    pub auto_id_column: Option<String>,
69    pub id_column: String,
70    pub identity_source: crate::mutation::identity::IdentitySource,
71}
72
73pub struct InsertSelectConsumerState<S: Clone + 'static> {
74    pub stmt: InsertPlan,
75    pub params: Vec<SQLParam>,
76    pub snapshot_scope: CteScope<S>,
77    pub auto_id_column: Option<String>,
78    pub id_column: String,
79    pub identity_source: crate::mutation::identity::IdentitySource,
80    pub conflict_update_columns: Vec<String>,
81    pub columns: Option<Vec<uqa_sql::ast::AssignmentTarget<crate::ScalarExpr>>>,
82    /// The columns the statement supplies, which its constraint violations show to a role that may not read the table: the target columns the source fills and those `ON CONFLICT DO UPDATE` sets.
83    pub supplied_columns: Vec<String>,
84    /// The catalog name of the relation the statement names.
85    pub statement_relation: String,
86    /// The identity columns whose source values `OVERRIDING USER VALUE` discards.
87    pub discarded_identities: std::collections::BTreeSet<String>,
88    pub result_width: Option<usize>,
89    pub prepared_schema: crate::RowSchema,
90    pub prepared_buffer: Option<crate::SpillBuffer>,
91    pub conflict_locks: Option<InsertConflictLocks>,
92    pub affected: u64,
93    pub returning_rows: crate::mutation::returning::ReturningRows,
94    pub events: crate::mutation::events::MutationEventQueue,
95    pub has_prepared_effect: bool,
96    pub has_prepared_auto_identity: bool,
97    pub supplied_identities: super::supplied_identities::SuppliedIdentities,
98}
99
100pub struct PreparedInsertSelect {
101    pub rows: crate::SharedSpill,
102    pub conflict_locks: InsertConflictLocks,
103    pub affected: u64,
104    pub returning_rows: crate::mutation::returning::ReturningRows,
105    pub events: crate::mutation::events::MutationEventQueue,
106    pub has_prepared_effect: bool,
107    pub has_prepared_auto_identity: bool,
108    pub supplied_identities: super::supplied_identities::SuppliedIdentities,
109}
110
111impl<S: Clone + 'static> InsertSelectConsumer<S> {
112    pub fn new(
113        services: InsertSourceContext<'_, S>,
114        stmt: &InsertPlan,
115        params: &[SQLParam],
116        snapshot_scope: CteScope<S>,
117        identity: InsertSelectIdentity,
118        conflict_update_columns: Vec<String>,
119    ) -> Result<Self, SQLError> {
120        let InsertSelectIdentity {
121            auto_id_column,
122            id_column,
123            identity_source,
124        } = identity;
125        let prepared_schema = prepared_insert_spill_schema();
126        Ok(Self {
127            state: RefCell::new(InsertSelectConsumerState {
128                stmt: stmt.clone(),
129                params: params.to_vec(),
130                snapshot_scope,
131                auto_id_column,
132                id_column,
133                identity_source,
134                conflict_update_columns,
135                columns: None,
136                supplied_columns: Vec::new(),
137                statement_relation: String::new(),
138                discarded_identities: std::collections::BTreeSet::new(),
139                result_width: None,
140                prepared_schema,
141                prepared_buffer: Some(crate::SpillBuffer::new(
142                    physical_work_mem_bytes(services.runtime)?.max(1),
143                )),
144                conflict_locks: Some(InsertConflictLocks::new(&services.rows.referential)),
145                affected: 0,
146                returning_rows: crate::mutation::returning::ReturningRows::new(services.runtime)?,
147                events: crate::mutation::events::MutationEventQueue::default(),
148                has_prepared_effect: false,
149                has_prepared_auto_identity: false,
150                supplied_identities: super::supplied_identities::SuppliedIdentities::default(),
151            }),
152        })
153    }
154
155    pub fn take_prepared(&self) -> Result<PreparedInsertSelect, SQLError> {
156        let mut state = self.state.borrow_mut();
157        let buffer = state.prepared_buffer.take().ok_or_else(|| {
158            SQLError::Internal("INSERT SELECT row consumer was finalized more than once".into())
159        })?;
160        let rows = buffer
161            .into_shared(state.prepared_schema.clone())
162            .map_err(crate::query::projection::physical_exec_error)?;
163        let conflict_locks = state.conflict_locks.take().ok_or_else(|| {
164            SQLError::Internal("INSERT SELECT conflict locks were finalized more than once".into())
165        })?;
166        Ok(PreparedInsertSelect {
167            rows,
168            conflict_locks,
169            affected: state.affected,
170            returning_rows: std::mem::take(&mut state.returning_rows),
171            events: std::mem::take(&mut state.events),
172            has_prepared_effect: state.has_prepared_effect,
173            has_prepared_auto_identity: state.has_prepared_auto_identity,
174            supplied_identities: std::mem::take(&mut state.supplied_identities),
175        })
176    }
177}
178
179impl<S: Clone + 'static> InsertSelectConsumer<S> {
180    pub fn begin(
181        &self,
182        services: InsertSourceContext<'_, S>,
183        source_columns: &[String],
184        _schema: &crate::RowSchema,
185    ) -> Result<(), SQLError> {
186        let mut state = self.state.borrow_mut();
187        let result_width = source_columns.len();
188        let implicit_columns = state.stmt.columns.is_empty();
189        let columns = if implicit_columns {
190            let target_columns = services
191                .rows
192                .referential
193                .assignment
194                .rows
195                .relations
196                .column_names(&state.stmt.table)
197                .map_err(|error| dml_storage_error("INSERT SELECT", error))?;
198            if target_columns.is_empty() {
199                source_columns.iter().cloned().map(Into::into).collect()
200            } else {
201                target_columns.into_iter().map(Into::into).collect()
202            }
203        } else {
204            state.stmt.columns.clone()
205        };
206        uqa_sql::assignment::columns::validate_mutation_targets(
207            services.rows.referential.assignment.columns,
208            &state.stmt.table,
209            columns.iter(),
210            "INSERT SELECT",
211            true,
212        )?;
213        if result_width > columns.len() || (!implicit_columns && result_width != columns.len()) {
214            return Err(SQLError::TypeMismatch(format!(
215                "INSERT SELECT width {result_width} != column count {}",
216                columns.len()
217            )));
218        }
219        if let (Some(existing_columns), Some(existing_width)) =
220            (state.columns.as_ref(), state.result_width)
221        {
222            if existing_columns != &columns || existing_width != result_width {
223                return Err(SQLError::Internal(
224                    "INSERT SELECT row consumer was rebound to a different source shape".into(),
225                ));
226            }
227            return Ok(());
228        }
229        state.discarded_identities = super::identity_targets::user_value_identity_columns(
230            services.identities,
231            &state.stmt,
232            columns.iter().map(|column| column.column.as_str()),
233        )?;
234        state.statement_relation = crate::mutation::constraints::statement_relation(
235            services.rows.referential.constraints,
236            &state.stmt.table,
237        )?;
238        state.supplied_columns = columns
239            .iter()
240            .take(result_width)
241            .map(|column| column.column.clone())
242            .chain(state.conflict_update_columns.iter().cloned())
243            .collect();
244        state.columns = Some(columns);
245        state.result_width = Some(result_width);
246        Ok(())
247    }
248
249    #[expect(clippy::too_many_lines, reason = "preserves DML lock and event order")]
250    pub fn consume(
251        &self,
252        services: InsertSourceContext<'_, S>,
253        source_row: crate::OwnedPhysicalRow,
254        destination: Option<crate::mutation::returning::ReturningDestination<'_>>,
255    ) -> Result<crate::query::consumer::QueryConsumerControl, SQLError> {
256        services.runtime.check_cancelled()?;
257        let mut state = self.state.borrow_mut();
258        let InsertSelectConsumerState {
259            stmt,
260            params,
261            snapshot_scope,
262            auto_id_column,
263            id_column,
264            identity_source,
265            conflict_update_columns,
266            columns,
267            supplied_columns,
268            statement_relation,
269            discarded_identities,
270            result_width,
271            prepared_schema,
272            prepared_buffer,
273            conflict_locks,
274            affected,
275            returning_rows,
276            events,
277            has_prepared_effect,
278            has_prepared_auto_identity,
279            supplied_identities,
280        } = &mut *state;
281        let columns = columns.as_ref().ok_or_else(|| {
282            SQLError::Internal("INSERT SELECT row consumer was not initialized".into())
283        })?;
284        let result_width = result_width.ok_or_else(|| {
285            SQLError::Internal("INSERT SELECT row consumer has no source width".into())
286        })?;
287        let source_schema = &source_row.schema;
288        let source_row = source_row.view();
289        let mut document = Document::new();
290        for (index, column) in columns.iter().take(result_width).enumerate() {
291            if discarded_identities.contains(&column.column) {
292                continue;
293            }
294            if uqa_sql::assignment::columns::generated_column_kind(
295                services.rows.referential.assignment.columns,
296                &stmt.table,
297                &column.column,
298            )?
299            .is_some()
300            {
301                if uqa_sql::semantics::generated_values::insert_has_written_value(stmt, index) {
302                    return Err(
303                        uqa_sql::semantics::generated_values::generated_column_insert_error(
304                            &column.column,
305                        ),
306                    );
307                }
308                continue;
309            }
310            let value = source_row
311                .value_at(index)
312                .cloned()
313                .unwrap_or(uqa_core::Value::Null);
314            let value = crate::mutation::assignment::coerce_mutation_assignment(
315                services.rows.referential.assignment,
316                snapshot_scope,
317                crate::mutation::assignment::MutationAssignmentTarget {
318                    table: &stmt.table,
319                    target: column,
320                    current: document.get(&column.column),
321                    final_column_write: !columns[index + 1..]
322                        .iter()
323                        .any(|next| next.column == column.column),
324                    action: "INSERT SELECT",
325                    new_row: true,
326                },
327                value,
328                source_schema.column_types()[index].as_ref(),
329                None,
330                params,
331            )?;
332            document.insert(column.column.clone(), value);
333        }
334        apply_missing_column_defaults(
335            services.rows.referential.assignment,
336            &stmt.table,
337            &mut document,
338            params,
339        )?;
340        let prepared_auto_identity = prepare_auto_increment_identity(
341            services.identities,
342            &stmt.table,
343            id_column,
344            *identity_source,
345            auto_id_column.as_deref(),
346            &mut document,
347            "prepare INSERT SELECT identity",
348        )?;
349        *has_prepared_auto_identity |= prepared_auto_identity.is_some();
350        let statement = ConstraintStatement::new(statement_relation, supplied_columns);
351        let target_table = partition_insert_target(
352            services.rows.referential.constraints,
353            statement,
354            &stmt.table,
355            &document,
356            params,
357            stmt.include_descendants,
358        )?;
359        services.rows.referential.locking.session.lock_relation(
360            &target_table,
361            crate::row_locks::RelationLockMode::RowExclusive,
362        )?;
363        let mut insert_identity = match prepared_auto_identity {
364            Some(identity) => identity,
365            None => prepare_insert_identity(
366                services.identities,
367                &target_table,
368                id_column,
369                *identity_source,
370                None,
371                &mut document,
372                "prepare INSERT SELECT identity",
373            )?,
374        };
375        let Some(triggered_document) = crate::mutation::triggers::fire_before_row_triggers(
376            &services.rows.referential.triggers,
377            &target_table,
378            uqa_sql::ast::TriggerEvent::Insert,
379            insert_identity.0,
380            None,
381            Some(&document),
382            &[],
383        )?
384        else {
385            return Ok(crate::query::consumer::QueryConsumerControl::Continue);
386        };
387        document = triggered_document;
388        crate::mutation::assignment::refresh_stored_generated_columns(
389            services.rows.referential.assignment,
390            &target_table,
391            &mut document,
392        )?;
393        refresh_insert_identity_after_trigger(
394            crate::mutation::identity::IdentityAllocationContext {
395                identifiers: services.rows.referential.identifiers,
396                partitions: services.rows.referential.constraints.partitions.catalog,
397            },
398            &target_table,
399            id_column,
400            *identity_source,
401            &document,
402            &mut insert_identity,
403        )?;
404        let trigger_target = partition_insert_target(
405            services.rows.referential.constraints,
406            statement,
407            &stmt.table,
408            &document,
409            params,
410            stmt.include_descendants,
411        )?;
412        if trigger_target != target_table {
413            return Err(SQLError::Routine {
414                sqlstate: "0A000".into(),
415                message: "moving row to another partition during a BEFORE FOR EACH ROW trigger is not supported".into(),
416            });
417        }
418        let prepared_conflict = if let Some(on_conflict) = stmt.on_conflict.as_ref() {
419            conflict_locks
420                .as_mut()
421                .ok_or_else(|| {
422                    SQLError::Internal("INSERT SELECT conflict locks are unavailable".into())
423                })?
424                .prepare_document(InsertConflictPreparation {
425                    context: services.rows.referential,
426                    target_table: &stmt.table,
427                    table: &target_table,
428                    target_qualifier: &stmt.target_qualifier,
429                    on_conflict,
430                    document: &document,
431                    params,
432                    scope: snapshot_scope,
433                })?
434        } else {
435            let _key_locks = lock_document_key_dependencies(
436                services.rows.referential.constraints,
437                &target_table,
438                &document,
439                None,
440            )?;
441            PreparedInsertConflict::Unresolved
442        };
443        let mut prepared_conflict =
444            attach_prepared_insert_identity(prepared_conflict, insert_identity);
445        let prepared_effect = !matches!(&prepared_conflict, PreparedInsertConflict::Skip);
446        let (returning, row_after_events) = stage_prepared_insert_row(
447            PreparedInsertRowContext {
448                services: services.rows,
449                stmt,
450                statement,
451                storage_table: &target_table,
452                document: &document,
453                shared_document: None,
454                conflict_update_columns,
455                params,
456                scope: snapshot_scope,
457            },
458            &mut prepared_conflict,
459        )?;
460        if let Some(row) = returning {
461            returning_rows.push_to(row, destination)?;
462        }
463        events.append_after_rows(row_after_events, &services.rows.referential.triggers)?;
464        supplied_identities.note(&target_table, &prepared_conflict);
465        push_prepared_insert_spill_row(
466            prepared_buffer.as_mut().ok_or_else(|| {
467                SQLError::Internal("INSERT SELECT prepared buffer is unavailable".into())
468            })?,
469            prepared_schema,
470            PreparedInsertSpillRow {
471                target_table,
472                document,
473                conflict: prepared_conflict,
474            },
475        )?;
476        if prepared_effect {
477            *affected += 1;
478            *has_prepared_effect = true;
479        }
480        Ok(crate::query::consumer::QueryConsumerControl::Continue)
481    }
482}
483
484use crate::mutation::preparation::MutationPreparationContext;
485
486pub mod binding;