Skip to main content

uqa_execution/query/statement/
execution.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! CTE scheduling, statement snapshot selection, and physical query execution.
8mod materialized;
9
10use super::{
11    bound_consumer::bind_output_mode,
12    consumer::{QueryOutputMode, SetOperationConsumerFactory},
13    context::{with_query_snapshot, QueryContext},
14};
15use crate::query::{
16    binding::{analyze_query_plan_schema, bind_query_plan_schema},
17    block::execute_query_block_output,
18    cte::{finish_statement_ctes, install_statement_ctes, strategy::schedule_plan_ctes},
19    ordering::identity_order_columns,
20    output::{QueryOutput, QueryRows},
21    projection::{physical_exec_error, physical_work_mem_bytes},
22    relational::{
23        limit::attach_order_limit, row_count::resolve_limit_offset_with_ctes,
24        values::execute_plan_values_output,
25    },
26    CteScope,
27};
28use std::rc::Rc;
29use uqa_sql::{
30    ast::SetOpKind,
31    plan::{QueryPlan, RelationalPlan},
32    semantics::{
33        primary_query_cte_references_with_control, sets::validation::validate_values_set_contexts,
34    },
35    SQLError, SQLParam, SQLResult,
36};
37
38pub fn execute_query_plan_with_ctes<S: Clone + Send + Sync + 'static>(
39    context: &QueryContext<'_, S>,
40    plan: &QueryPlan,
41    params: &[SQLParam],
42    ctes: &mut CteScope<S>,
43) -> Result<SQLResult, SQLError> {
44    materialized::collect(|mode| execute_query_plan_output(context, plan, params, ctes, mode))
45}
46
47/// Keep the ordinary public-row and borrowed-storage paths while measuring a selected relation destination's source query.
48pub fn execute_query_plan_measured<S: Clone + Send + Sync + 'static>(
49    context: &QueryContext<'_, S>,
50    plan: &QueryPlan,
51    params: &[SQLParam],
52    ctes: &mut CteScope<S>,
53    measurement: Option<&crate::query::measurement::QueryMeasurement>,
54) -> Result<SQLResult, SQLError> {
55    materialized::collect_measured(measurement, |mode| {
56        execute_query_plan_output(context, plan, params, ctes, mode)
57    })
58}
59
60pub fn execute_query_plan_output<S: Clone + Send + Sync + 'static>(
61    context: &QueryContext<'_, S>,
62    plan: &QueryPlan,
63    params: &[SQLParam],
64    ctes: &mut CteScope<S>,
65    output_mode: QueryOutputMode<S>,
66) -> Result<QueryOutput, SQLError> {
67    let _diagnostics = context
68        .source
69        .relational
70        .runtime
71        .diagnostics
72        .bind_current()
73        .map_err(|error| crate::storage_errors::storage_error("bind query diagnostics", &error))?;
74    let prepared =
75        crate::query::sources::prepared_queries::prepare(&context.source, plan, params, ctes)?;
76    let plan = prepared.as_ref();
77    crate::query::privileges::routine_calls::query(&context.source, plan, params, ctes)?;
78    let mut running_statement = None;
79    if plan.ctes.iter().any(|cte| cte.body.modifies_data()) {
80        analyze_query_plan_schema(context.source.ctes.routines, plan, params, ctes, None)?;
81        if ctes.command_cte_snapshot().is_none() {
82            ctes.set_command_cte_snapshot(Some(std::sync::Arc::new(context.snapshots.capture()?)));
83        }
84        if ctes.statement_commands().is_none() {
85            let statement = std::sync::Arc::<crate::query::scope::StatementCommands>::default();
86            ctes.set_statement_commands(std::sync::Arc::clone(&statement));
87            running_statement = Some(crate::mutation::statement_end::enter_statement(statement));
88        }
89    }
90    let result = ctes.with_cte_producers_with_control(
91        !plan.ctes.is_empty(),
92        &context.source.ctes.production_resources()?.control(),
93        |ctes| execute_prepared_query_output(context, plan, params, ctes, output_mode),
94    );
95    drop(running_statement);
96    result
97}
98
99fn execute_prepared_query_output<S: Clone + Send + Sync + 'static>(
100    context: &QueryContext<'_, S>,
101    plan: &QueryPlan,
102    params: &[SQLParam],
103    ctes: &mut CteScope<S>,
104    output_mode: QueryOutputMode<S>,
105) -> Result<QueryOutput, SQLError> {
106    let resources = context.source.ctes.production_resources()?;
107    let mut relation_lookup =
108        ctes.enter_query_plan_scope_with_control(plan, &resources.control())?;
109    let mut visible_ctes = relation_lookup.enter_visible_ctes_with_control(
110        plan.ctes.iter().map(|cte| cte.name.as_str()),
111        &resources.control(),
112    )?;
113    let ctes = &mut *visible_ctes;
114    install_query_ctes(context, plan, params, ctes)?;
115    let output = match ctes.command_cte_snapshot() {
116        Some(snapshot) => with_query_snapshot(context.snapshots, &snapshot, |selected| {
117            execute_query_root(selected, plan, params, ctes, output_mode)
118        })?,
119        None => execute_query_root(context, plan, params, ctes, output_mode)?,
120    };
121    if plan.ctes.iter().any(|cte| cte.body.modifies_data()) {
122        finish_statement_ctes(context.source.ctes, params, ctes)?;
123        if let Some(commands) = ctes.statement_commands().cloned() {
124            context
125                .source
126                .ctes
127                .queries
128                .fire_after_triggers(commands.after_triggers())?;
129        }
130    }
131    Ok(output)
132}
133
134fn install_query_ctes<S: Clone + Send + Sync + 'static>(
135    context: &QueryContext<'_, S>,
136    plan: &QueryPlan,
137    params: &[SQLParam],
138    ctes: &mut CteScope<S>,
139) -> Result<(), SQLError> {
140    if plan.ctes.is_empty() {
141        return Ok(());
142    }
143    let scheduled = schedule_plan_ctes(context.source.ctes, context.source.volatility, plan)?;
144    let filters = context.cte_filters.output_filters(plan, ctes)?;
145    install_statement_ctes(
146        context.source.ctes,
147        &plan.ctes,
148        &scheduled,
149        |control| primary_query_cte_references_with_control(plan, control),
150        params,
151        ctes,
152        &filters,
153    )
154}
155fn execute_query_root<S: Clone + Send + Sync + 'static>(
156    context: &QueryContext<'_, S>,
157    plan: &QueryPlan,
158    params: &[SQLParam],
159    ctes: &mut CteScope<S>,
160    output_mode: QueryOutputMode<S>,
161) -> Result<QueryOutput, SQLError> {
162    match &plan.root {
163        RelationalPlan::QueryBlock(block) => execute_query_block_output(
164            &context.source,
165            block,
166            params,
167            ctes,
168            bind_output_mode(
169                context.generation,
170                output_mode,
171                context.source.types.enum_labels(),
172            )?,
173        ),
174        RelationalPlan::SetOp { .. } => {
175            execute_set_operation(context, plan, params, ctes, output_mode)
176        }
177        RelationalPlan::Values { rows, subqueries } => {
178            execute_values_root(context, rows, subqueries, params, ctes, output_mode)
179        }
180    }
181}
182
183/// VALUES validation owns its scalar-query scope; ordinary SELECT dispatch retains none of this preparation scratch while evaluating rows.
184fn execute_values_root<S: Clone + Send + Sync + 'static>(
185    context: &QueryContext<'_, S>,
186    rows: &[Vec<uqa_sql::ScalarExpr>],
187    subqueries: &[QueryPlan],
188    params: &[SQLParam],
189    ctes: &mut CteScope<S>,
190    output_mode: QueryOutputMode<S>,
191) -> Result<QueryOutput, SQLError> {
192    {
193        let arena_resources = context.source.ctes.production_resources()?;
194        let scoped_ctes =
195            ctes.enter_scalar_subqueries_with_control(subqueries, &arena_resources.control())?;
196        let type_resolver = context.source.relational.expression_scope(&scoped_ctes)?;
197        validate_values_set_contexts(
198            context.source.relational.catalog,
199            type_resolver.as_ref(),
200            rows,
201            &crate::RowSchema::default(),
202            params,
203        )?;
204    }
205    execute_plan_values_output(
206        context.source.relational,
207        rows,
208        subqueries,
209        params,
210        ctes,
211        bind_output_mode(
212            context.generation,
213            output_mode,
214            context.source.types.enum_labels(),
215        )?,
216    )
217}
218
219#[expect(
220    clippy::too_many_lines,
221    reason = "assembles set-operation execution and result delivery"
222)]
223fn execute_set_operation<S: Clone + Send + Sync + 'static>(
224    context: &QueryContext<'_, S>,
225    plan: &QueryPlan,
226    params: &[SQLParam],
227    ctes: &mut CteScope<S>,
228    output_mode: QueryOutputMode<S>,
229) -> Result<QueryOutput, SQLError> {
230    let RelationalPlan::SetOp {
231        kind,
232        all,
233        left,
234        right,
235        order_by,
236        limit,
237        with_ties,
238        offset,
239        subqueries,
240    } = &plan.root
241    else {
242        unreachable!("set-operation dispatch requires a set-operation root");
243    };
244    let set_schema =
245        bind_query_plan_schema(context.source.ctes.routines, plan, params, ctes, None)?;
246    let directional_union_all = matches!(
247        &output_mode,
248        QueryOutputMode::RowConsumer(downstream)
249            if downstream.uses_directional_scan()
250                && matches!((*kind, *all), (SetOpKind::Union, true))
251                && order_by.is_empty()
252                && !*with_ties
253    );
254    if directional_union_all {
255        let left_schema =
256            bind_query_plan_schema(context.source.ctes.routines, left, params, ctes, None)?;
257        let right_schema =
258            bind_query_plan_schema(context.source.ctes.routines, right, params, ctes, None)?;
259        let child_ctes = ctes.enter_lock_identity_emission(false);
260        let left: Box<dyn crate::PhysicalOperator + '_> =
261            context
262                .directional
263                .query_operator(left, params, &child_ctes, left_schema)?;
264        let (left, right) = crate::physical::construction::OperatorBuild::run(left, |_| {
265            context
266                .directional
267                .query_operator(right, params, &child_ctes, right_schema)
268        })?;
269        drop(child_ctes);
270        let (left, right, work_mem) =
271            crate::physical::construction::OperatorBuild::pair(left, right, |_, _| {
272                physical_work_mem_bytes(context.source.relational.runtime)
273            })?;
274        let mut operation: Box<dyn crate::PhysicalOperator + '_> = Box::new(
275            crate::ExternalSetOperation::new_directional_with_types(
276                left,
277                right,
278                *kind,
279                *all,
280                set_schema.column_types().to_vec(),
281                work_mem,
282            )
283            .map_err(physical_exec_error)?,
284        );
285        let (input, (resolved_offset, resolved_limit)) =
286            crate::physical::construction::OperatorBuild::run(operation, |_| {
287                let arena_resources = context.source.ctes.production_resources()?;
288                let scoped_ctes = ctes
289                    .enter_scalar_subqueries_with_control(subqueries, &arena_resources.control())?;
290                Ok((
291                    resolve_limit_offset_with_ctes(
292                        offset.as_deref(),
293                        context.source.relational,
294                        params,
295                        "OFFSET",
296                        &scoped_ctes,
297                    )?
298                    .unwrap_or(0),
299                    resolve_limit_offset_with_ctes(
300                        limit.as_deref(),
301                        context.source.relational,
302                        params,
303                        "LIMIT",
304                        &scoped_ctes,
305                    )?,
306                ))
307            })?;
308        operation = input;
309        if resolved_offset != 0 || resolved_limit.is_some() {
310            operation = Box::new(crate::Limit::new(
311                operation,
312                resolved_offset,
313                resolved_limit,
314            ));
315        }
316        return collect_query_operator(
317            context,
318            set_schema.columns().to_vec(),
319            operation,
320            output_mode,
321        );
322    }
323    let streaming_consumer = match &output_mode {
324        QueryOutputMode::RowConsumer(downstream)
325            if downstream.streams_set_inputs()
326                && matches!((*kind, *all), (SetOpKind::Union, true))
327                && order_by.is_empty()
328                && !*with_ties =>
329        {
330            Some(Rc::clone(downstream))
331        }
332        _ => None,
333    };
334    if let Some(downstream) = streaming_consumer {
335        let columns = set_schema.columns().to_vec();
336        let column_types = set_schema.column_types().to_vec();
337        let (resolved_offset, resolved_limit) = {
338            let arena_resources = context.source.ctes.production_resources()?;
339            let scoped_ctes =
340                ctes.enter_scalar_subqueries_with_control(subqueries, &arena_resources.control())?;
341            (
342                resolve_limit_offset_with_ctes(
343                    offset.as_deref(),
344                    context.source.relational,
345                    params,
346                    "OFFSET",
347                    &scoped_ctes,
348                )?
349                .unwrap_or(0),
350                resolve_limit_offset_with_ctes(
351                    limit.as_deref(),
352                    context.source.relational,
353                    params,
354                    "LIMIT",
355                    &scoped_ctes,
356                )?,
357            )
358        };
359        let consumer = Rc::new(SetOperationConsumerFactory::new(
360            Rc::clone(&downstream),
361            set_schema.clone(),
362            resolved_offset,
363            resolved_limit,
364        ));
365        if consumer.stopped() {
366            Rc::clone(&downstream)
367                .bind(context.generation)?
368                .begin(&columns, &set_schema)?;
369        } else {
370            let mut child_ctes = ctes.enter_lock_identity_emission(false);
371            execute_query_plan_output(
372                context,
373                left,
374                params,
375                &mut child_ctes,
376                QueryOutputMode::RowConsumer(consumer.clone()),
377            )?;
378            if !consumer.stopped() {
379                execute_query_plan_output(
380                    context,
381                    right,
382                    params,
383                    &mut child_ctes,
384                    QueryOutputMode::RowConsumer(consumer),
385                )?;
386            }
387        }
388        return Ok(QueryOutput {
389            columns,
390            column_types,
391            internal_schema: set_schema,
392            rows: QueryRows::Rows(Vec::new()),
393        });
394    }
395    // Materialize each child directly into a disk-backed, repeatable stream before starting the next child. A nested set operation therefore never owns two cardinality-sized `SQLResult.rows` vectors, and its external merge consumes batches under `work_mem`.
396    let (lhs, rhs) = {
397        let mut child_ctes = ctes.enter_lock_identity_emission(false);
398        let lhs = execute_query_plan_output(
399            context,
400            left,
401            params,
402            &mut child_ctes,
403            QueryOutputMode::SharedSpill,
404        )?;
405        let rhs = execute_query_plan_output(
406            context,
407            right,
408            params,
409            &mut child_ctes,
410            QueryOutputMode::SharedSpill,
411        )?;
412        (lhs, rhs)
413    };
414    let columns = lhs.columns.clone();
415    let left: Box<dyn crate::PhysicalOperator + '_> = lhs.into_public_operator();
416    let right: Box<dyn crate::PhysicalOperator + '_> = rhs.into_public_operator();
417    let (left, right, (work_mem, evaluator)) =
418        crate::physical::construction::OperatorBuild::pair(left, right, |_, _| {
419            Ok((
420                physical_work_mem_bytes(context.source.relational.runtime)?,
421                context.source.relational.evaluator(params, ctes)?,
422            ))
423        })?;
424    let operation: Box<dyn crate::PhysicalOperator + '_> = Box::new(
425        crate::ExternalSetOperation::new_with_types_and_evaluator(
426            left,
427            right,
428            *kind,
429            *all,
430            set_schema.column_types().to_vec(),
431            work_mem,
432            evaluator,
433        )
434        .map_err(physical_exec_error)?,
435    );
436    if !order_by.is_empty() || limit.is_some() || offset.is_some() {
437        let operation =
438            crate::physical::construction::OperatorBuild::build(operation, |operation| {
439                let resources = context.source.ctes.production_resources()?;
440                let synthetic = plan.set_ordering_with_control(&resources.control())?;
441                let ordering_scope =
442                    ctes.enter_scalar_subqueries_with_control(subqueries, &resources.control())?;
443                let evaluator = context
444                    .source
445                    .relational
446                    .evaluator(params, &ordering_scope)?;
447                let output = identity_order_columns(&columns);
448                operation.attach(|input| {
449                    attach_order_limit(
450                        input,
451                        &synthetic,
452                        &output,
453                        context.source.relational,
454                        params,
455                        &ordering_scope,
456                        context.source.relational.runtime,
457                        evaluator,
458                        None,
459                    )
460                })
461            })?;
462        return collect_query_operator(context, columns, operation, output_mode);
463    }
464    collect_query_operator(context, columns, operation, output_mode)
465}
466
467pub fn collect_query_operator<'a, S: Clone + Send + Sync + 'static>(
468    context: &QueryContext<'_, S>,
469    columns: Vec<String>,
470    operator: Box<dyn crate::PhysicalOperator + 'a>,
471    output_mode: QueryOutputMode<S>,
472) -> Result<QueryOutput, SQLError> {
473    let (operator, output_mode) =
474        crate::physical::construction::OperatorBuild::run(operator, |_| {
475            bind_output_mode(
476                context.generation,
477                output_mode,
478                context.source.types.enum_labels(),
479            )
480        })?;
481    crate::query::collection::collect_query_operator(
482        context.source.relational.runtime,
483        columns,
484        operator,
485        output_mode,
486    )
487}