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