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.
8use super::{
9    codec::{
10        decode_prepared_insert_spill_row, prepared_insert_spill_schema,
11        push_prepared_insert_spill_row, PreparedInsertSpillRow,
12    },
13    known_new::KnownNewInserts,
14    pending::{PendingInsertRow, PendingInsertRows},
15    rows::prepare_values_insert_row,
16    source::{InsertInputRows, InsertSelectConsumer, InsertSelectIdentity, PreparedInsertSelect},
17    supplied_identities::SuppliedIdentities,
18    triggers::insert_statement_events,
19};
20use crate::mutation::output::MutationOutput;
21use crate::mutation::statement::context::{with_mutation_snapshot, MutationStatementContext};
22use crate::{
23    mutation::{
24        assignment::{
25            apply_missing_column_defaults, eval_mutation_assignment, MutationAssignmentTarget,
26        },
27        command_scope::MutationOverlayScope,
28        conflict::update::InsertConflictLocks,
29        constraints::{partition_insert_target, ConstraintStatement},
30        errors::dml_storage_error,
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::{statement::consumer::QueryOutputMode, CteScope},
41};
42use std::{collections::BTreeSet, rc::Rc, sync::Arc};
43use uqa_sql::assignment::columns::validate_mutation_targets;
44use uqa_sql::{
45    plan::{ConflictActionPlan, ConflictPlan, InsertPlan, QueryPlan},
46    semantics::{
47        conflict::InferenceContext,
48        returning::{validate_returning_alias_relations, ReturningAnalysisContext},
49        rules::insert_inputs::{
50            required_view_rule_insert_input_positions, view_rule_insert_column_type,
51        },
52    },
53    SQLError, SQLParam,
54};
55use uqa_storage::document_store::Document;
56
57/// SQL analysis inputs and the planner's positional source-output rewrite for one INSERT.
58pub struct InsertPlanning<'a> {
59    pub inference: InferenceContext<'a>,
60    pub returning: ReturningAnalysisContext<'a>,
61    pub prune_source_outputs: fn(&mut QueryPlan, &BTreeSet<usize>, usize),
62}
63
64#[expect(clippy::too_many_lines, reason = "preserves DML lock and event order")]
65pub fn run_table_insert<S: Clone + Send + Sync + 'static>(
66    context: &MutationStatementContext<'_, S>,
67    planning: InsertPlanning<'_>,
68    stmt: &InsertPlan,
69    params: &[SQLParam],
70    inherited_ctes: Option<&CteScope<S>>,
71) -> Result<MutationOutput, SQLError> {
72    let mutation = &context.mutation;
73    let preparation = mutation.preparation;
74    let assignment = preparation.referential.assignment;
75    let triggers = preparation.referential.triggers;
76    let (statement_commands, _running_statement) =
77        statement_end::statement_commands(inherited_ctes);
78    let _trigger_scope = crate::mutation::triggers::TriggerStatementScope::enter();
79    preparation.referential.locking.session.lock_relation(
80        &stmt.table,
81        crate::row_locks::RelationLockMode::RowExclusive,
82    )?;
83    let insert_rules = mutation
84        .rules
85        .rules
86        .analysis
87        .rules
88        .rules_for(&stmt.table, uqa_sql::ast::RuleEvent::Insert)?;
89    let has_insert_rules = !insert_rules.is_empty();
90    let has_view_insert_rules = !stmt.view_rule_relations.is_empty();
91    let has_any_insert_rules = has_insert_rules || has_view_insert_rules;
92    if stmt.on_conflict.is_some()
93        && (has_insert_rules
94            || !mutation
95                .rules
96                .rules
97                .analysis
98                .rules
99                .rules_for(&stmt.table, uqa_sql::ast::RuleEvent::Update)?
100                .is_empty())
101    {
102        return Err(SQLError::Routine {
103            sqlstate: "0A000".into(),
104            message: "INSERT with ON CONFLICT clause cannot be used with table that has INSERT or UPDATE rules".into(),
105        });
106    }
107    validate_returning_alias_relations(&stmt.target_qualifier, &stmt.returning_aliases, None)?;
108    uqa_sql::semantics::rules::validate_rule_returning_contract(
109        mutation.rules.rules.analysis.rules,
110        &stmt.table,
111        uqa_sql::ast::RuleEvent::Insert,
112        !stmt.returning.is_empty(),
113    )?;
114    if let Some(view_returning) = &stmt.view_rule_returning {
115        uqa_sql::semantics::rules::validate_rule_returning_contract(
116            mutation.rules.rules.analysis.rules,
117            &view_returning.relation,
118            uqa_sql::ast::RuleEvent::Insert,
119            !view_returning.returning.is_empty(),
120        )?;
121    }
122    let prepared_statement = uqa_sql::semantics::conflict::prepare_inference_predicate(
123        planning.inference,
124        stmt,
125        params,
126    )?;
127    let stmt = prepared_statement.as_ref();
128    if let Some(conflict) = stmt.on_conflict.as_ref() {
129        uqa_sql::semantics::conflict::validate_conflict_target(
130            planning.inference.catalog,
131            &stmt.table,
132            conflict,
133        )?;
134    }
135    let conflict_update_columns = if let Some(ConflictPlan {
136        action: ConflictActionPlan::Update { assignments, .. },
137        ..
138    }) = stmt.on_conflict.as_ref()
139    {
140        validate_mutation_targets(
141            assignment.columns,
142            &stmt.table,
143            assignments
144                .iter()
145                .flat_map(|assignment| assignment.target.targets()),
146            "INSERT ON CONFLICT DO UPDATE",
147            false,
148        )?;
149        Some(
150            assignments
151                .iter()
152                .flat_map(|assignment| assignment.target.column_names())
153                .map(str::to_owned)
154                .collect::<Vec<_>>(),
155        )
156    } else {
157        None
158    };
159    if stmt.view_rule_relations.is_empty() && !stmt.columns.is_empty() {
160        validate_mutation_targets(
161            assignment.columns,
162            &stmt.table,
163            stmt.columns.iter(),
164            "INSERT",
165            true,
166        )?;
167    }
168    if stmt.view_rule_relations.is_empty() {
169        super::identity_targets::validate_insert_identity_targets(mutation.identities, stmt)?;
170    }
171    uqa_sql::semantics::returning::validate_insert_returning(
172        planning.returning,
173        stmt,
174        params,
175        inherited_ctes.map(|scope| scope as &dyn uqa_sql::semantics::returning::ReturningScope),
176    )?;
177    uqa_sql::semantics::mutation_privileges::ensure_insert_target_privileges(
178        mutation.privileges,
179        stmt,
180        conflict_update_columns.as_deref(),
181    )?;
182    // The columns the statement supplies, which its constraint violations show to a role that may not read the table.
183    let supplied_columns =
184        uqa_sql::semantics::mutation_privileges::insert_target_columns(mutation.privileges, stmt)?
185            .into_iter()
186            .chain(conflict_update_columns.iter().flatten().cloned())
187            .collect::<Vec<_>>();
188    let statement_relation = crate::mutation::constraints::statement_relation(
189        preparation.referential.constraints,
190        &stmt.table,
191    )?;
192    let statement = ConstraintStatement::new(&statement_relation, &supplied_columns);
193    let view_original_query = !stmt.view_rule_relations.iter().try_fold(
194        false,
195        |suppressed, relation| -> Result<bool, SQLError> {
196            Ok(suppressed
197                || mutation
198                    .rules
199                    .rules
200                    .analysis
201                    .rules
202                    .rules_for(relation, uqa_sql::ast::RuleEvent::Insert)?
203                    .iter()
204                    .any(|rule| rule.definition.instead && rule.definition.condition.is_none()))
205        },
206    )?;
207    let insert_original_query = view_original_query
208        && !insert_rules
209            .iter()
210            .any(|rule| rule.definition.instead && rule.definition.condition.is_none());
211    if insert_original_query {
212        crate::mutation::routine_calls::insert(context, stmt, params, inherited_ctes)?;
213    }
214    let has_before_insert_statement_trigger = insert_original_query
215        && !triggers
216            .catalog
217            .triggers_for(
218                &stmt.table,
219                uqa_sql::ast::TriggerTiming::Before,
220                uqa_sql::ast::TriggerEvent::Insert,
221                false,
222                &[],
223            )?
224            .is_empty();
225    let has_before_update_statement_trigger =
226        if let Some(columns) = conflict_update_columns.as_deref() {
227            !triggers
228                .catalog
229                .triggers_for(
230                    &stmt.table,
231                    uqa_sql::ast::TriggerTiming::Before,
232                    uqa_sql::ast::TriggerEvent::Update,
233                    false,
234                    columns,
235                )?
236                .is_empty()
237        } else {
238            false
239        };
240    let statement_snapshot = match inherited_ctes.and_then(CteScope::command_cte_snapshot) {
241        Some(snapshot) => Some(snapshot),
242        None if has_before_insert_statement_trigger
243            || has_before_update_statement_trigger
244            || stmt.ctes.iter().any(|cte| cte.body.modifies_data()) =>
245        {
246            Some(std::sync::Arc::new(context.snapshots.capture()?))
247        }
248        None => None,
249    };
250    if insert_original_query {
251        statement_commands.after_triggers().fire_before_statement(
252            &triggers,
253            &StatementEvent::new(&stmt.table, uqa_sql::ast::TriggerEvent::Insert, &[]),
254        )?;
255    }
256    if let Some(columns) = conflict_update_columns.as_deref() {
257        statement_commands.after_triggers().fire_before_statement(
258            &triggers,
259            &StatementEvent::new(&stmt.table, uqa_sql::ast::TriggerEvent::Update, columns),
260        )?;
261    }
262    let mut statement_scope = None;
263    let mut execute_read =
264        |read_context: &MutationStatementContext<'_, S>| -> Result<MutationOutput, SQLError> {
265            let read_assignment = read_context.mutation.preparation.referential.assignment;
266            let scope = statement_scope.insert(read_context.mutation.scopes.command_scope(
267                stmt.statement_privilege_subject.as_ref(),
268                stmt.relations_bound,
269            )?);
270            if let Some(parent) = inherited_ctes {
271                scope.inherit_cte_bindings(parent);
272            }
273            scope.set_statement_commands(Arc::clone(&statement_commands));
274            scope.set_command_cte_snapshot(statement_snapshot.clone());
275            crate::query::cte::materialize_command_ctes(
276                context.query.source.ctes,
277                &stmt.ctes,
278                || {
279                    uqa_sql::semantics::primary_command_cte_references(
280                        &stmt.ctes,
281                        &stmt.query_inputs(),
282                        None,
283                    )
284                },
285                params,
286                scope,
287            )?;
288            scope.scalar_subqueries = stmt.subqueries.as_slice().into();
289            // 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.
290            let (auto_id_col, id_column, identity_source) =
291                insert_identity_columns(mutation.identities, &stmt.table, "INSERT")?;
292            let mut rule_source_rows = None;
293            // 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.
294            if let Some(source) = stmt.source.as_deref() {
295                let surviving_view_rules_require_rows =
296                    uqa_sql::semantics::rules::analysis::surviving_view_rules_require_event_rows(
297                        mutation.rules.rules.analysis,
298                        &stmt.view_rule_relations,
299                        uqa_sql::ast::RuleEvent::Insert,
300                    )?;
301                if !view_original_query && !surviving_view_rules_require_rows {
302                    rule_source_rows = Some(InsertInputRows::values(&[]));
303                } else if !has_any_insert_rules {
304                    let snapshot_scope = scope.returning_statement_snapshot_scope();
305                    let mut source_scope = snapshot_scope.clone();
306                    source_scope.enable_command_progress_streaming();
307                    let consumer = Rc::new(InsertSelectConsumer::new(
308                        context.insert_source(),
309                        stmt,
310                        params,
311                        snapshot_scope,
312                        InsertSelectIdentity {
313                            auto_id_column: auto_id_col.clone(),
314                            id_column: id_column.clone(),
315                            identity_source,
316                        },
317                        conflict_update_columns.clone().unwrap_or_default(),
318                    )?);
319                    let overlay = MutationOverlayScope::new(mutation.state);
320                    crate::query::statement::execute_query_plan_output(
321                        &read_context.query,
322                        source,
323                        params,
324                        &mut source_scope,
325                        QueryOutputMode::RowConsumer(Rc::new(
326                            super::source::binding::InsertSelectOutput {
327                                binding: mutation.insert_consumers,
328                                consumer: Rc::clone(&consumer),
329                            },
330                        )),
331                    )?;
332                    let PreparedInsertSelect {
333                        rows: prepared_rows,
334                        conflict_locks,
335                        affected,
336                        returning_rows,
337                        events,
338                        has_prepared_effect,
339                        has_prepared_auto_identity,
340                        supplied_identities,
341                    } = consumer.take_prepared()?;
342                    let published = overlay.finish();
343                    if has_prepared_effect || has_prepared_auto_identity {
344                        mutation.state.prepare_writer()?;
345                        persist_auto_increment_identity(
346                            mutation.identities,
347                            &stmt.table,
348                            auto_id_col.as_deref(),
349                            "persist INSERT SELECT identity",
350                        )?;
351                    }
352                    drop(conflict_locks);
353                    let observed = supplied_identities.observe(mutation.publication.storage)?;
354                    let cancel = context.query.source.relational.runtime.cancellation_token();
355                    let apply_reader = prepared_rows
356                        .read_rows()
357                        .map_err(crate::physical::physical_exec_error)?;
358                    let mut publication = statement_end::publication_batch(&statement_commands)
359                        .with_published(published);
360                    let mut known_new = KnownNewInserts::new(
361                        preparation.referential.constraints.catalog,
362                        &id_column,
363                        stmt.on_conflict.is_some(),
364                    );
365                    for prepared_row in apply_reader {
366                        cancel.check()?;
367                        let prepared_row =
368                            prepared_row.map_err(crate::physical::physical_exec_error)?;
369                        let PreparedInsertSpillRow {
370                            target_table,
371                            document,
372                            conflict: prepared,
373                        } = decode_prepared_insert_spill_row(prepared_row)?;
374                        let inserted = known_new.identity(
375                            &target_table,
376                            &prepared,
377                            &observed,
378                            mutation.publication.identifiers,
379                        )?;
380                        apply_validated_prepared_insert(
381                            mutation.publication,
382                            &target_table,
383                            document,
384                            prepared,
385                            inserted,
386                            &mut publication,
387                        )?;
388                    }
389                    finish_mutation_publication(mutation.publication, &mut publication)?;
390                    statement_end::note_written_rows(&statement_commands, &mut publication);
391                    statement_end::end_command(
392                        &statement_commands,
393                        &triggers,
394                        &insert_statement_events(
395                            &stmt.table,
396                            insert_original_query,
397                            conflict_update_columns.as_deref(),
398                        ),
399                        events.into_after_rows(),
400                    )?;
401                    if !stmt.returning.is_empty() {
402                        return dml_returning_result(
403                            preparation.returning,
404                            DmlReturningShape {
405                                table: &stmt.table,
406                                target_qualifier: &stmt.target_qualifier,
407                                aliases: &stmt.returning_aliases,
408                                returning: &stmt.returning,
409                                params,
410                                ctes: scope,
411                                supplemental_schema: None,
412                            },
413                            returning_rows,
414                            affected,
415                        );
416                    }
417                    return Ok(MutationOutput::from_affected(affected));
418                }
419                if rule_source_rows.is_none() {
420                    let mut source = source.clone();
421                    if !view_original_query {
422                        if let Some(required_positions) = required_view_rule_insert_input_positions(
423                            mutation.rules.rules.analysis,
424                            stmt,
425                        )? {
426                            (planning.prune_source_outputs)(
427                                &mut source,
428                                &required_positions,
429                                stmt.columns.len(),
430                            );
431                        }
432                    }
433                    let mut source_scope = scope.returning_statement_snapshot_scope();
434                    source_scope.enable_command_progress_streaming();
435                    let result = crate::query::statement::execute_query_plan_output(
436                        &read_context.query,
437                        &source,
438                        params,
439                        &mut source_scope,
440                        QueryOutputMode::SharedSpill,
441                    )?;
442                    rule_source_rows = Some(InsertInputRows::query(
443                        result,
444                        context.query.source.relational.runtime.cancellation_token(),
445                    )?);
446                }
447            }
448
449            let implicit_columns = stmt.columns.is_empty();
450            let columns: Vec<uqa_sql::ast::AssignmentTarget<uqa_sql::ScalarExpr>> =
451                if implicit_columns {
452                    // INSERT without explicit column list: project the table schema.
453                    preparation
454                        .returning
455                        .catalog
456                        .try_table_columns(&stmt.table)
457                        .map_err(|error| dml_storage_error("INSERT", error))?
458                        .into_iter()
459                        .map(Into::into)
460                        .collect()
461                } else {
462                    stmt.columns.clone()
463                };
464            if view_original_query {
465                validate_mutation_targets(
466                    assignment.columns,
467                    &stmt.table,
468                    columns.iter(),
469                    "INSERT",
470                    true,
471                )?;
472            }
473
474            // 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.
475
476            let mut affected = 0u64;
477            let mut returning_rows = crate::mutation::returning::ReturningRows::new(
478                context.query.source.relational.runtime,
479            )?;
480            let cancel = context.query.source.relational.runtime.cancellation_token();
481            // 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.
482            let snapshot_scope = scope.returning_statement_snapshot_scope();
483            let overlay = MutationOverlayScope::new(mutation.state);
484            let mut conflict_locks = InsertConflictLocks::new(&preparation.referential);
485            let input_rows =
486                rule_source_rows.unwrap_or_else(|| InsertInputRows::values(&stmt.rows));
487            let prepared_schema = prepared_insert_spill_schema();
488            let mut prepared_rows = crate::SpillBuffer::new(
489                crate::query::projection::physical_work_mem_bytes(
490                    context.query.source.relational.runtime,
491                )?
492                .max(1),
493            );
494            let mut supplied_identities = SuppliedIdentities::default();
495            let mut events = crate::mutation::events::MutationEventQueue::default();
496            let mut has_prepared_effect = false;
497            let mut has_prepared_auto_identity = false;
498            let work_mem = prepared_rows.budget_bytes();
499            let mut pending_rule_rows = PendingInsertRows::new(work_mem, cancel.clone());
500            let discarded_identities = super::identity_targets::user_value_identity_columns(
501                mutation.identities,
502                stmt,
503                columns.iter().map(|column| column.column.as_str()),
504            )?;
505            let required_rule_input_positions = (!view_original_query)
506                .then(|| {
507                    required_view_rule_insert_input_positions(mutation.rules.rules.analysis, stmt)
508                })
509                .transpose()?
510                .flatten();
511            for row in input_rows {
512                cancel.check()?;
513                let row = row?;
514                if row.len() > columns.len() || (!implicit_columns && row.len() != columns.len()) {
515                    return Err(SQLError::Routine {
516                        sqlstate: "42601".into(),
517                        message: if row.len() > columns.len() {
518                            "INSERT has more expressions than target columns"
519                        } else {
520                            "INSERT has more target columns than expressions"
521                        }
522                        .into(),
523                    });
524                }
525                let mut document = Document::new();
526                for (i, col) in columns.iter().take(row.len()).enumerate() {
527                    if discarded_identities.contains(&col.column) {
528                        continue;
529                    }
530                    if required_rule_input_positions
531                        .as_ref()
532                        .is_some_and(|required| !required.contains(&i))
533                    {
534                        continue;
535                    }
536                    let value = if has_any_insert_rules
537                        && matches!(row[i], uqa_sql::ScalarExpr::Default)
538                    {
539                        None
540                    } else if !view_original_query {
541                        let ty =
542                            view_rule_insert_column_type(mutation.rules.views.rewrite, stmt, i)?;
543                        Some(crate::mutation::assignment::eval_typed_assignment(
544                            read_assignment,
545                            &snapshot_scope,
546                            crate::mutation::assignment::TypedAssignmentTarget {
547                                target: col,
548                                ty: ty.as_ref(),
549                                current: document.get(&col.column),
550                                final_column_write: !columns[i + 1..]
551                                    .iter()
552                                    .any(|next| next.column == col.column),
553                            },
554                            &row[i],
555                            None,
556                            params,
557                        )?)
558                    } else {
559                        eval_mutation_assignment(
560                            read_assignment,
561                            &snapshot_scope,
562                            MutationAssignmentTarget {
563                                table: &stmt.table,
564                                target: col,
565                                current: document.get(&col.column),
566                                final_column_write: !columns[i + 1..]
567                                    .iter()
568                                    .any(|next| next.column == col.column),
569                                action: "INSERT",
570                                new_row: true,
571                            },
572                            &row[i],
573                            None,
574                            params,
575                        )?
576                    };
577                    if let Some(value) = value {
578                        document.insert(col.column.clone(), value);
579                    }
580                }
581                if has_any_insert_rules {
582                    pending_rule_rows.push(document, None)?;
583                    continue;
584                }
585                apply_missing_column_defaults(assignment, &stmt.table, &mut document, params)?;
586                let prepared_auto_identity = prepare_auto_increment_identity(
587                    mutation.identities,
588                    &stmt.table,
589                    &id_column,
590                    identity_source,
591                    auto_id_col.as_deref(),
592                    stmt.overriding,
593                    &mut document,
594                    "prepare INSERT identity",
595                )?;
596                has_prepared_auto_identity |= prepared_auto_identity.is_some();
597                let target_table = partition_insert_target(
598                    preparation.referential.constraints,
599                    statement,
600                    &stmt.table,
601                    &document,
602                    params,
603                    stmt.include_descendants,
604                )?;
605                preparation.referential.locking.session.lock_relation(
606                    &target_table,
607                    crate::row_locks::RelationLockMode::RowExclusive,
608                )?;
609                let insert_identity = match prepared_auto_identity {
610                    Some(identity) => identity,
611                    None => prepare_insert_identity(
612                        mutation.identities,
613                        &target_table,
614                        &id_column,
615                        identity_source,
616                        None,
617                        &mut document,
618                        "prepare INSERT identity",
619                    )?,
620                };
621                if let Some(staged) = prepare_values_insert_row(
622                    preparation,
623                    stmt,
624                    statement,
625                    params,
626                    &snapshot_scope,
627                    conflict_update_columns.as_deref().unwrap_or(&[]),
628                    &id_column,
629                    identity_source,
630                    target_table,
631                    document,
632                    insert_identity,
633                    &mut conflict_locks,
634                )? {
635                    if let Some(returning) = staged.returning {
636                        returning_rows.push(returning)?;
637                    }
638                    events.append_after_rows(staged.after_row_events, &triggers)?;
639                    if staged.prepared_effect {
640                        affected += 1;
641                        has_prepared_effect = true;
642                    }
643                    supplied_identities.note(&staged.target_table, &staged.prepared);
644                    push_prepared_insert_spill_row(
645                        &mut prepared_rows,
646                        &prepared_schema,
647                        PreparedInsertSpillRow {
648                            target_table: staged.target_table,
649                            document: Arc::unwrap_or_clone(staged.document),
650                            conflict: staged.prepared,
651                        },
652                    )?;
653                }
654            }
655            let mut view_rule_rows =
656                crate::mutation::rules::RuleRowBuffer::new(work_mem, cancel.clone());
657            for index in 0..pending_rule_rows.len() {
658                let document = pending_rule_rows.get(index)?.document;
659                let rule_doc_id = crate::mutation::identity::supplied_document_identity(
660                    identity_source,
661                    &document,
662                    &id_column,
663                )?;
664                view_rule_rows.push(crate::mutation::rules::RuleRowImage {
665                    old_storage_table: None,
666                    old_doc_id: None,
667                    old: None,
668                    new_storage_table: None,
669                    new_doc_id: rule_doc_id,
670                    new: Some(document),
671                    context: None,
672                })?;
673            }
674            let view_rule_rows = view_rule_rows.finish();
675            let view_rule_batches = crate::mutation::rules::views::prepare_view_rule_batches(
676                crate::mutation::rules::views::ViewRuleBatchRequest {
677                    context: mutation.rules,
678                    relations: &stmt.view_rule_relations,
679                    event: uqa_sql::ast::RuleEvent::Insert,
680                    rows: &view_rule_rows,
681                    params,
682                    scope: &snapshot_scope,
683                    insert_plans: &stmt.view_rule_insert_plans,
684                    update_plans: &[],
685                    document_relation: None,
686                },
687            )?;
688            let mut pending_base_rows = PendingInsertRows::new(work_mem, cancel.clone());
689            for index in 0..pending_rule_rows.len() {
690                if view_rule_batches.suppresses(index)? {
691                    continue;
692                }
693                let mut document = pending_rule_rows.get(index)?.document;
694                apply_missing_column_defaults(assignment, &stmt.table, &mut document, params)?;
695                let prepared_auto_identity = prepare_auto_increment_identity(
696                    mutation.identities,
697                    &stmt.table,
698                    &id_column,
699                    identity_source,
700                    auto_id_col.as_deref(),
701                    stmt.overriding,
702                    &mut document,
703                    "prepare INSERT identity",
704                )?;
705                has_prepared_auto_identity |= prepared_auto_identity.is_some();
706                pending_base_rows.push(document, prepared_auto_identity)?;
707            }
708            let rule_batch = (has_insert_rules && view_original_query)
709                .then(|| {
710                    let rule_rows = crate::mutation::rules::RuleRows::from_rows(
711                        (0..pending_base_rows.len()).map(|index| {
712                            let mut rule_document = pending_base_rows.get(index)?.document;
713                            crate::mutation::assignment::refresh_stored_generated_columns(
714                                assignment,
715                                &stmt.table,
716                                &mut rule_document,
717                            )?;
718                            let rule_doc_id =
719                                crate::mutation::identity::supplied_document_identity(
720                                    identity_source,
721                                    &rule_document,
722                                    &id_column,
723                                )?;
724                            Ok(crate::mutation::rules::RuleRowImage {
725                                old_storage_table: None,
726                                old_doc_id: None,
727                                old: None,
728                                new_storage_table: None,
729                                new_doc_id: rule_doc_id,
730                                new: Some(rule_document),
731                                context: None,
732                            })
733                        }),
734                        work_mem,
735                        cancel.clone(),
736                    )?;
737                    crate::mutation::rules::prepare_retained_rule_batch(
738                        mutation.rules.rules,
739                        &stmt.table,
740                        uqa_sql::ast::RuleEvent::Insert,
741                        rule_rows,
742                    )
743                })
744                .transpose()?;
745            if has_any_insert_rules {
746                for rule_index in 0..pending_base_rows.len() {
747                    if rule_batch
748                        .as_ref()
749                        .map(|rule_batch| rule_batch.suppresses(rule_index))
750                        .transpose()?
751                        .unwrap_or(false)
752                    {
753                        continue;
754                    }
755                    let PendingInsertRow {
756                        mut document,
757                        identity: prepared_auto_identity,
758                    } = pending_base_rows.get(rule_index)?;
759                    let target_table = partition_insert_target(
760                        preparation.referential.constraints,
761                        statement,
762                        &stmt.table,
763                        &document,
764                        params,
765                        stmt.include_descendants,
766                    )?;
767                    preparation.referential.locking.session.lock_relation(
768                        &target_table,
769                        crate::row_locks::RelationLockMode::RowExclusive,
770                    )?;
771                    let insert_identity = match prepared_auto_identity {
772                        Some(identity) => identity,
773                        None => prepare_insert_identity(
774                            mutation.identities,
775                            &target_table,
776                            &id_column,
777                            identity_source,
778                            None,
779                            &mut document,
780                            "prepare INSERT identity",
781                        )?,
782                    };
783                    let Some(staged) = prepare_values_insert_row(
784                        preparation,
785                        stmt,
786                        statement,
787                        params,
788                        &snapshot_scope,
789                        conflict_update_columns.as_deref().unwrap_or(&[]),
790                        &id_column,
791                        identity_source,
792                        target_table,
793                        document,
794                        insert_identity,
795                        &mut conflict_locks,
796                    )?
797                    else {
798                        continue;
799                    };
800                    if let Some(returning) = staged.returning {
801                        returning_rows.push(returning)?;
802                    }
803                    events.append_after_rows(staged.after_row_events, &triggers)?;
804                    if staged.prepared_effect {
805                        affected += 1;
806                        has_prepared_effect = true;
807                    }
808                    supplied_identities.note(&staged.target_table, &staged.prepared);
809                    push_prepared_insert_spill_row(
810                        &mut prepared_rows,
811                        &prepared_schema,
812                        PreparedInsertSpillRow {
813                            target_table: staged.target_table,
814                            document: Arc::unwrap_or_clone(staged.document),
815                            conflict: staged.prepared,
816                        },
817                    )?;
818                }
819            }
820            let published = overlay.finish();
821            if has_prepared_effect || has_prepared_auto_identity {
822                mutation.state.prepare_writer()?;
823                persist_auto_increment_identity(
824                    mutation.identities,
825                    &stmt.table,
826                    auto_id_col.as_deref(),
827                    "persist INSERT identity",
828                )?;
829            }
830            drop(conflict_locks);
831            let observed = supplied_identities.observe(mutation.publication.storage)?;
832            let mut publication =
833                statement_end::publication_batch(&statement_commands).with_published(published);
834            let mut known_new = KnownNewInserts::new(
835                preparation.referential.constraints.catalog,
836                &id_column,
837                stmt.on_conflict.is_some(),
838            );
839            for row in prepared_rows
840                .drain_rows()
841                .map_err(crate::physical::physical_exec_error)?
842            {
843                cancel.check()?;
844                let PreparedInsertSpillRow {
845                    target_table,
846                    document,
847                    conflict: prepared,
848                } = decode_prepared_insert_spill_row(
849                    row.map_err(crate::physical::physical_exec_error)?,
850                )?;
851                let inserted = known_new.identity(
852                    &target_table,
853                    &prepared,
854                    &observed,
855                    mutation.publication.identifiers,
856                )?;
857                apply_validated_prepared_insert(
858                    mutation.publication,
859                    &target_table,
860                    document,
861                    prepared,
862                    inserted,
863                    &mut publication,
864                )?;
865            }
866            finish_mutation_publication(mutation.publication, &mut publication)?;
867            statement_end::note_written_rows(&statement_commands, &mut publication);
868            statement_end::end_command(
869                &statement_commands,
870                &triggers,
871                &insert_statement_events(
872                    &stmt.table,
873                    insert_original_query,
874                    conflict_update_columns.as_deref(),
875                ),
876                events.into_after_rows(),
877            )?;
878            let (rule_returning, rule_affected, rule_sets_command_tag) =
879                if let Some(rule_batch) = rule_batch.as_ref() {
880                    let outcome = rule_batch.execute_actions_with_affected(
881                        mutation.rules.rules,
882                        crate::mutation::rules::RuleReturningRequest::from_plan(
883                            &stmt.returning,
884                            &stmt.returning_aliases,
885                            &stmt.subqueries,
886                        ),
887                    )?;
888                    (
889                        outcome.returning,
890                        outcome.affected_rows,
891                        outcome.sets_command_tag,
892                    )
893                } else {
894                    (None, 0, false)
895                };
896            let view_rule_outcome = view_rule_batches.execute_actions_with_affected(
897                mutation.rules.rules,
898                stmt.view_rule_returning.as_ref(),
899            )?;
900            let view_rule_returning = view_rule_outcome.returning;
901            if view_rule_returning.is_some() && rule_returning.is_some() {
902                return Err(SQLError::Routine {
903                    sqlstate: "0A000".into(),
904                    message: "cannot have RETURNING lists in multiple rules".into(),
905                });
906            }
907            if !stmt.returning.is_empty() {
908                if let Some(view_rule_returning) = view_rule_returning {
909                    return view_rule_returning.project(preparation.returning, params, scope, None);
910                }
911                let shape = DmlReturningShape {
912                    table: &stmt.table,
913                    target_qualifier: &stmt.target_qualifier,
914                    aliases: &stmt.returning_aliases,
915                    returning: &stmt.returning,
916                    params,
917                    ctes: scope,
918                    supplemental_schema: None,
919                };
920                if let Some(rule_returning) = rule_returning {
921                    return rule_returning.project(preparation.returning, shape);
922                }
923                return dml_returning_result(
924                    preparation.returning,
925                    shape,
926                    returning_rows,
927                    affected,
928                );
929            }
930            let rule_affected = if view_rule_outcome.sets_command_tag {
931                view_rule_outcome.affected_rows
932            } else if rule_sets_command_tag {
933                rule_affected
934            } else {
935                0
936            };
937            Ok(MutationOutput::from_affected(
938                if affected == 0 && !insert_original_query {
939                    rule_affected
940                } else {
941                    affected
942                },
943            ))
944        };
945    let result = match statement_snapshot.as_deref() {
946        Some(snapshot) => with_mutation_snapshot(context.snapshots, snapshot, execute_read),
947        None => execute_read(context),
948    }?;
949    statement_end::finish_statement(context, params, &stmt.ctes, statement_scope.as_mut())?;
950    Ok(result)
951}