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<uqa_sql::plan::OwnedQueryPlan, SQLError> {
87        crate::capabilities::statement_planning::optimize_engine_query(
88            self,
89            std::borrow::Cow::Borrowed(plan),
90        )
91    }
92    fn execute(
93        &self,
94        plan: &QueryPlan,
95        params: &[SQLParam],
96        measurement: Option<&uqa_execution::query::measurement::QueryMeasurement>,
97    ) -> Result<SQLResult, SQLError> {
98        let mut scope = super::query_scope::new_for_current_routine(self)?;
99        uqa_execution::query::statement::execute_query_plan_measured(
100            &self.query_execution_context(),
101            plan,
102            params,
103            &mut scope,
104            measurement,
105        )
106    }
107}
108impl TableAsNamespace for Engine {
109    fn relation_exists(&self, name: &str) -> Result<bool, SQLError> {
110        self.relation_kind_at(name)
111            .map(|kind| kind.is_some())
112            .map_err(|error| storage_error("CREATE TABLE AS", &error))
113    }
114
115    fn prepare_writer(&self) -> Result<bool, SQLError> {
116        self.prepare_explicit_transaction_writer()
117    }
118}
119impl TableAsPublication for Engine {
120    fn create_relation(
121        &self,
122        name: &str,
123        persistence: RelationPersistence,
124        on_commit: OnCommitAction,
125        owner: &uqa_execution::catalog::security::roles::locking::RoleBinding,
126    ) -> Result<(), SQLError> {
127        self.create_table_with_lifecycle(
128            name,
129            uqa_analysis::analyzer::standard_analyzer("english"),
130            Vec::new(),
131            persistence,
132            on_commit,
133            owner,
134            None,
135        )
136        .map_err(|error| storage_error("CREATE TABLE AS", &error))
137    }
138    fn create_vector_field(
139        &self,
140        name: &str,
141        column: &str,
142        dimensions: u32,
143    ) -> Result<bool, SQLError> {
144        self.install_vector_field(
145            name,
146            column.into(),
147            dimensions,
148            uqa_storage::VectorIndexSpec::BruteForce,
149            false,
150            true,
151        )
152        .map_err(|error| storage_error("CREATE TABLE AS vector field", &error))
153    }
154    fn publish_columns(&self, name: &str, columns: &[ColumnDef]) -> Result<(), SQLError> {
155        let constraints = self
156            .try_declared_table_constraints(name)
157            .map_err(|error| storage_error("CREATE TABLE AS schema", &error))?;
158        uqa_execution::schema::publication::replace_constraint_state(
159            &self.schema_publication_context(),
160            name,
161            columns.to_vec(),
162            constraints,
163        )
164        .map_err(|error| storage_error("CREATE TABLE AS schema", &error))
165    }
166    fn insert_document(
167        &self,
168        table: &str,
169        id: DocId,
170        document: Document,
171        vectors: DocumentVectors,
172    ) -> Result<(), SQLError> {
173        self.add_document_with_vector_values_inner(
174            table,
175            id,
176            document,
177            vectors,
178            uqa_execution::mutation::publication::InsertedIdentity::Unused,
179        )
180    }
181}
182
183impl Engine {
184    pub(crate) fn table_declaration_context(
185        &self,
186    ) -> uqa_sql::schema::table_creation::declaration::CreateTableAnalysisContext<'_> {
187        uqa_sql::schema::table_creation::declaration::CreateTableAnalysisContext {
188            types: self,
189            schema: self,
190            bindings: self,
191            inheritance: uqa_sql::schema::inheritance::InheritanceContext {
192                catalog: self,
193                partitions: self.partition_context(),
194                roles: self,
195            },
196            index_names: self,
197            foreign_keys: self.foreign_key_definition_context(),
198        }
199    }
200}
201
202impl Engine {
203    pub(crate) fn create_table_context(
204        &self,
205    ) -> uqa_execution::schema::table_creation::CreateTableContext<'_> {
206        let runtime = self.query_runtime_view();
207        uqa_execution::schema::table_creation::CreateTableContext {
208            creation: self.relation_creation_context(),
209            namespace: self,
210            analysis: self.table_declaration_context(),
211            sequences: self.implicit_sequence_context(),
212            ownership: self.implicit_ownership_context(),
213            schema_transactions: self,
214            publication: self,
215            identities: self.catalog_identity_reservation_context(),
216            notices: runtime.notices,
217        }
218    }
219}
220impl uqa_execution::schema::table_creation::TableCreationNamespace for Engine {
221    fn prepare_writer(&self) -> Result<bool, SQLError> {
222        self.prepare_explicit_transaction_writer()
223    }
224
225    fn relation_exists(&self, name: &str) -> Result<bool, SQLError> {
226        self.resolve_bound_relation_kind(name)
227            .map(|resolution| matches!(resolution, super::RelationResolution::Found(_, _)))
228    }
229}
230impl uqa_execution::schema::table_creation::TableCreationPublication for Engine {
231    fn create_table(
232        &self,
233        name: &str,
234        persistence: RelationPersistence,
235        on_commit: OnCommitAction,
236        owner: &uqa_execution::catalog::security::roles::locking::RoleBinding,
237        catalog_oids: uqa_sql::catalog::relation_oids::RelationCatalogOids,
238    ) -> uqa_storage::StorageBackendResult<()> {
239        self.create_table_with_lifecycle(
240            name,
241            uqa_analysis::analyzer::standard_analyzer("english"),
242            Vec::new(),
243            persistence,
244            on_commit,
245            owner,
246            Some(catalog_oids),
247        )
248    }
249    fn create_vector_field(
250        &self,
251        table: &str,
252        field: String,
253        dimensions: u32,
254    ) -> uqa_storage::StorageBackendResult<bool> {
255        self.install_vector_field(
256            table,
257            field,
258            dimensions,
259            uqa_storage::VectorIndexSpec::BruteForce,
260            false,
261            true,
262        )
263    }
264    fn install_hierarchy(
265        &self,
266        table: &str,
267        hierarchy: uqa_sql::ast::TableHierarchy,
268    ) -> uqa_storage::StorageBackendResult<()> {
269        self.install_table_hierarchy(table, hierarchy)
270    }
271    fn validate_default_partition_rows(
272        &self,
273        parent: &str,
274        bound: &uqa_sql::ast::PartitionBound,
275    ) -> Result<(), SQLError> {
276        uqa_execution::schema::hierarchy::validate_default_partition_exclusion(
277            &self.hierarchy_execution_context(),
278            parent,
279            bound,
280        )
281    }
282    fn persist_schema(&self, table: &str) -> uqa_storage::StorageBackendResult<bool> {
283        self.try_persist_table_schema(table)
284    }
285    fn refresh_value_indexes(&self, table: &str) -> uqa_storage::StorageBackendResult<()> {
286        self.refresh_value_indexes_for_table(table)
287    }
288}