Skip to main content

uqa_execution/statement/
prepared.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Prepared registration ordered around retained session registry publication.
8
9pub mod invalidation;
10
11use std::sync::Arc;
12use uqa_sql::{
13    plan::{AggregateClassifier, UnifiedPlan},
14    prepared::{definition::PreparedDefinitionContext, entry::PreparedStatementPlan},
15    ColumnType, SQLError, Statement,
16};
17
18pub trait PreparedDefinitionWrite {
19    fn insert(&mut self, name: String, definition: PreparedStatementPlan);
20}
21
22pub trait PreparedDefinitionRegistry {
23    fn write_definitions(&self) -> Box<dyn PreparedDefinitionWrite + '_>;
24}
25
26#[derive(Clone, Copy)]
27pub struct PreparedRegistrationContext<'a> {
28    pub analysis: PreparedDefinitionContext<'a>,
29    pub aggregates: &'a dyn AggregateClassifier,
30    pub registry: &'a dyn PreparedDefinitionRegistry,
31    /// The session's active transaction clock, including direct host registration; `None` keeps the caller's clock.
32    pub transaction_timestamp_micros: Option<i64>,
33    pub date_order: Option<uqa_core::TemporalDateOrder>,
34    pub interval_style: Option<uqa_core::TemporalIntervalStyle>,
35    /// The session's cancellation, which the definition's analysis observes.
36    pub cancellation: &'a uqa_core::CancellationToken,
37    pub clock: fn() -> i64,
38}
39
40pub fn register_statement(
41    context: &PreparedRegistrationContext<'_>,
42    name: String,
43    statement: Statement,
44) -> Result<(), SQLError> {
45    let plan = UnifiedPlan::lower_with(statement, context.aggregates);
46    register_plan(context, name, plan, &[], None)
47}
48
49pub fn register_plan(
50    context: &PreparedRegistrationContext<'_>,
51    name: String,
52    logical_plan: UnifiedPlan,
53    declared: &[ColumnType],
54    source_sql: Option<&str>,
55) -> Result<(), SQLError> {
56    register_definition(
57        context,
58        name,
59        logical_plan,
60        declared,
61        source_sql,
62        source_sql.is_some(),
63    )
64}
65
66/// Parse a prepared message before selecting its analysis snapshot. Empty input remains an explicit native definition.
67pub fn parse_host_sql(
68    sql: &str,
69    settings: uqa_sql::parser::ParserSettings,
70    notices: &crate::query::NoticeQueue,
71    cancellation: &uqa_core::CancellationToken,
72) -> Result<Arc<Statement>, SQLError> {
73    cancellation.check()?;
74    let (statements, parser) =
75        uqa_sql::parser::with_settings(settings, || uqa_sql::parse_statements(sql));
76    for notice in parser.notices.iter() {
77        notices.push(notice.clone());
78    }
79    let mut statements = statements?;
80    if statements.len() > 1 {
81        return Err(SQLError::Routine {
82            sqlstate: "42601".into(),
83            message: "cannot insert multiple commands into a prepared statement".into(),
84        });
85    }
86    let statement = statements
87        .pop()
88        .map(|statement| statement.compile())
89        .transpose()?
90        .unwrap_or(Statement::Empty);
91    Ok(Arc::new(statement))
92}
93
94/// Analyze the parsed host definition in its admitted session boundary. Retain source text without marking it as SQL PREPARE.
95pub fn register_host_statement(
96    context: &PreparedRegistrationContext<'_>,
97    name: String,
98    statement: &Statement,
99    sql: &str,
100    declared: &[ColumnType],
101) -> Result<(), SQLError> {
102    let plan = UnifiedPlan::lower_with(statement.clone(), context.aggregates);
103    register_definition(context, name, plan, declared, Some(sql), false)
104}
105
106fn register_definition(
107    context: &PreparedRegistrationContext<'_>,
108    name: String,
109    logical_plan: UnifiedPlan,
110    declared: &[ColumnType],
111    source_sql: Option<&str>,
112    from_sql: bool,
113) -> Result<(), SQLError> {
114    let _statement_thread = super::thread_context::StatementThreadContext {
115        retained_rows: crate::query::sources::retained_source::RetainedRowContext::current(),
116        io: uqa_core::io_usage::IOContext::current(),
117        regex_cache: uqa_sql::expr::current_regex_cache(),
118        temporal_input: uqa_sql::expr::TemporalInputContext {
119            transaction_clock_micros: context
120                .transaction_timestamp_micros
121                .or_else(uqa_sql::expr::transaction_clock_micros),
122            interval_style: context
123                .interval_style
124                .unwrap_or_else(uqa_sql::expr::temporal_interval_style),
125            date_order: context
126                .date_order
127                .unwrap_or_else(uqa_sql::expr::temporal_date_order),
128        },
129        cancellation: Some(context.cancellation.clone()),
130    }
131    .enter();
132    let source_plan = Arc::new(logical_plan.clone());
133    let definition = uqa_sql::prepared::definition::analyze_definition(
134        &context.analysis,
135        logical_plan,
136        declared,
137    )?;
138    context.registry.write_definitions().insert(
139        name,
140        PreparedStatementPlan {
141            composite_inputs: definition.composite_inputs,
142            source_plan,
143            logical_plan: Arc::new(definition.logical_plan),
144            needs_analysis: false,
145            effective_search_path: definition.effective_search_path,
146            dependencies: definition.dependencies,
147            dependency_snapshot: definition.dependency_snapshot,
148            plan: None,
149            parameter_types: definition.parameter_types,
150            result_schema: definition.result_schema,
151            source_sql: source_sql.map(Arc::from),
152            prepared_at_micros: (context.clock)(),
153            from_sql,
154            generic_plans: 0,
155            custom_plans: 0,
156            generic_cost: None,
157            total_custom_cost: 0.0,
158        },
159    );
160    Ok(())
161}
162
163#[cfg(test)]
164mod tests;