Skip to main content

uqa_execution/mutation/insert/
table.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Table INSERT scheduling, snapshot reads, row staging, and publication.
8
9mod query;
10use super::{
11    codec::{
12        decode_prepared_insert_spill_row, prepared_insert_spill_schema,
13        push_prepared_insert_spill_row, PreparedInsertSpillRow,
14    },
15    known_new::KnownNewInserts,
16    rows::prepare_values_insert_row,
17    source::{InsertSelectConsumer, InsertSelectIdentity, PreparedInsertSelect},
18    supplied_identities::SuppliedIdentities,
19    triggers::insert_statement_events,
20};
21use crate::mutation::output::MutationOutput;
22use crate::mutation::statement::context::{with_mutation_snapshot, MutationStatementContext};
23use crate::{
24    mutation::{
25        assignment::{
26            apply_missing_column_defaults, eval_mutation_assignment, MutationAssignmentTarget,
27        },
28        command_scope::MutationOverlayScope,
29        conflict::update::InsertConflictLocks,
30        constraints::{partition_insert_target, ConstraintStatement},
31        identity::{
32            insert_identity_columns, persist_auto_increment_identity,
33            prepare_auto_increment_identity, prepare_insert_identity,
34        },
35        publication::{apply_validated_prepared_insert, finish_mutation_publication},
36        returning::{dml_returning_result, DmlReturningShape},
37        statement_end,
38        triggers::queue::StatementEvent,
39    },
40    query::CteScope,
41};
42use std::{rc::Rc, sync::Arc};
43use uqa_sql::assignment::columns::validate_mutation_targets_with_control;
44use uqa_sql::{
45    plan::{ConflictActionPlan, ConflictPlan, InsertPlan, QueryPlan},
46    semantics::{
47        conflict::InferenceContext,
48        returning::{validate_returning_alias_relations, ReturningAnalysisContext},
49    },
50    SQLError, SQLParam,
51};
52use uqa_storage::document_store::Document;
53
54/// SQL analysis inputs and the planner's positional source-output rewrite for one INSERT.
55pub struct InsertPlanning<'a> {
56    pub inference: InferenceContext<'a>,
57    pub returning: ReturningAnalysisContext<'a>,
58    pub prune_source_outputs: crate::mutation::views::commands::SourceOutputPruning,
59}
60
61#[expect(clippy::too_many_lines, reason = "preserves DML lock and event order")]
62pub fn run_table_insert<S: Clone + Send + Sync + 'static>(
63    context: &MutationStatementContext<'_, S>,
64    planning: InsertPlanning<'_>,
65    stmt: &InsertPlan,
66    params: &[SQLParam],
67    inherited_ctes: Option<&CteScope<S>>,
68) -> Result<MutationOutput, SQLError> {
69    let mutation = &context.mutation;
70    let preparation = mutation.preparation;
71    let assignment = preparation.referential.assignment;
72    let triggers = preparation.referential.triggers;
73    let (statement_commands, _running_statement) =
74        statement_end::statement_commands(context.query.source.ctes, inherited_ctes)?;
75    let _trigger_scope = crate::mutation::triggers::TriggerStatementScope::enter();
76    preparation.referential.locking.session.lock_relation(
77        &stmt.table,
78        crate::row_locks::RelationLockMode::RowExclusive,
79    )?;
80    let insert_rules = mutation
81        .rules
82        .rules
83        .capture_rules(&stmt.table, uqa_sql::ast::RuleEvent::Insert)?;
84    let has_insert_rules = !insert_rules.is_empty()?;
85    let has_view_insert_rules = !stmt.view_rule_relations.is_empty();
86    let has_any_insert_rules = has_insert_rules || has_view_insert_rules;
87    if stmt.on_conflict.is_some()
88        && (has_insert_rules
89            || !mutation
90                .rules
91                .rules
92                .capture_rules(&stmt.table, uqa_sql::ast::RuleEvent::Update)?
93                .is_empty()?)
94    {
95        return Err(SQLError::Routine {
96            sqlstate: "0A000".into(),
97            message: "INSERT with ON CONFLICT clause cannot be used with table that has INSERT or UPDATE rules".into(),
98        });
99    }
100    validate_returning_alias_relations(&stmt.target_qualifier, &stmt.returning_aliases, None)?;
101    uqa_sql::semantics::rules::validate_rule_returning_contract(
102        mutation.rules.rules.analysis.rules,
103        &stmt.table,
104        uqa_sql::ast::RuleEvent::Insert,
105        !stmt.returning.is_empty(),
106    )?;
107    if let Some(view_returning) = &stmt.view_rule_returning {
108        uqa_sql::semantics::rules::validate_rule_returning_contract(
109            mutation.rules.rules.analysis.rules,
110            &view_returning.relation,
111            uqa_sql::ast::RuleEvent::Insert,
112            !view_returning.returning.is_empty(),
113        )?;
114    }
115    let resources = context.query.source.ctes.production_resources()?;
116    let control = resources.control();
117    let prepared_statement =
118        uqa_sql::semantics::conflict::prepare_inference_predicate_with_control(
119            planning.inference,
120            stmt,
121            params,
122            &control,
123        )?;
124    let stmt = prepared_statement.as_ref().map_or(stmt, |command| {
125        let uqa_sql::plan::CommandPlan::Insert(insert) = &**command else {
126            unreachable!("INSERT inference")
127        };
128        insert
129    });
130    if let Some(conflict) = stmt.on_conflict.as_ref() {
131        uqa_sql::semantics::conflict::validate_conflict_target(
132            planning.inference.catalog,
133            &stmt.table,
134            conflict,
135        )?;
136    }
137    let conflict_update_columns_owner = if let Some(ConflictPlan {
138        action: ConflictActionPlan::Update { assignments, .. },
139        ..
140    }) = stmt.on_conflict.as_ref()
141    {
142        validate_mutation_targets_with_control(
143            assignment.columns,
144            &stmt.table,
145            assignments
146                .iter()
147                .flat_map(|assignment| assignment.target.targets()),
148            "INSERT ON CONFLICT DO UPDATE",
149            false,
150            &control,
151        )?;
152        Some(
153            uqa_sql::semantics::mutation_privileges::assignment_column_names_with_control(
154                assignments,
155                &control,
156            )?,
157        )
158    } else {
159        None
160    };
161    let conflict_update_columns = conflict_update_columns_owner
162        .as_ref()
163        .map(|columns| columns.as_slice());
164    if stmt.view_rule_relations.is_empty() && !stmt.columns.is_empty() {
165        validate_mutation_targets_with_control(
166            assignment.columns,
167            &stmt.table,
168            stmt.columns.iter(),
169            "INSERT",
170            true,
171            &control,
172        )?;
173    }
174    if stmt.view_rule_relations.is_empty() {
175        super::identity_targets::validate_insert_identity_targets(
176            mutation.identities,
177            stmt,
178            &control,
179        )?;
180    }
181    uqa_sql::semantics::returning::validate_insert_returning(
182        planning.returning,
183        stmt,
184        params,
185        inherited_ctes.map(|scope| scope as &dyn uqa_sql::semantics::returning::ReturningScope),
186    )?;
187    uqa_sql::semantics::mutation_privileges::ensure_insert_target_privileges_with_control(
188        mutation.privileges,
189        stmt,
190        conflict_update_columns,
191        &control,
192    )?;
193    // The columns the statement supplies, which its constraint violations show to a role that may not read the table.
194    let supplied_columns =
195        uqa_sql::semantics::mutation_privileges::insert_constraint_columns_with_control(
196            mutation.privileges,
197            stmt,
198            conflict_update_columns,
199            &control,
200        )?;
201    let statement_relation = crate::mutation::constraints::statement_relation(
202        preparation.referential.constraints,
203        &stmt.table,
204    )?;
205    let statement = ConstraintStatement::new(&statement_relation, &supplied_columns);
206    let view_original_query = !stmt.view_rule_relations.iter().try_fold(
207        false,
208        |suppressed, relation| -> Result<bool, SQLError> {
209            Ok(suppressed
210                || mutation
211                    .rules
212                    .rules
213                    .capture_rules(relation, uqa_sql::ast::RuleEvent::Insert)?
214                    .any(|rule| rule.definition.instead && rule.definition.condition.is_none())?)
215        },
216    )?;
217    let insert_original_query = view_original_query
218        && !insert_rules
219            .any(|rule| rule.definition.instead && rule.definition.condition.is_none())?;
220    if insert_original_query {
221        if !stmt.view_rule_relations.is_empty() {
222            super::identity_targets::validate_insert_identity_targets(
223                mutation.identities,
224                stmt,
225                &control,
226            )?;
227        }
228        crate::mutation::routine_calls::insert(context, stmt, params, inherited_ctes)?;
229    }
230    let has_before_insert_statement_trigger = insert_original_query
231        && !triggers
232            .catalog
233            .triggers_for(
234                &stmt.table,
235                uqa_sql::ast::TriggerTiming::Before,
236                uqa_sql::ast::TriggerEvent::Insert,
237                false,
238                &[],
239            )?
240            .is_empty();
241    let has_before_update_statement_trigger = if let Some(columns) = conflict_update_columns {
242        !triggers
243            .catalog
244            .triggers_for(
245                &stmt.table,
246                uqa_sql::ast::TriggerTiming::Before,
247                uqa_sql::ast::TriggerEvent::Update,
248                false,
249                columns,
250            )?
251            .is_empty()
252    } else {
253        false
254    };
255    let statement_snapshot = match inherited_ctes.and_then(CteScope::command_cte_snapshot) {
256        Some(snapshot) => Some(snapshot),
257        None if has_before_insert_statement_trigger
258            || has_before_update_statement_trigger
259            || stmt.ctes.iter().any(|cte| cte.body.modifies_data()) =>
260        {
261            Some(std::sync::Arc::new(context.snapshots.capture()?))
262        }
263        None => None,
264    };
265    if insert_original_query {
266        statement_commands.after_triggers().fire_before_statement(
267            &triggers,
268            &StatementEvent::new(&stmt.table, uqa_sql::ast::TriggerEvent::Insert, &[]),
269        )?;
270    }
271    if let Some(columns) = conflict_update_columns {
272        statement_commands.after_triggers().fire_before_statement(
273            &triggers,
274            &StatementEvent::new(&stmt.table, uqa_sql::ast::TriggerEvent::Update, columns),
275        )?;
276    }
277    let mut statement_scope = None;
278    let mut execute_read =
279        |read_context: &MutationStatementContext<'_, S>| -> Result<MutationOutput, SQLError> {
280            let read_assignment = read_context.mutation.preparation.referential.assignment;
281            let scope = statement_scope.insert(read_context.mutation.scopes.command_scope(
282                stmt.statement_privilege_subject.as_ref(),
283                stmt.relations_bound,
284            )?);
285            if let Some(parent) = inherited_ctes {
286                scope.inherit_cte_bindings_with_control(parent, &control)?;
287            }
288            scope.set_statement_commands(Arc::clone(&statement_commands));
289            scope.set_command_cte_snapshot(statement_snapshot.clone());
290            crate::query::cte::materialize_command_ctes(
291                context.query.source.ctes,
292                &stmt.ctes,
293                |control| {
294                    uqa_sql::semantics::primary_command_cte_references_with_control(
295                        &stmt.ctes,
296                        stmt.query_inputs(),
297                        None,
298                        control,
299                    )
300                },
301                params,
302                scope,
303            )?;
304            let arena_resources = context.query.source.ctes.production_resources()?;
305            scope.scalar_subqueries = uqa_sql::plan::RetainedQueryArena::capture(
306                &stmt.subqueries,
307                &arena_resources.control(),
308            )?;
309            let query_rules = (has_any_insert_rules || stmt.rule_values_input.is_some())
310                .then(|| {
311                    mutation
312                        .rules
313                        .rules
314                        .bind_insert_queries(stmt, scope.privilege_subject()?)
315                })
316                .transpose()?;
317            if let Some(queries) = &query_rules {
318                if queries.original.is_none() {
319                    return crate::mutation::rules::run_insert_query_rules(
320                        &mutation.rules.rules,
321                        preparation.returning,
322                        queries,
323                        params,
324                        scope,
325                        planning.prune_source_outputs,
326                    );
327                }
328            }
329            // Resolve the column that names an inserted row: the table's single PRIMARY KEY column, whether a sequence generates its values or not, and otherwise the conventional legacy `id` slot of a table without declared columns. Both VALUES and SELECT sources must derive the internal doc id from this same column or later primary-key rewrites can address a different row than the one that was inserted.
330            let (auto_id_col, id_column, identity_source) =
331                insert_identity_columns(mutation.identities, &stmt.table, "INSERT")?;
332            // INSERT ... SELECT: the query executor feeds each positional physical row directly into the INSERT sink. Ordinary source scans and scalar subqueries retain the statement snapshot, while a VOLATILE callback observes the logical mutations staged by preceding rows of this command.
333            if let Some(source) = stmt.source.as_deref().or_else(|| {
334                query_rules
335                    .as_ref()
336                    .and_then(|queries| queries.original.as_deref())
337            }) {
338                let output = query::run(query::InsertQueryExecution {
339                    context,
340                    read_context,
341                    stmt,
342                    source: query_rules
343                        .as_ref()
344                        .and_then(|queries| queries.original.as_deref())
345                        .unwrap_or(source),
346                    params,
347                    scope,
348                    identity: InsertSelectIdentity {
349                        auto_id_column: auto_id_col,
350                        id_column,
351                        identity_source,
352                    },
353                    conflict_update_columns,
354                    statement_commands: &statement_commands,
355                    control,
356                })?;
357                if let Some(queries) = &query_rules {
358                    crate::mutation::rules::run_insert_query_rules(
359                        &mutation.rules.rules,
360                        preparation.returning,
361                        queries,
362                        params,
363                        scope,
364                        planning.prune_source_outputs,
365                    )?;
366                }
367                return Ok(output);
368            }
369
370            let implicit_columns = stmt.columns.is_empty();
371            let owned_columns;
372            let columns: &[uqa_sql::ast::AssignmentTarget<uqa_sql::ScalarExpr>] =
373                if implicit_columns {
374                    let mut targets = uqa_core::memory::ProductionVec::new(control);
375                    preparation
376                        .returning
377                        .catalog
378                        .visit_column_names_with_control(&stmt.table, &control, &mut |name| {
379                            targets.push_produced(
380                                uqa_sql::assignment::targets::whole_column_with_control(
381                                    name, &control,
382                                )?,
383                            )?;
384                            Ok(())
385                        })
386                        .map_err(|error| {
387                            uqa_sql::catalog::errors::dml_storage_error_with_control(
388                                "INSERT", error, &control,
389                            )
390                        })?;
391                    owned_columns = targets.finish()?;
392                    &owned_columns
393                } else {
394                    &stmt.columns
395                };
396            if view_original_query {
397                validate_mutation_targets_with_control(
398                    assignment.columns,
399                    &stmt.table,
400                    columns.iter(),
401                    "INSERT",
402                    true,
403                    &control,
404                )?;
405            }
406
407            // No explicit id and no auto-increment column: allocate a synthetic u64 doc_id at insert time. Every table has an implicit doc_id even when the schema declares no primary key.
408
409            let mut affected = 0u64;
410            let mut returning_rows = crate::mutation::returning::ReturningRows::new(
411                context.query.source.relational.runtime,
412            )?;
413            let cancel = context.query.source.relational.runtime.cancellation_token();
414            // Evaluate, validate, and stage every VALUES row before writer promotion. A scalar subquery inside VALUES may carry FOR UPDATE, so holding the backend writer during that wait would fabricate a deadlock. Ordinary subqueries retain the statement snapshot while VOLATILE functions read the logical overlay left by preceding rows, matching PostgreSQL 18 command visibility.
415            let snapshot_scope = scope.returning_statement_snapshot_scope_with_control(&control)?;
416            let overlay = MutationOverlayScope::new(mutation.state);
417            let mut conflict_locks = InsertConflictLocks::new(&preparation.referential);
418            let prepared_schema = prepared_insert_spill_schema();
419            let mut prepared_rows = crate::SpillBuffer::new(
420                crate::query::projection::physical_work_mem_bytes(
421                    context.query.source.relational.runtime,
422                )?
423                .max(1),
424            );
425            let mut supplied_identities = SuppliedIdentities::default();
426            let mut events = crate::mutation::events::MutationEventQueue::default();
427            let mut has_prepared_effect = false;
428            let mut has_prepared_auto_identity = false;
429            let discarded_identities =
430                super::identity_targets::user_value_identity_columns_with_control(
431                    mutation.identities,
432                    stmt,
433                    columns.iter().map(|column| column.column.as_str()),
434                    &control,
435                )?;
436            for row in &stmt.rows {
437                cancel.check()?;
438                if row.len() > columns.len() || (!implicit_columns && row.len() != columns.len()) {
439                    return Err(SQLError::Routine {
440                        sqlstate: "42601".into(),
441                        message: if row.len() > columns.len() {
442                            "INSERT has more expressions than target columns"
443                        } else {
444                            "INSERT has more target columns than expressions"
445                        }
446                        .into(),
447                    });
448                }
449                let mut document = Document::new();
450                for (i, col) in columns.iter().take(row.len()).enumerate() {
451                    if discarded_identities.contains(&col.column) {
452                        continue;
453                    }
454                    let value = eval_mutation_assignment(
455                        read_assignment,
456                        &snapshot_scope,
457                        MutationAssignmentTarget {
458                            table: &stmt.table,
459                            target: col,
460                            current: document.get(&col.column),
461                            final_column_write: !columns[i + 1..]
462                                .iter()
463                                .any(|next| next.column == col.column),
464                            action: "INSERT",
465                            new_row: true,
466                        },
467                        &row[i],
468                        None,
469                        params,
470                    )?;
471                    if let Some(value) = value {
472                        document.insert(col.column.clone(), value);
473                    }
474                }
475                apply_missing_column_defaults(assignment, &stmt.table, &mut document, params)?;
476                let prepared_auto_identity = prepare_auto_increment_identity(
477                    mutation.identities,
478                    &stmt.table,
479                    &id_column,
480                    identity_source,
481                    auto_id_col.as_deref(),
482                    &mut document,
483                    "prepare INSERT identity",
484                )?;
485                has_prepared_auto_identity |= prepared_auto_identity.is_some();
486                let target_table = partition_insert_target(
487                    preparation.referential.constraints,
488                    statement,
489                    &stmt.table,
490                    &document,
491                    params,
492                    stmt.include_descendants,
493                )?;
494                preparation.referential.locking.session.lock_relation(
495                    &target_table,
496                    crate::row_locks::RelationLockMode::RowExclusive,
497                )?;
498                let insert_identity = match prepared_auto_identity {
499                    Some(identity) => identity,
500                    None => prepare_insert_identity(
501                        mutation.identities,
502                        &target_table,
503                        &id_column,
504                        identity_source,
505                        None,
506                        &mut document,
507                        "prepare INSERT identity",
508                    )?,
509                };
510                if let Some(staged) = prepare_values_insert_row(
511                    preparation,
512                    stmt,
513                    statement,
514                    params,
515                    &snapshot_scope,
516                    conflict_update_columns.unwrap_or(&[]),
517                    &id_column,
518                    identity_source,
519                    target_table,
520                    document,
521                    insert_identity,
522                    &mut conflict_locks,
523                )? {
524                    if let Some(returning) = staged.returning {
525                        returning_rows.push_to(
526                            returning,
527                            context.mutation.preparation.returning.destination,
528                        )?;
529                    }
530                    events.append_after_rows(staged.after_row_events, &triggers)?;
531                    if staged.prepared_effect {
532                        affected += 1;
533                        has_prepared_effect = true;
534                    }
535                    supplied_identities.note(&staged.target_table, &staged.prepared);
536                    push_prepared_insert_spill_row(
537                        &mut prepared_rows,
538                        &prepared_schema,
539                        PreparedInsertSpillRow {
540                            target_table: staged.target_table,
541                            document: Arc::unwrap_or_clone(staged.document),
542                            conflict: staged.prepared,
543                        },
544                    )?;
545                }
546            }
547            let published = overlay.finish();
548            if has_prepared_effect || has_prepared_auto_identity {
549                mutation.state.prepare_writer()?;
550                persist_auto_increment_identity(
551                    mutation.identities,
552                    &stmt.table,
553                    auto_id_col.as_deref(),
554                    "persist INSERT identity",
555                )?;
556            }
557            drop(conflict_locks);
558            let observed = supplied_identities.observe(mutation.publication.storage)?;
559            let mut publication =
560                statement_end::publication_batch(&statement_commands).with_published(published);
561            let mut known_new = KnownNewInserts::new(
562                preparation.referential.constraints.catalog,
563                &id_column,
564                stmt.on_conflict.is_some(),
565            );
566            for row in prepared_rows
567                .drain_rows()
568                .map_err(crate::physical::physical_exec_error)?
569            {
570                cancel.check()?;
571                let PreparedInsertSpillRow {
572                    target_table,
573                    document,
574                    conflict: prepared,
575                } = decode_prepared_insert_spill_row(
576                    row.map_err(crate::physical::physical_exec_error)?,
577                )?;
578                let inserted = known_new.identity(
579                    &target_table,
580                    &prepared,
581                    &observed,
582                    mutation.publication.identifiers,
583                )?;
584                apply_validated_prepared_insert(
585                    mutation.publication,
586                    &target_table,
587                    document,
588                    prepared,
589                    inserted,
590                    &mut publication,
591                )?;
592            }
593            finish_mutation_publication(mutation.publication, &mut publication)?;
594            statement_end::note_written_rows(&statement_commands, &mut publication);
595            statement_end::end_command(
596                &statement_commands,
597                &triggers,
598                &insert_statement_events(
599                    &stmt.table,
600                    insert_original_query,
601                    conflict_update_columns,
602                ),
603                events.into_after_rows(),
604            )?;
605            if !stmt.returning.is_empty() {
606                let shape = DmlReturningShape {
607                    table: &stmt.table,
608                    target_qualifier: &stmt.target_qualifier,
609                    aliases: &stmt.returning_aliases,
610                    returning: &stmt.returning,
611                    params,
612                    ctes: scope,
613                    supplemental_schema: None,
614                };
615                return dml_returning_result(
616                    preparation.returning,
617                    shape,
618                    returning_rows,
619                    affected,
620                );
621            }
622            Ok(MutationOutput::from_affected(affected))
623        };
624    let result = match statement_snapshot.as_deref() {
625        Some(snapshot) => with_mutation_snapshot(context.snapshots, snapshot, execute_read),
626        None => execute_read(context),
627    };
628    statement_end::finish_statement(
629        context,
630        params,
631        &stmt.ctes,
632        statement_scope.as_mut(),
633        result,
634    )
635}