uqa-execution 0.6.3

Volcano physical operators with row-batch pipelines
Documentation
//
// Unified Query Algebra
//
// Copyright (c) 2023-2026 Cognica, Inc.
//

//! Physical relational assembly with independent expression and lock construction services.

use crate::query::recheck_source::LockRowsRecheckInput;
use crate::query::runtime::QueryRuntimeView;
use crate::query::set_projection::{SetFunctionRuntime, SetProjectionOutput};
use crate::query::CteScope;
use crate::{PhysicalOperator, ScalarExpr, SharedExpressionEvaluator, SharedRowPredicate};
use std::sync::Arc;
use uqa_sql::{plan::QueryBlockPlan, semantics::sets::SetFunctionCatalog, SQLError, SQLParam};

/// Bind scoped expression services without exposing the owning session or storage state.
pub trait QueryExpressionFactory<S: Clone + 'static>: Sync {
    fn production_resources(&self) -> Result<uqa_core::memory::OwnedProductionControl, SQLError>;
    fn bind_scope(&self, scope: &CteScope<S>)
        -> Result<Arc<dyn SetFunctionRuntime + '_>, SQLError>;
    /// Apply the owning planner to a validated schema/procedural execution copy.
    fn optimize_catalog_scalar(&self, expression: &mut ScalarExpr) -> Result<(), SQLError>;
    fn optimize_owned_catalog_scalar(
        &self,
        expression: uqa_sql::plan::OwnedScalarExpr,
        control: &uqa_core::memory::ProductionControl<'_>,
    ) -> Result<uqa_sql::plan::OwnedScalarExpr, SQLError>;
    fn prepare_predicate<'a>(
        &'a self,
        expression: &ScalarExpr,
        params: &'a [SQLParam],
        scope: &CteScope<S>,
    ) -> Result<Option<SharedRowPredicate<'a>>, SQLError>;
}

/// Attach the locking boundary using the caller's relation and transaction lock services.
pub trait RowLockOperatorFactory<S: Clone + 'static>: Sync {
    /// Accept ownership of the input, including closing it before returning a
    /// construction error. Successful construction transfers it to the result.
    fn attach_lock_rows<'a>(
        &'a self,
        operator: Box<dyn PhysicalOperator + 'a>,
        statement: &QueryBlockPlan,
        params: &'a [SQLParam],
        scope: &CteScope<S>,
        max_rows: Option<u64>,
        recheck: Option<LockRowsRecheckInput<'_, S>>,
    ) -> Result<Box<dyn PhysicalOperator + 'a>, SQLError>;
}

#[derive(Clone)]
pub struct RelationalContext<'a, S: Clone + 'static> {
    pub catalog: &'a dyn SetFunctionCatalog,
    pub expressions: &'a dyn QueryExpressionFactory<S>,
    pub row_locks: &'a dyn RowLockOperatorFactory<S>,
    pub runtime: QueryRuntimeView<'a>,
}

impl<S: Clone + 'static> Copy for RelationalContext<'_, S> {}

impl<'a, S: Clone + 'static> RelationalContext<'a, S> {
    pub fn expression_scope(
        self,
        scope: &CteScope<S>,
    ) -> Result<Arc<dyn SetFunctionRuntime + 'a>, SQLError> {
        self.expressions.bind_scope(scope)
    }

    pub fn evaluator(
        self,
        params: &'a [SQLParam],
        scope: &CteScope<S>,
    ) -> Result<SharedExpressionEvaluator<'a>, SQLError> {
        let resources = self.expressions.production_resources()?;
        crate::query::expression::ScopedExpressionEvaluator::shared_with_control(
            self.expression_scope(scope)?,
            params,
            self.runtime.cancellation_token(),
            &resources.control(),
        )
    }
}

pub fn build_set_projection<'a, S: Clone + 'static>(
    operator: Box<dyn PhysicalOperator + 'a>,
    context: RelationalContext<'a, S>,
    params: &'a [SQLParam],
    ctes: &CteScope<S>,
    evaluator: SharedExpressionEvaluator<'a>,
    output: SetProjectionOutput,
) -> Result<Box<dyn PhysicalOperator + 'a>, SQLError> {
    let (operator, (work_mem, scope)) =
        crate::physical::construction::OperatorBuild::run(operator, |_| {
            Ok((
                context.runtime.work_mem_bytes()?,
                context.expression_scope(ctes)?,
            ))
        })?;
    crate::query::set_projection::build_set_projection(
        operator,
        context.catalog,
        scope,
        params,
        evaluator,
        work_mem,
        output,
    )
}

pub fn attach_lock_rows<'a, S: Clone + 'static>(
    context: RelationalContext<'a, S>,
    operator: Box<dyn PhysicalOperator + 'a>,
    statement: &QueryBlockPlan,
    params: &'a [SQLParam],
    ctes: &CteScope<S>,
    max_rows: Option<u64>,
    recheck: Option<LockRowsRecheckInput<'_, S>>,
) -> Result<Box<dyn PhysicalOperator + 'a>, SQLError> {
    context
        .row_locks
        .attach_lock_rows(operator, statement, params, ctes, max_rows, recheck)
}