Skip to main content

uqa_sql/prepared/
utility.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Session-owned utility descriptors and the distinction between analyzed and unplanned statements.
8
9use crate::{
10    plan::{CommandPlan, PlanRef, UnifiedPlan},
11    RowSchema, SQLError, Statement,
12};
13
14/// Read existing descriptors without executing a utility or advancing a portal.
15pub trait PreparedSessionMetadata {
16    fn show_result_schema(&self, name: &str) -> Result<RowSchema, SQLError>;
17    fn portal_result_schema(&self, name: &str) -> Option<RowSchema>;
18    fn prepared_result_schema(&self, name: &str) -> Option<RowSchema>;
19
20    fn show_result_schema_with_control(
21        &self,
22        name: &str,
23        control: &uqa_core::memory::ProductionControl<'_>,
24    ) -> Result<RowSchema, SQLError> {
25        control.check()?;
26        self.show_result_schema(name)
27    }
28    fn portal_result_schema_with_control(
29        &self,
30        name: &str,
31        control: &uqa_core::memory::ProductionControl<'_>,
32    ) -> Result<Option<RowSchema>, SQLError> {
33        control.check()?;
34        Ok(self.portal_result_schema(name))
35    }
36    fn prepared_result_schema_with_control(
37        &self,
38        name: &str,
39        control: &uqa_core::memory::ProductionControl<'_>,
40    ) -> Result<Option<RowSchema>, SQLError> {
41        control.check()?;
42        Ok(self.prepared_result_schema(name))
43    }
44}
45
46/// Utilities whose bodies undergo parse analysis also require a planning snapshot and cache revalidation. Other utilities retain their original result descriptor even when the session object used at execution changes.
47pub fn requires_analysis(plan: &UnifiedPlan) -> bool {
48    requires_analysis_ref(plan.into())
49}
50
51pub fn requires_analysis_ref(plan: PlanRef<'_>) -> bool {
52    match plan {
53        PlanRef::Query(_) => true,
54        PlanRef::Command(command) => matches!(
55            command,
56            CommandPlan::Insert(_)
57                | CommandPlan::Update(_)
58                | CommandPlan::Delete(_)
59                | CommandPlan::Merge(_)
60                | CommandPlan::Call { .. }
61                | CommandPlan::Explain { .. }
62                | CommandPlan::DeclareCursor { .. }
63                | CommandPlan::CreateTableAs { .. }
64                | CommandPlan::CreateMaterializedView { .. }
65        ),
66    }
67}
68
69pub fn statement_requires_analysis(statement: &Statement) -> bool {
70    matches!(
71        statement,
72        Statement::Select(_)
73            | Statement::Insert(_)
74            | Statement::Update(_)
75            | Statement::Delete(_)
76            | Statement::Merge(_)
77            | Statement::Call { .. }
78            | Statement::Explain { .. }
79            | Statement::DeclareCursor(_)
80            | Statement::CreateTableAs { .. }
81            | Statement::CreateMaterializedView { .. }
82    )
83}
84
85pub fn result_schema(
86    session: &dyn PreparedSessionMetadata,
87    plan: &UnifiedPlan,
88) -> Result<Option<RowSchema>, SQLError> {
89    let UnifiedPlan::Command(command) = plan else {
90        return Ok(None);
91    };
92    match command.as_ref() {
93        CommandPlan::ShowVariable { name } => session.show_result_schema(name).map(Some),
94        CommandPlan::FetchCursor(fetch) if !fetch.move_only => {
95            Ok(session.portal_result_schema(&fetch.name))
96        }
97        CommandPlan::Execute { name, .. } => Ok(session.prepared_result_schema(name)),
98        _ => Ok(None),
99    }
100}
101
102/// Observe utility metadata under the same allowance as its preparation; shared portal and prepared schemas retain their original owners.
103pub fn result_schema_with_control(
104    session: &dyn PreparedSessionMetadata,
105    plan: PlanRef<'_>,
106    control: &uqa_core::memory::ProductionControl<'_>,
107) -> Result<Option<RowSchema>, SQLError> {
108    control.check()?;
109    let PlanRef::Command(command) = plan else {
110        return Ok(None);
111    };
112    match command {
113        CommandPlan::ShowVariable { name } => session
114            .show_result_schema_with_control(name, control)
115            .map(Some),
116        CommandPlan::FetchCursor(fetch) if !fetch.move_only => {
117            session.portal_result_schema_with_control(&fetch.name, control)
118        }
119        CommandPlan::Execute { name, .. } => {
120            session.prepared_result_schema_with_control(name, control)
121        }
122        _ => Ok(None),
123    }
124}