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    ) -> Result<crate::query::consumer::QueryConsumerControl, SQLError> {
255        services.runtime.check_cancelled()?;
256        let mut state = self.state.borrow_mut();
257        let InsertSelectConsumerState {
258            stmt,
259            params,
260            snapshot_scope,
261            auto_id_column,
262            id_column,
263            identity_source,
264            conflict_update_columns,
265            columns,
266            supplied_columns,
267            statement_relation,
268            discarded_identities,
269            result_width,
270            prepared_schema,
271            prepared_buffer,
272            conflict_locks,
273            affected,
274            returning_rows,
275            events,
276            has_prepared_effect,
277            has_prepared_auto_identity,
278            supplied_identities,
279        } = &mut *state;
280        let columns = columns.as_ref().ok_or_else(|| {
281            SQLError::Internal("INSERT SELECT row consumer was not initialized".into())
282        })?;
283        let result_width = result_width.ok_or_else(|| {
284            SQLError::Internal("INSERT SELECT row consumer has no source width".into())
285        })?;
286        let source_schema = &source_row.schema;
287        let source_row = source_row.view();
288        let mut document = Document::new();
289        for (index, column) in columns.iter().take(result_width).enumerate() {
290            if discarded_identities.contains(&column.column) {
291                continue;
292            }
293            if uqa_sql::assignment::columns::generated_column_kind(
294                services.rows.referential.assignment.columns,
295                &stmt.table,
296                &column.column,
297            )?
298            .is_some()
299            {
300                return Err(
301                    uqa_sql::semantics::generated_values::generated_column_insert_error(
302                        &column.column,
303                    ),
304                );
305            }
306            let value = source_row
307                .value_at(index)
308                .cloned()
309                .unwrap_or(uqa_core::Value::Null);
310            let value = crate::mutation::assignment::coerce_mutation_assignment(
311                services.rows.referential.assignment,
312                snapshot_scope,
313                crate::mutation::assignment::MutationAssignmentTarget {
314                    table: &stmt.table,
315                    target: column,
316                    current: document.get(&column.column),
317                    final_column_write: !columns[index + 1..]
318                        .iter()
319                        .any(|next| next.column == column.column),
320                    action: "INSERT SELECT",
321                    new_row: true,
322                },
323                value,
324                source_schema.column_types()[index].as_ref(),
325                None,
326                params,
327            )?;
328            document.insert(column.column.clone(), value);
329        }
330        apply_missing_column_defaults(
331            services.rows.referential.assignment,
332            &stmt.table,
333            &mut document,
334            params,
335        )?;
336        let prepared_auto_identity = prepare_auto_increment_identity(
337            services.identities,
338            &stmt.table,
339            id_column,
340            *identity_source,
341            auto_id_column.as_deref(),
342            stmt.overriding,
343            &mut document,
344            "prepare INSERT SELECT identity",
345        )?;
346        *has_prepared_auto_identity |= prepared_auto_identity.is_some();
347        let statement = ConstraintStatement::new(statement_relation, supplied_columns);
348        let target_table = partition_insert_target(
349            services.rows.referential.constraints,
350            statement,
351            &stmt.table,
352            &document,
353            params,
354            stmt.include_descendants,
355        )?;
356        services.rows.referential.locking.session.lock_relation(
357            &target_table,
358            crate::row_locks::RelationLockMode::RowExclusive,
359        )?;
360        let mut insert_identity = match prepared_auto_identity {
361            Some(identity) => identity,
362            None => prepare_insert_identity(
363                services.identities,
364                &target_table,
365                id_column,
366                *identity_source,
367                None,
368                &mut document,
369                "prepare INSERT SELECT identity",
370            )?,
371        };
372        let Some(triggered_document) = crate::mutation::triggers::fire_before_row_triggers(
373            &services.rows.referential.triggers,
374            &target_table,
375            uqa_sql::ast::TriggerEvent::Insert,
376            insert_identity.0,
377            None,
378            Some(&document),
379            &[],
380        )?
381        else {
382            return Ok(crate::query::consumer::QueryConsumerControl::Continue);
383        };
384        document = triggered_document;
385        crate::mutation::assignment::refresh_stored_generated_columns(
386            services.rows.referential.assignment,
387            &target_table,
388            &mut document,
389        )?;
390        refresh_insert_identity_after_trigger(
391            crate::mutation::identity::IdentityAllocationContext {
392                identifiers: services.rows.referential.identifiers,
393                partitions: services.rows.referential.constraints.partitions.catalog,
394            },
395            &target_table,
396            id_column,
397            *identity_source,
398            &document,
399            &mut insert_identity,
400        )?;
401        let trigger_target = partition_insert_target(
402            services.rows.referential.constraints,
403            statement,
404            &stmt.table,
405            &document,
406            params,
407            stmt.include_descendants,
408        )?;
409        if trigger_target != target_table {
410            return Err(SQLError::Routine {
411                sqlstate: "0A000".into(),
412                message: "moving row to another partition during a BEFORE FOR EACH ROW trigger is not supported".into(),
413            });
414        }
415        let prepared_conflict = if let Some(on_conflict) = stmt.on_conflict.as_ref() {
416            conflict_locks
417                .as_mut()
418                .ok_or_else(|| {
419                    SQLError::Internal("INSERT SELECT conflict locks are unavailable".into())
420                })?
421                .prepare_document(InsertConflictPreparation {
422                    context: services.rows.referential,
423                    target_table: &stmt.table,
424                    table: &target_table,
425                    target_qualifier: &stmt.target_qualifier,
426                    on_conflict,
427                    document: &document,
428                    params,
429                    scope: snapshot_scope,
430                })?
431        } else {
432            let _key_locks = lock_document_key_dependencies(
433                services.rows.referential.constraints,
434                &target_table,
435                &document,
436                None,
437            )?;
438            PreparedInsertConflict::Unresolved
439        };
440        let mut prepared_conflict =
441            attach_prepared_insert_identity(prepared_conflict, insert_identity);
442        let prepared_effect = !matches!(&prepared_conflict, PreparedInsertConflict::Skip);
443        let (returning, row_after_events) = stage_prepared_insert_row(
444            PreparedInsertRowContext {
445                services: services.rows,
446                stmt,
447                statement,
448                storage_table: &target_table,
449                document: &document,
450                shared_document: None,
451                conflict_update_columns,
452                params,
453                scope: snapshot_scope,
454            },
455            &mut prepared_conflict,
456        )?;
457        if let Some(row) = returning {
458            returning_rows.push(row)?;
459        }
460        events.append_after_rows(row_after_events, &services.rows.referential.triggers)?;
461        supplied_identities.note(&target_table, &prepared_conflict);
462        push_prepared_insert_spill_row(
463            prepared_buffer.as_mut().ok_or_else(|| {
464                SQLError::Internal("INSERT SELECT prepared buffer is unavailable".into())
465            })?,
466            prepared_schema,
467            PreparedInsertSpillRow {
468                target_table,
469                document,
470                conflict: prepared_conflict,
471            },
472        )?;
473        if prepared_effect {
474            *affected += 1;
475            *has_prepared_effect = true;
476        }
477        Ok(crate::query::consumer::QueryConsumerControl::Continue)
478    }
479}
480
481use crate::mutation::preparation::MutationPreparationContext;
482
483pub mod binding;
484mod inputs;
485pub(super) use inputs::InsertInputRows;