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    fn column_prune_with_filter(
29        &self,
30        statement: &QueryBlockPlan,
31        source: &SourcePlan,
32        filter: Option<&ScalarExpr>,
33        scope: &CteScope<S>,
34        schema: Option<&crate::RowSchema>,
35    ) -> Result<Option<ColumnPrune>, SQLError>;
36    fn column_prune(
37        &self,
38        statement: &QueryBlockPlan,
39        source: &SourcePlan,
40        scope: &CteScope<S>,
41        schema: Option<&crate::RowSchema>,
42    ) -> Result<Option<ColumnPrune>, SQLError>;
43    fn qualifier_filters(
44        &self,
45        statement: &QueryBlockPlan,
46        source: &SourcePlan,
47        scope: &CteScope<S>,
48    ) -> Result<Option<QualifierFilters>, SQLError>;
49    fn residual_filter(
50        &self,
51        statement: &QueryBlockPlan,
52        source: &SourcePlan,
53        filters: Option<&QualifierFilters>,
54        scope: &CteScope<S>,
55    ) -> Result<Option<ScalarExpr>, SQLError>;
56    fn propagated_join_filters(
57        &self,
58        filters: &QualifierFilters,
59        source: &SourcePlan,
60        target: &SourcePlan,
61        on: Option<&ScalarExpr>,
62    ) -> Option<QualifierFilters>;
63}
64
65pub type ForeignSourceRows<'a> = Box<dyn Iterator<Item = Result<ResultRow, String>> + Send + 'a>;
66
67/// A foreign table scan bound to the caller's catalog generation and FDW registrations.
68pub trait ForeignTableScan: Sync {
69    fn scan_foreign_source(
70        &self,
71        name: &str,
72        filter: Option<&ScalarExpr>,
73        params: &[SQLParam],
74    ) -> Result<ForeignSourceRows<'_>, String>;
75}
76
77#[derive(Clone)]
78pub struct SourceContext<'a, S: Clone + 'static> {
79    pub relational: RelationalContext<'a, S>,
80    pub ctes: CteExecutionContext<'a, S>,
81    pub scans: TableScanContext<'a>,
82    pub retrieval: TableRetrievalContext<'a>,
83    pub locking: RowLockContext<'a, S>,
84    pub catalog: CatalogContext<'a>,
85    pub planning: &'a dyn SourcePlanning<S>,
86    pub foreign_tables: Option<&'a dyn ForeignTableScan>,
87    pub volatility: &'a (dyn VolatilityCatalog + Sync),
88    pub types: &'a dyn FunctionTypeResolver,
89    pub documents: &'a dyn crate::query::block::context::QueryDocumentRead,
90    pub relation_retrieval: &'a dyn crate::query::block::context::RelationRetrieval,
91    pub text_indexes: &'a (dyn uqa_sql::semantics::text_indexes::TextMatchCatalog + Sync),
92}
93impl<S: Clone + 'static> Copy for SourceContext<'_, S> {}
94
95impl<'a, S: Clone + 'static> SourceContext<'a, S> {
96    pub fn scan_foreign_source(
97        &self,
98        name: &str,
99        filter: Option<&ScalarExpr>,
100        params: &[SQLParam],
101    ) -> Result<ForeignSourceRows<'a>, String> {
102        self.foreign_tables
103            .ok_or_else(|| "FDW support is not available in this build".to_owned())?
104            .scan_foreign_source(name, filter, params)
105    }
106}