Skip to main content

uqa_sql/prepared/
entry.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Prepared plan identity, cached variants and catalog-visible metadata.
8
9use super::ownership::SharedPreparedInput;
10use std::sync::Arc;
11
12#[derive(Clone)]
13pub struct PreparedStatementPlan {
14    /// Stable registration identity, independent of executable storage and reanalysis. Weak host handles retain no admitted plan payload.
15    pub definition_identity: Arc<()>,
16    pub composite_inputs: super::composites::CompositeInputs,
17    /// Original input syntax, retained for parse analysis after invalidation.
18    pub source_plan: crate::plan::SharedExecutablePlan,
19    pub logical_plan: crate::plan::SharedExecutablePlan,
20    pub needs_analysis: bool,
21    /// The effective namespace of the retained analysis, when its catalog supplies one.
22    pub effective_search_path:
23        SharedPreparedInput<Option<crate::catalog::resolution::EffectiveSearchPath>>,
24    pub dependencies: SharedPreparedInput<super::dependencies::PreparedAnalysisDependencies>,
25    pub dependency_snapshot:
26        SharedPreparedInput<Option<super::dependencies::PreparedDependencySnapshot>>,
27    /// Immutable generic executable shared by the cache and its active executions.
28    pub plan: Option<crate::plan::SharedExecutablePlan>,
29    pub parameter_types: SharedPreparedInput<Vec<Option<crate::ast::ColumnType>>>,
30    pub result_schema: Option<crate::RowSchema>,
31    pub source_sql: Option<SharedPreparedInput<String>>,
32    pub prepared_at_micros: i64,
33    pub from_sql: bool,
34    pub generic_plans: i64,
35    pub custom_plans: i64,
36    pub generic_cost: Option<f64>,
37    pub total_custom_cost: f64,
38}
39
40use crate::catalog::session::PreparedStatementMetadata;
41
42impl PreparedStatementPlan {
43    pub fn metadata(&self, name: &str) -> PreparedStatementMetadata {
44        PreparedStatementMetadata {
45            name: name.to_string(),
46            parameter_types: self.parameter_types.to_vec(),
47            result_types: self
48                .result_schema
49                .as_ref()
50                .map(|schema| schema.column_types().to_vec()),
51            source_sql: self
52                .source_sql
53                .as_ref()
54                .map(|source| Arc::from(source.as_str())),
55            prepared_at_micros: self.prepared_at_micros,
56            from_sql: self.from_sql,
57            generic_plans: self.generic_plans,
58            custom_plans: self.custom_plans,
59        }
60    }
61}
62
63impl PreparedStatementPlan {
64    /// Publish successful descriptor reanalysis without counting a plan execution.
65    pub fn record_analysis<P: Into<crate::plan::SharedExecutablePlan>>(
66        &mut self,
67        definition: super::definition::PreparedDefinition<P>,
68    ) {
69        self.composite_inputs = definition.composite_inputs;
70        self.logical_plan = definition.logical_plan.into();
71        self.effective_search_path = definition.effective_search_path;
72        self.dependencies = definition.dependencies;
73        self.dependency_snapshot = definition.dependency_snapshot;
74        self.needs_analysis = false;
75        self.plan = None;
76        self.generic_cost = None;
77    }
78
79    pub fn invalidate(&mut self) {
80        if !super::utility::requires_analysis(&self.source_plan) {
81            return;
82        }
83        self.plan = None;
84        self.needs_analysis = true;
85    }
86
87    pub fn record_execution(&mut self, update: super::planning::PreparedPlanUpdate) {
88        self.composite_inputs = update.composite_inputs;
89        if let Some(analysis) = update.reanalyzed {
90            self.logical_plan = analysis.logical_plan;
91            self.effective_search_path = analysis.effective_search_path;
92            self.dependencies = analysis.dependencies;
93            self.dependency_snapshot = analysis.dependency_snapshot;
94            self.needs_analysis = false;
95        }
96        self.plan = update.generic_plan;
97        self.generic_cost = update.generic_cost;
98        if let Some(cost) = update.custom_cost {
99            self.total_custom_cost += cost;
100            self.custom_plans = self.custom_plans.saturating_add(1);
101        } else {
102            self.generic_plans = self.generic_plans.saturating_add(1);
103        }
104    }
105}
106
107mod reuse;