Skip to main content

uqa_execution/query/block/
execution.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Query-block validation and physical source selection.
8
9use super::{
10    binding_context, ensure_select_privileges_for_query_block, expand_from_star_columns,
11    overlay_outer_schema, projection_columns, run_select_without_from_output,
12    run_single_foreign_select_output, run_single_table_select_output,
13    validate_query_block_expression_types, validate_query_block_references,
14    validate_query_set_contexts, validate_source_set_contexts_before_build,
15    with_query_table_pseudo_columns, ComputePlan, CteScope, QueryBlockPlan, QueryOutput,
16    QueryOutputMode, SQLError, SQLParam, ScalarExpr, SingleRelation, SourceContext, SourcePlan,
17};
18use crate::query::binding::sources::{
19    bind_query_block_with_sources, ensure_select_with_sources, BoundQueryBlock, SourceBindings,
20};
21
22#[expect(
23    clippy::too_many_arguments,
24    reason = "borrows the bound source tree throughout physical assembly"
25)]
26fn run_bound_query_block_output<'a, S: Clone + Send + Sync + 'static>(
27    context: &SourceContext<'a, S>,
28    block: &'a QueryBlockPlan,
29    stmt: &'a QueryBlockPlan,
30    params: &'a [SQLParam],
31    ctes: &'a mut CteScope<S>,
32    output_mode: QueryOutputMode<'a>,
33    source_schema: &crate::RowSchema,
34    sources: Option<&SourceBindings<'_>>,
35) -> Result<QueryOutput, SQLError> {
36    // Binding and validation finish before row evaluation can reenter a routine.
37    let (expression_schema, outer) =
38        validate_bound_query_block(context, stmt, params, ctes, source_schema)?;
39    if stmt.from.is_none() {
40        return run_select_without_from_output(context, block, stmt, params, ctes, output_mode);
41    }
42    run_from_query_block(
43        context,
44        block,
45        stmt,
46        params,
47        ctes,
48        output_mode,
49        &expression_schema,
50        outer.as_ref(),
51        sources,
52    )
53}
54
55fn validate_bound_query_block<S: Clone + Send + Sync + 'static>(
56    context: &SourceContext<'_, S>,
57    stmt: &QueryBlockPlan,
58    params: &[SQLParam],
59    ctes: &CteScope<S>,
60    source_schema: &crate::RowSchema,
61) -> Result<(crate::RowSchema, Option<crate::RowSchema>), SQLError> {
62    let outer = ctes.row_lock_outer_row().map(|row| row.schema.clone());
63    let resources = context.ctes.production_resources()?;
64    let source_schema = uqa_sql::binding::with_query_table_pseudo_columns_with_control(
65        source_schema,
66        &resources.control(),
67    )?;
68    let expression_schema = uqa_sql::binding::overlay_outer_schema_with_control(
69        &source_schema,
70        outer.as_ref(),
71        &resources.control(),
72    )?;
73    validate_query_block_expression_types(
74        context.ctes.routines,
75        stmt,
76        &expression_schema,
77        params,
78        ctes,
79        &context.ctes.production_resources()?.control(),
80    )?;
81    let type_resolver = context.relational.expression_scope(ctes)?;
82    validate_query_set_contexts(
83        context.relational.catalog,
84        type_resolver.as_ref(),
85        stmt,
86        &expression_schema,
87        params,
88    )?;
89
90    let Some(from) = stmt.from.as_ref() else {
91        if stmt
92            .projections
93            .iter()
94            .any(|projection| matches!(projection.expr, ScalarExpr::Star))
95            && outer.is_none()
96        {
97            return Err(SQLError::Routine {
98                sqlstate: "42601".into(),
99                message: "SELECT * with no tables specified is not valid".into(),
100            });
101        }
102        validate_query_block_references(
103            context.ctes.routines,
104            stmt,
105            &expression_schema,
106            params,
107            ctes,
108            outer.as_ref(),
109            &context.ctes.production_resources()?.control(),
110        )?;
111        return Ok((expression_schema, outer));
112    };
113    validate_source_set_contexts_before_build(
114        context.relational.catalog,
115        type_resolver.as_ref(),
116        from,
117        params,
118        &binding_context(ctes)?,
119        outer.as_ref(),
120    )?;
121
122    Ok((expression_schema, outer))
123}
124
125#[expect(
126    clippy::too_many_arguments,
127    reason = "borrows the already validated query scopes"
128)]
129#[expect(
130    clippy::too_many_lines,
131    reason = "preserves SELECT schema and row identity"
132)]
133fn run_from_query_block<'a, S: Clone + Send + Sync + 'static>(
134    context: &SourceContext<'a, S>,
135    block: &'a QueryBlockPlan,
136    stmt: &'a QueryBlockPlan,
137    params: &'a [SQLParam],
138    ctes: &'a mut CteScope<S>,
139    output_mode: QueryOutputMode<'a>,
140    expression_schema: &crate::RowSchema,
141    outer: Option<&crate::RowSchema>,
142    sources: Option<&SourceBindings<'_>>,
143) -> Result<QueryOutput, SQLError> {
144    let from = stmt
145        .from
146        .as_ref()
147        .expect("FROM source checked before dispatch");
148    // Set-op branches, CTEs, and derived-table bodies still need the same
149    // search-aware single-table physical access path as top-level queries;
150    // otherwise registry-backed predicates such as
151    // `pool_positive_evidence(bayesian_match(...), knn_match(...))` fall
152    // through to scalar expression evaluation.
153    if let SourcePlan::Table {
154        name,
155        qualifier,
156        alias,
157        column_aliases,
158        include_descendants,
159        ..
160    } = from
161    {
162        if !ctes.is_visible_cte(name) {
163            let catalog = ctes.catalog_read_view()?;
164            let resolution = ctes.relation_name_resolution()?;
165            let foreign_table = catalog.foreign_table_entry_resolved(&resolution, name)?;
166            if alias.is_none() && column_aliases.is_empty() && foreign_table.is_some() {
167                let foreign_name = foreign_table
168                    .as_ref()
169                    .map(|(canonical, _)| canonical.as_str())
170                    .expect("foreign table presence checked above");
171                validate_query_block_references(
172                    context.ctes.routines,
173                    stmt,
174                    expression_schema,
175                    params,
176                    ctes,
177                    outer,
178                    &context.ctes.production_resources()?.control(),
179                )?;
180                ensure_select_privileges_for_query_block(stmt, from, ctes)?;
181                return run_single_foreign_select_output(
182                    context,
183                    SingleRelation {
184                        reference_name: name,
185                        relation_name: foreign_name,
186                        qualifier,
187                    },
188                    block,
189                    stmt,
190                    params,
191                    ctes,
192                    output_mode,
193                );
194            }
195            let local_table = catalog.table_name_resolved(&resolution, name)?;
196            let is_virtual =
197                name.contains('.') || (local_table.is_none() && foreign_table.is_none());
198            let schemaless = local_table.is_some()
199                && catalog
200                    .table_resolved(&resolution, name)?
201                    .is_some_and(|table| table.columns.is_empty() && !table.columns_declared);
202            // Only the overlay of this block's own table changes what it reads; changes of other tables leave its storage view as the single-table path reads it.
203            let command_overlay = match local_table.as_deref() {
204                Some(table) if ctes.reads_command_overlay() => {
205                    context.documents.command_overlay_holds(table)?
206                }
207                _ => false,
208            };
209            let has_hierarchy_descendants = local_table.is_some()
210                && catalog
211                    .hierarchy_scan_tables(&resolution, name, *include_descendants)?
212                    .len()
213                    > 1;
214            if alias.is_none() && !is_virtual && !command_overlay && !has_hierarchy_descendants {
215                let local_table = local_table
216                    .as_deref()
217                    .expect("single-table fast path requires a resolved table");
218                if let Some(filter) = stmt.r#where.as_ref() {
219                    uqa_sql::semantics::text_indexes::validate_expr_text_match_fields(
220                        context.text_indexes,
221                        local_table,
222                        filter,
223                    )?;
224                }
225                let reference_schema = if schemaless {
226                    schemaless_reference_schema(context, stmt, from, qualifier, outer, ctes)?
227                } else {
228                    expression_schema.clone()
229                };
230                validate_query_block_references(
231                    context.ctes.routines,
232                    stmt,
233                    &reference_schema,
234                    params,
235                    ctes,
236                    outer,
237                    &context.ctes.production_resources()?.control(),
238                )?;
239                ensure_select_privileges_for_query_block(stmt, from, ctes)?;
240                return run_single_table_select_output(
241                    context,
242                    super::BoundSingleRelation {
243                        relation: SingleRelation {
244                            reference_name: name,
245                            relation_name: local_table,
246                            qualifier,
247                        },
248                        schema: &reference_schema,
249                    },
250                    block,
251                    stmt,
252                    params,
253                    ctes,
254                    output_mode,
255                );
256            }
257        }
258    }
259
260    if let Some(filter) = stmt.r#where.as_ref() {
261        uqa_sql::semantics::text_indexes::validate_joined_expr_text_match_fields(
262            context.text_indexes,
263            from,
264            filter,
265        )?;
266    }
267
268    let reference_schema_is_execution_defined = stmt
269        .r#where
270        .as_ref()
271        .is_some_and(uqa_sql::semantics::contains_retrieval)
272        || source_schema_is_execution_defined(context.relational.runtime, from);
273    if !reference_schema_is_execution_defined {
274        validate_query_block_references(
275            context.ctes.routines,
276            stmt,
277            expression_schema,
278            params,
279            ctes,
280            outer,
281            &context.ctes.production_resources()?.control(),
282        )?;
283    }
284    let column_prune = context
285        .planning
286        .column_prune(stmt, from, ctes, Some(expression_schema))?;
287    let qualifier_filters = context.planning.qualifier_filters(stmt, from, ctes)?;
288    let source_row_locks = crate::query::locking::resolve_row_locks(
289        context.locking,
290        from,
291        &stmt.locking,
292        stmt.r#where.as_ref(),
293        params,
294        ctes,
295    )?;
296    let sources = ensure_select_with_sources(stmt, from, ctes, sources)?;
297    let operator = {
298        let mut scoped_ctes = ctes.enter_source_row_locks_with_control(
299            source_row_locks,
300            &context.ctes.production_resources()?.control(),
301        )?;
302        if context.planning.block_input_is_empty(stmt) {
303            crate::query::sources::empty_source_operator(
304                context,
305                from,
306                params,
307                &scoped_ctes,
308                outer,
309            )?
310        } else {
311            crate::query::sources::build_join_operator_with_bound_sources(
312                context,
313                from,
314                params,
315                &mut scoped_ctes,
316                column_prune.as_ref(),
317                qualifier_filters.as_ref(),
318                sources.as_ref(),
319            )?
320        }
321    };
322    let rewrite_subqueries = !stmt.deferred_outer_rewrites.is_empty();
323    let (operator, (rewritten, original)) =
324        crate::physical::construction::OperatorBuild::run(operator, |operator| {
325            let resources = context.ctes.production_resources()?;
326            let control = resources.control();
327            let rewritten = uqa_sql::binding::ExecutionQueryBlock::borrowed(stmt)
328                .resolve_outer_rewrites(operator.row_schema(), &control)?;
329            let original = uqa_sql::binding::ExecutionQueryBlock::borrowed(block)
330                .resolve_outer_rewrites(operator.row_schema(), &control)?;
331            Ok((rewritten, original))
332        })?;
333    let stmt = rewritten.as_ref();
334    let block = original.as_ref();
335    let mut rewritten_scope;
336    let (operator, ctes) = if rewrite_subqueries {
337        let (operator, scope) =
338            crate::physical::construction::OperatorBuild::run(operator, |_| {
339                let arena_resources = context.ctes.production_resources()?;
340                ctes.enter_scalar_subqueries_with_control(
341                    &stmt.subqueries,
342                    &arena_resources.control(),
343                )
344            })?;
345        rewritten_scope = scope;
346        (operator, &mut *rewritten_scope)
347    } else {
348        (operator, ctes)
349    };
350    let (operator, (columns, physical_filter)) =
351        crate::physical::construction::OperatorBuild::run(operator, |operator| {
352            let source_schema = operator.row_schema().clone();
353            let resources = context.ctes.production_resources()?;
354            let projection_schema = uqa_sql::binding::with_query_table_pseudo_columns_with_control(
355                &source_schema,
356                &resources.control(),
357            )?;
358            let projection_schema = uqa_sql::binding::overlay_outer_schema_with_control(
359                &projection_schema,
360                outer,
361                &resources.control(),
362            )?;
363            validate_query_block_references(
364                context.ctes.routines,
365                stmt,
366                &projection_schema,
367                params,
368                ctes,
369                outer,
370                &context.ctes.production_resources()?.control(),
371            )?;
372            let physical_filter =
373                context
374                    .planning
375                    .residual_filter(stmt, from, qualifier_filters.as_ref(), ctes)?;
376
377            let columns = expand_from_star_columns(
378                projection_columns(&stmt.projections),
379                &stmt.projections,
380                &source_schema,
381            )?;
382            Ok((columns, physical_filter))
383        })?;
384    crate::query::relational::output::execute_query_block_operator_output_owned(
385        context.relational,
386        operator,
387        physical_filter,
388        stmt,
389        block,
390        params,
391        ctes,
392        columns,
393        output_mode,
394    )
395}
396
397/// Whether a source contains an extension table function whose row shape is declared by the function result rather than by SQL metadata.
398fn source_schema_is_execution_defined(
399    context: crate::query::runtime::QueryRuntimeView<'_>,
400    source: &SourcePlan,
401) -> bool {
402    match source {
403        SourcePlan::Join { left, right, .. } => {
404            source_schema_is_execution_defined(context, left)
405                || source_schema_is_execution_defined(context, right)
406        }
407        SourcePlan::Function { name, binding, .. } => {
408            binding.as_ref().is_none_or(|binding| binding.builtin)
409                && context.has_table_function(&name.to_ascii_lowercase())
410        }
411        SourcePlan::FunctionGroup { functions, .. } => functions.iter().any(|function| {
412            function
413                .binding
414                .as_ref()
415                .is_none_or(|binding| binding.builtin)
416                && context.has_table_function(&function.name.to_ascii_lowercase())
417        }),
418        SourcePlan::Subquery { body, .. } => query_schema_is_execution_defined(context, body),
419        SourcePlan::RetainedRows(_) | SourcePlan::Table { .. } | SourcePlan::Values { .. } => false,
420    }
421}
422
423fn query_schema_is_execution_defined(
424    context: crate::query::runtime::QueryRuntimeView<'_>,
425    query: &uqa_sql::plan::QueryPlan,
426) -> bool {
427    match &query.root {
428        uqa_sql::plan::RelationalPlan::QueryBlock(block) => block
429            .from
430            .as_ref()
431            .is_some_and(|source| source_schema_is_execution_defined(context, source)),
432        uqa_sql::plan::RelationalPlan::SetOp { left, right, .. } => {
433            query_schema_is_execution_defined(context, left)
434                || query_schema_is_execution_defined(context, right)
435        }
436        uqa_sql::plan::RelationalPlan::Values { .. } => false,
437    }
438}
439
440/// Bind the query-visible fields of a schemaless table from the same projection contract that constructs its document scan.
441fn schemaless_reference_schema<S: Clone + Send + Sync + 'static>(
442    context: &SourceContext<'_, S>,
443    statement: &QueryBlockPlan,
444    source: &SourcePlan,
445    qualifier: &str,
446    outer: Option<&crate::RowSchema>,
447    ctes: &CteScope<S>,
448) -> Result<crate::RowSchema, SQLError> {
449    let columns = context
450        .planning
451        .column_prune(statement, source, ctes, None)?
452        .and_then(|prune| prune.get(qualifier).cloned())
453        .map_or_else(Vec::new, |projection| {
454            projection.requested_columns().map(str::to_owned).collect()
455        });
456    let schema = crate::RowSchema::with_qualified_types(
457        qualifier,
458        columns.clone(),
459        vec![None; columns.len()],
460    );
461    let schema = crate::RowSchema::with_wildcard_hidden_positions(&schema, 0..columns.len());
462    let schema = with_query_table_pseudo_columns(&schema);
463    Ok(overlay_outer_schema(&schema, outer))
464}
465
466pub fn execute_query_block_output<'a, S: Clone + Send + Sync + 'static>(
467    context: &SourceContext<'a, S>,
468    block: &'a QueryBlockPlan,
469    params: &'a [SQLParam],
470    ctes: &mut CteScope<S>,
471    output_mode: QueryOutputMode<'a>,
472) -> Result<QueryOutput, SQLError> {
473    let inherited_lock_identities = ctes.lock_identities.emit;
474    let arena_resources = context.ctes.production_resources()?;
475    let mut scoped_ctes = ctes.enter_query_block_with_control(block, &arena_resources.control())?;
476    let row_identity_barrier = block.distinct
477        || !block.distinct_on.is_empty()
478        || matches!(block.compute, ComputePlan::Aggregate | ComputePlan::Window);
479    scoped_ctes.lock_identities.emit =
480        !block.locking.is_empty() || (inherited_lock_identities && !row_identity_barrier);
481    scoped_ctes.lock_identities.retain_after_lock =
482        inherited_lock_identities && !row_identity_barrier;
483    let bound = prepare_query_block(context, block, params, &mut scoped_ctes)?;
484    let mut rewritten_scope;
485    let scoped_ctes = if block.deferred_outer_rewrites.is_empty() {
486        &mut *scoped_ctes
487    } else {
488        let arena_resources = context.ctes.production_resources()?;
489        rewritten_scope = scoped_ctes.enter_scalar_subqueries_with_control(
490            &bound.block.subqueries,
491            &arena_resources.control(),
492        )?;
493        &mut *rewritten_scope
494    };
495    run_bound_query_block_output(
496        context,
497        block,
498        &bound.block,
499        params,
500        scoped_ctes,
501        output_mode,
502        &bound.schema,
503        bound.sources.as_ref(),
504    )
505}
506
507/// Finish outer-row rebinding and source analysis before row evaluation can recurse. Only the selected block and source descriptors remain live in the execution frame.
508fn prepare_query_block<'a, S: Clone + Send + Sync + 'static>(
509    context: &SourceContext<'a, S>,
510    block: &'a QueryBlockPlan,
511    params: &'a [SQLParam],
512    ctes: &mut CteScope<S>,
513) -> Result<BoundQueryBlock<'a>, SQLError> {
514    if let Some(outer) = ctes.row_lock_outer_row() {
515        if let std::borrow::Cow::Owned(outer) =
516            crate::query::binding::bind_outer_rewrite_row(block, outer)
517        {
518            ctes.set_row_lock_outer_row(outer);
519        }
520    }
521    let defer_distinct_limit = uqa_sql::semantics::should_defer_distinct_limit(block);
522    let outer = ctes.row_lock_outer_row().map(|row| &row.schema);
523    bind_query_block_with_sources(
524        context.ctes.routines,
525        block,
526        params,
527        ctes,
528        uqa_sql::binding::ExecutionBindingOptions {
529            outer,
530            defer_distinct_limit,
531        },
532        None,
533        &context.ctes.production_resources()?.control(),
534    )
535}