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