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