Skip to main content

uqa_sql/prepared/
definition.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Analyze prepared declarations with separate retained inference and descriptor scopes.
8
9use super::dependencies::{PreparedAnalysisDependencies, PreparedDependencySnapshot};
10use crate::{
11    binding::statements::{StatementAnalysisScopes, StatementBindingScope},
12    catalog::resolution::EffectiveSearchPath,
13    plan::UnifiedPlan,
14    routines::RoutineResolution,
15    ColumnType, FunctionTypeResolver, RowSchema, SQLError,
16};
17
18#[derive(Clone, Copy)]
19pub struct PreparedDefinitionContext<'a> {
20    pub types: &'a dyn FunctionTypeResolver,
21    pub routines: &'a dyn RoutineResolution,
22    pub procedures: &'a dyn crate::routines::resolution::RoutineOverloadCatalog,
23    pub scopes: &'a dyn StatementAnalysisScopes,
24    pub session: &'a dyn super::utility::PreparedSessionMetadata,
25    /// The catalog the `reg*` input functions read object names from when the statement is analyzed.
26    pub aliases: &'a dyn crate::schema::dependencies::oid_alias::OidAliasInput,
27}
28
29pub struct PreparedDefinition {
30    pub composite_inputs: super::composites::CompositeInputs,
31    pub logical_plan: UnifiedPlan,
32    pub parameter_types: Vec<Option<ColumnType>>,
33    pub result_schema: Option<RowSchema>,
34    pub effective_search_path: Option<EffectiveSearchPath>,
35    pub dependencies: PreparedAnalysisDependencies,
36    pub dependency_snapshot: Option<PreparedDependencySnapshot>,
37}
38
39pub fn analyze_definition(
40    context: &PreparedDefinitionContext<'_>,
41    mut logical_plan: UnifiedPlan,
42    declared: &[ColumnType],
43) -> Result<PreparedDefinition, SQLError> {
44    let parameter_types =
45        super::declared_parameter_types(context.types, &mut logical_plan, declared)?;
46    if !super::utility::requires_analysis(&logical_plan) {
47        let result_schema = super::utility::result_schema(context.session, &logical_plan)?;
48        return Ok(PreparedDefinition {
49            composite_inputs: super::composites::CompositeInputs::default(),
50            logical_plan,
51            parameter_types,
52            result_schema,
53            effective_search_path: None,
54            dependencies: PreparedAnalysisDependencies::default(),
55            dependency_snapshot: None,
56        });
57    }
58    let (input, effective_search_path, dependency_snapshot) = with_scope_result(
59        context.scopes,
60        |scope| {
61            let binding = scope.binding_context()?;
62            let mut input = if matches!(&logical_plan, UnifiedPlan::Command(command) if matches!(command.as_ref(), crate::plan::CommandPlan::Call { .. }))
63            {
64                let (_, input) = crate::binding::read_procedure_inputs(
65                    &crate::binding::statements::StatementAnalysisContext {
66                        routines: context.routines,
67                        scopes: context.scopes,
68                        aliases: context.aliases,
69                    },
70                    &crate::routines::resolution::RoutineOverloadContext {
71                        catalog: context.procedures,
72                    },
73                    context.procedures,
74                    &mut logical_plan,
75                    &parameter_types,
76                    &binding,
77                )?;
78                crate::binding::retain_prepared_input_metadata(
79                    context.routines,
80                    &mut logical_plan,
81                    &input.parameter_types,
82                    &binding,
83                )?;
84                input
85            } else {
86                crate::binding::read_prepared_inputs(
87                    context.routines,
88                    &mut logical_plan,
89                    &parameter_types,
90                    &binding,
91                    Some(context.aliases),
92                )?
93            };
94            crate::schema::dependencies::oid_alias::read_prepared_oid_alias_constants(
95                context.aliases,
96                &mut logical_plan,
97            )?;
98            logical_plan.visit_scalar_expressions(&mut |expression| {
99                input.dependencies.include_expression(expression);
100            });
101            let effective_search_path =
102                binding.catalog.effective_search_path(&binding.resolution)?;
103            let dependency_snapshot = binding
104                .catalog
105                .prepared_dependency_snapshot(&input.dependencies)?;
106            Ok((input, effective_search_path, dependency_snapshot))
107        },
108    )?;
109    let result_schema = analyze_result_schema(context, &logical_plan, &input.parameter_types)?;
110    Ok(PreparedDefinition {
111        composite_inputs: super::composites::CompositeInputs::capture(
112            &logical_plan,
113            context.types,
114        )?,
115        logical_plan,
116        parameter_types: input.parameter_types,
117        result_schema,
118        effective_search_path,
119        dependencies: input.dependencies,
120        dependency_snapshot,
121    })
122}
123
124/// Check analysis dependencies in one retained namespace. Catalogs that supplied no path or revision capability at analysis leave that part of freshness to their owner's invalidation events.
125pub fn analysis_is_current(
126    context: &PreparedDefinitionContext<'_>,
127    retained_path: Option<&EffectiveSearchPath>,
128    dependencies: &PreparedAnalysisDependencies,
129    retained_snapshot: Option<&PreparedDependencySnapshot>,
130) -> Result<bool, SQLError> {
131    if retained_path.is_none() && retained_snapshot.is_none() {
132        return Ok(true);
133    }
134    with_scope_result(context.scopes, |scope| {
135        let binding = scope.binding_context()?;
136        if let Some(path) = retained_path {
137            if binding
138                .catalog
139                .effective_search_path(&binding.resolution)?
140                .as_ref()
141                != Some(path)
142            {
143                return Ok(false);
144            }
145        }
146        match retained_snapshot {
147            Some(snapshot) => Ok(binding
148                .catalog
149                .prepared_dependency_snapshot(dependencies)?
150                .as_ref()
151                == Some(snapshot)),
152            None => Ok(true),
153        }
154    })
155}
156
157/// Read the live namespace through one retained binding scope before selecting a previously analyzed prepared statement.
158pub fn effective_search_path(
159    context: &PreparedDefinitionContext<'_>,
160) -> Result<Option<EffectiveSearchPath>, SQLError> {
161    with_scope_result(context.scopes, |scope| {
162        let binding = scope.binding_context()?;
163        binding.catalog.effective_search_path(&binding.resolution)
164    })
165}
166
167pub fn analyze_result_schema(
168    context: &PreparedDefinitionContext<'_>,
169    logical_plan: &UnifiedPlan,
170    parameter_types: &[Option<ColumnType>],
171) -> Result<Option<RowSchema>, SQLError> {
172    if !super::utility::requires_analysis(logical_plan) {
173        return super::utility::result_schema(context.session, logical_plan);
174    }
175    with_scope_result(context.scopes, |scope| {
176        let binding = scope.binding_context()?;
177        if let UnifiedPlan::Command(command) = logical_plan {
178            if let crate::plan::CommandPlan::Call { name, args } = command.as_ref() {
179                let params = super::analysis_parameters(parameter_types);
180                return crate::routines::call::ProcedureCallAnalysis::new(args)?.result_schema(
181                    name,
182                    &crate::routines::resolution::RoutineOverloadContext {
183                        catalog: context.procedures,
184                    },
185                    context.procedures,
186                    &mut |argument| {
187                        crate::binding::analyze_expression_plan_type(
188                            context.routines,
189                            argument,
190                            &params,
191                            &binding,
192                        )
193                    },
194                );
195            }
196        }
197        super::analyze_prepared_plan(context.routines, logical_plan, parameter_types, &binding)
198    })
199}
200
201fn with_scope_result<T>(
202    scopes: &dyn StatementAnalysisScopes,
203    mut analyze: impl FnMut(&dyn StatementBindingScope) -> Result<T, SQLError>,
204) -> Result<T, SQLError> {
205    let mut result = None;
206    scopes.with_scope(&mut |scope| {
207        result = Some(analyze(scope)?);
208        Ok(())
209    })?;
210    result.ok_or_else(|| {
211        SQLError::Internal("prepared analysis scope did not invoke its operation".into())
212    })
213}
214
215#[cfg(test)]
216mod tests;