Skip to main content

uqa_engine/capabilities/
table_creation.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Bind table creation to active query generations and schema publication state.
8use crate::{session::StatementReadSnapshot, Engine};
9use uqa_core::DocId;
10use uqa_execution::mutation::publication::DocumentVectors;
11use uqa_execution::query::CteScope;
12use uqa_execution::schema::ctas::{
13    entry::{TableAsTransactions, TableAsWrite},
14    CreateTableAsContext, TableAsNamespace, TableAsPublication, TableAsQuerySource,
15};
16use uqa_execution::schema::table_creation::entry::{TableCreationTransactions, TableCreationWrite};
17use uqa_sql::catalog::errors::storage_error;
18use uqa_sql::{
19    ast::{ColumnDef, OnCommitAction, RelationPersistence},
20    plan::QueryPlan,
21    SQLError, SQLParam, SQLResult,
22};
23use uqa_storage::document_store::Document;
24impl Engine {
25    pub(crate) fn create_table_as_context<'a>(
26        &'a self,
27        analysis_scope: &'a CteScope<StatementReadSnapshot>,
28    ) -> CreateTableAsContext<'a, StatementReadSnapshot> {
29        CreateTableAsContext {
30            creation: self.relation_creation_context(),
31            analysis_scope,
32            routines: self,
33            queries: self,
34            namespace: self,
35            publication: self,
36            vectors: self,
37            notices: &self.runtime.notices,
38        }
39    }
40}
41impl TableAsTransactions<StatementReadSnapshot> for Engine {
42    fn explain_existing_target(
43        &self,
44        name: &str,
45        if_not_exists: bool,
46        persistence: RelationPersistence,
47    ) -> Result<bool, SQLError> {
48        let scope = super::query_scope::new_for_current_routine(self);
49        uqa_execution::schema::ctas::explain_existing_target(
50            &self.create_table_as_context(&scope),
51            name,
52            if_not_exists,
53            persistence,
54        )
55    }
56    fn transaction_is_active(&self) -> bool {
57        self.transaction_depth() != 0
58    }
59    fn with_new_transaction(
60        &self,
61        write: TableAsWrite<'_, StatementReadSnapshot>,
62    ) -> Result<SQLResult, SQLError> {
63        self.transaction(|engine| engine.with_current_scope(write))
64    }
65    fn with_current_scope(
66        &self,
67        write: TableAsWrite<'_, StatementReadSnapshot>,
68    ) -> Result<SQLResult, SQLError> {
69        let scope = super::query_scope::new_for_current_routine(self);
70        write(&self.create_table_as_context(&scope))
71    }
72}
73impl TableCreationTransactions for Engine {
74    fn with_new_table_transaction(
75        &self,
76        write: TableCreationWrite<'_>,
77    ) -> Result<SQLResult, SQLError> {
78        self.transaction(|engine| {
79            let result = write(&engine.create_table_context())?;
80            engine.publish_catalog_constraint_tuples()?;
81            Ok(result)
82        })
83    }
84}
85impl TableAsQuerySource for Engine {
86    fn optimize(&self, plan: &QueryPlan) -> Result<QueryPlan, SQLError> {
87        crate::capabilities::statement_planning::optimize_engine_query(self, plan)
88    }
89    fn execute(
90        &self,
91        plan: &QueryPlan,
92        params: &[SQLParam],
93        measurement: Option<&uqa_execution::query::measurement::QueryMeasurement>,
94    ) -> Result<SQLResult, SQLError> {
95        let mut scope = super::query_scope::new_for_current_routine(self);
96        uqa_execution::query::statement::execute_query_plan_measured(
97            &self.query_execution_context(),
98            plan,
99            params,
100            &mut scope,
101            measurement,
102        )
103    }
104}
105impl TableAsNamespace for Engine {
106    fn relation_exists(&self, name: &str) -> Result<bool, SQLError> {
107        self.relation_kind_at(name)
108            .map(|kind| kind.is_some())
109            .map_err(|error| storage_error("CREATE TABLE AS", &error))
110    }
111
112    fn prepare_writer(&self) -> Result<bool, SQLError> {
113        self.prepare_explicit_transaction_writer()
114    }
115}
116impl TableAsPublication for Engine {
117    fn create_relation(
118        &self,
119        name: &str,
120        persistence: RelationPersistence,
121        on_commit: OnCommitAction,
122        owner: &uqa_execution::catalog::security::roles::locking::RoleBinding,
123    ) -> Result<(), SQLError> {
124        self.create_table_with_lifecycle(
125            name,
126            uqa_analysis::analyzer::standard_analyzer("english"),
127            Vec::new(),
128            persistence,
129            on_commit,
130            owner,
131            None,
132        )
133        .map_err(|error| storage_error("CREATE TABLE AS", &error))
134    }
135    fn create_vector_field(
136        &self,
137        name: &str,
138        column: &str,
139        dimensions: u32,
140    ) -> Result<bool, SQLError> {
141        self.install_vector_field(
142            name,
143            column.into(),
144            dimensions,
145            uqa_storage::VectorIndexSpec::BruteForce,
146            false,
147            true,
148        )
149        .map_err(|error| storage_error("CREATE TABLE AS vector field", &error))
150    }
151    fn publish_columns(&self, name: &str, columns: &[ColumnDef]) -> Result<(), SQLError> {
152        let constraints = self
153            .try_declared_table_constraints(name)
154            .map_err(|error| storage_error("CREATE TABLE AS schema", &error))?;
155        uqa_execution::schema::publication::replace_constraint_state(
156            &self.schema_publication_context(),
157            name,
158            columns.to_vec(),
159            constraints,
160        )
161        .map_err(|error| storage_error("CREATE TABLE AS schema", &error))
162    }
163    fn insert_document(
164        &self,
165        table: &str,
166        id: DocId,
167        document: Document,
168        vectors: DocumentVectors,
169    ) -> Result<(), SQLError> {
170        self.add_document_with_vector_values_inner(
171            table,
172            id,
173            document,
174            vectors,
175            uqa_execution::mutation::publication::InsertedIdentity::Unused,
176        )
177    }
178}
179
180impl Engine {
181    pub(crate) fn table_declaration_context(
182        &self,
183    ) -> uqa_sql::schema::table_creation::declaration::CreateTableAnalysisContext<'_> {
184        uqa_sql::schema::table_creation::declaration::CreateTableAnalysisContext {
185            types: self,
186            schema: self,
187            bindings: self,
188            inheritance: uqa_sql::schema::inheritance::InheritanceContext {
189                catalog: self,
190                partitions: self.partition_context(),
191                roles: self,
192            },
193            index_names: self,
194            foreign_keys: self.foreign_key_definition_context(),
195        }
196    }
197}
198
199impl Engine {
200    pub(crate) fn create_table_context(
201        &self,
202    ) -> uqa_execution::schema::table_creation::CreateTableContext<'_> {
203        let runtime = self.query_runtime_view();
204        uqa_execution::schema::table_creation::CreateTableContext {
205            creation: self.relation_creation_context(),
206            namespace: self,
207            analysis: self.table_declaration_context(),
208            sequences: self.implicit_sequence_context(),
209            ownership: self.implicit_ownership_context(),
210            schema_transactions: self,
211            publication: self,
212            identities: self.catalog_identity_reservation_context(),
213            notices: runtime.notices,
214        }
215    }
216}
217impl uqa_execution::schema::table_creation::TableCreationNamespace for Engine {
218    fn prepare_writer(&self) -> Result<bool, SQLError> {
219        self.prepare_explicit_transaction_writer()
220    }
221
222    fn relation_exists(&self, name: &str) -> Result<bool, SQLError> {
223        self.resolve_bound_relation_kind(name)
224            .map(|resolution| matches!(resolution, super::RelationResolution::Found(_, _)))
225    }
226}
227impl uqa_execution::schema::table_creation::TableCreationPublication for Engine {
228    fn create_table(
229        &self,
230        name: &str,
231        persistence: RelationPersistence,
232        on_commit: OnCommitAction,
233        owner: &uqa_execution::catalog::security::roles::locking::RoleBinding,
234        catalog_oids: uqa_sql::catalog::relation_oids::RelationCatalogOids,
235    ) -> uqa_storage::StorageBackendResult<()> {
236        self.create_table_with_lifecycle(
237            name,
238            uqa_analysis::analyzer::standard_analyzer("english"),
239            Vec::new(),
240            persistence,
241            on_commit,
242            owner,
243            Some(catalog_oids),
244        )
245    }
246    fn create_vector_field(
247        &self,
248        table: &str,
249        field: String,
250        dimensions: u32,
251    ) -> uqa_storage::StorageBackendResult<bool> {
252        self.install_vector_field(
253            table,
254            field,
255            dimensions,
256            uqa_storage::VectorIndexSpec::BruteForce,
257            false,
258            true,
259        )
260    }
261    fn install_hierarchy(
262        &self,
263        table: &str,
264        hierarchy: uqa_sql::ast::TableHierarchy,
265    ) -> uqa_storage::StorageBackendResult<()> {
266        self.install_table_hierarchy(table, hierarchy)
267    }
268    fn validate_default_partition_rows(
269        &self,
270        parent: &str,
271        bound: &uqa_sql::ast::PartitionBound,
272    ) -> Result<(), SQLError> {
273        uqa_execution::schema::hierarchy::validate_default_partition_exclusion(
274            &self.hierarchy_execution_context(),
275            parent,
276            bound,
277        )
278    }
279    fn persist_schema(&self, table: &str) -> uqa_storage::StorageBackendResult<bool> {
280        self.try_persist_table_schema(table)
281    }
282    fn refresh_value_indexes(&self, table: &str) -> uqa_storage::StorageBackendResult<()> {
283        self.refresh_value_indexes_for_table(table)
284    }
285}