Skip to main content

uqa_execution/query/sources/
context.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Inputs for source planning, scans, expression binding, and nested query execution.
8
9use crate::query::{
10    cte::context::CteExecutionContext,
11    locking::context::RowLockContext,
12    relational::RelationalContext,
13    table_sources::{TableRetrievalContext, TableScanContext},
14    CteScope,
15};
16use crate::{catalog::context::CatalogContext, FunctionTypeResolver};
17use uqa_sql::{
18    plan::{
19        source_projection::{ColumnPrune, QualifierFilters},
20        QueryBlockPlan, SourcePlan,
21    },
22    semantics::volatility::VolatilityCatalog,
23    ResultRow, SQLError, SQLParam, ScalarExpr,
24};
25
26/// Planner decisions needed when a parameterized source is assembled for execution.
27pub trait SourcePlanning<S: Clone>: Sync {
28    /// Whether the planner removes this source's physical scan. The default keeps initialization for planners without this proof.
29    fn source_is_empty(&self, _source: &SourcePlan) -> bool {
30        false
31    }
32    /// Whether a block keeps its output operators but removes its FROM input.
33    fn block_input_is_empty(&self, _statement: &QueryBlockPlan) -> bool {
34        false
35    }
36    /// Whether an outer join removes one matching input while retaining its preserved side.
37    fn join_input_is_empty(&self, _join: &SourcePlan, _right: bool) -> bool {
38        false
39    }
40    fn column_prune_with_filter(
41        &self,
42        statement: &QueryBlockPlan,
43        source: &SourcePlan,
44        filter: Option<&ScalarExpr>,
45        scope: &CteScope<S>,
46        schema: Option<&crate::RowSchema>,
47    ) -> Result<Option<ColumnPrune>, SQLError>;
48    fn column_prune(
49        &self,
50        statement: &QueryBlockPlan,
51        source: &SourcePlan,
52        scope: &CteScope<S>,
53        schema: Option<&crate::RowSchema>,
54    ) -> Result<Option<ColumnPrune>, SQLError>;
55    fn qualifier_filters(
56        &self,
57        statement: &QueryBlockPlan,
58        source: &SourcePlan,
59        scope: &CteScope<S>,
60    ) -> Result<Option<QualifierFilters>, SQLError>;
61    fn residual_filter(
62        &self,
63        statement: &QueryBlockPlan,
64        source: &SourcePlan,
65        filters: Option<&QualifierFilters>,
66        scope: &CteScope<S>,
67    ) -> Result<Option<uqa_sql::plan::OwnedScalarExpr>, SQLError>;
68    fn propagated_join_filters(
69        &self,
70        filters: &QualifierFilters,
71        source: &SourcePlan,
72        target: &SourcePlan,
73        on: Option<&ScalarExpr>,
74    ) -> Result<Option<QualifierFilters>, SQLError>;
75}
76
77pub type ForeignSourceRows<'a> = Box<dyn Iterator<Item = Result<ResultRow, String>> + Send + 'a>;
78
79/// A foreign table scan bound to the caller's catalog generation and FDW registrations.
80pub trait ForeignTableScan: Sync {
81    fn scan_foreign_source(
82        &self,
83        name: &str,
84        filter: Option<&ScalarExpr>,
85        params: &[SQLParam],
86    ) -> Result<ForeignSourceRows<'_>, String>;
87}
88
89#[derive(Clone)]
90pub struct SourceContext<'a, S: Clone + 'static> {
91    pub relational: RelationalContext<'a, S>,
92    pub ctes: CteExecutionContext<'a, S>,
93    pub scans: TableScanContext<'a>,
94    pub retrieval: TableRetrievalContext<'a>,
95    pub locking: RowLockContext<'a, S>,
96    pub catalog: CatalogContext<'a>,
97    pub planning: &'a dyn SourcePlanning<S>,
98    pub foreign_tables: Option<&'a dyn ForeignTableScan>,
99    pub volatility: &'a (dyn VolatilityCatalog + Sync),
100    pub types: &'a dyn FunctionTypeResolver,
101    pub documents: &'a dyn crate::query::block::context::QueryDocumentRead,
102    pub relation_retrieval: &'a dyn crate::query::block::context::RelationRetrieval,
103    pub text_indexes: &'a (dyn uqa_sql::semantics::text_indexes::TextMatchCatalog + Sync),
104}
105impl<S: Clone + 'static> Copy for SourceContext<'_, S> {}
106
107impl<'a, S: Clone + 'static> SourceContext<'a, S> {
108    pub fn scan_foreign_source(
109        &self,
110        name: &str,
111        filter: Option<&ScalarExpr>,
112        params: &[SQLParam],
113    ) -> Result<ForeignSourceRows<'a>, String> {
114        self.foreign_tables
115            .ok_or_else(|| "FDW support is not available in this build".to_owned())?
116            .scan_foreign_source(name, filter, params)
117    }
118}