Skip to main content

uqa_engine/capabilities/
maintenance.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Bind maintenance to retained table generations, session locks and provider transactions.
8use crate::{Engine, TableState};
9use std::{
10    collections::BTreeSet,
11    sync::{atomic::Ordering, Arc},
12};
13use uqa_core::DocId;
14use uqa_execution::{
15    maintenance::analyze::{
16        AnalyzeCatalog, AnalyzeContext, AnalyzeLocks, AnalyzeNotices, AnalyzeTarget,
17    },
18    maintenance::{
19        VacuumContext, VacuumDocuments, VacuumLocks, VacuumRelations, VacuumRows, VacuumStatistics,
20        VacuumStatisticsRefresh, VacuumStorage, VacuumTable, VacuumTransactions,
21        VacuumVectorIndexes, VacuumWrite,
22    },
23    mutation::publication::DocumentVectors,
24};
25use uqa_sql::{
26    ast::RelationPersistence,
27    catalog::security::table::TableAclPrivilege,
28    maintenance::{VacuumCatalog, VacuumPrivileges, VacuumRelation},
29    SQLError,
30};
31use uqa_storage::{document_store::Document, StorageBackendResult, StoredDocument};
32impl Engine {
33    pub(crate) fn analyze_execution_context(&self, check_privileges: bool) -> AnalyzeContext<'_> {
34        AnalyzeContext {
35            catalog: self,
36            locks: self,
37            notices: self,
38            privileges: check_privileges.then_some(self),
39        }
40    }
41
42    pub(crate) fn vacuum_execution_context(&self) -> VacuumContext<'_> {
43        VacuumContext {
44            catalog: self,
45            privileges: self,
46            relations: self,
47            locks: self,
48            storage: self,
49            rows: self,
50            statistics: self,
51            transactions: self,
52        }
53    }
54}
55
56impl AnalyzeCatalog for Engine {
57    fn resolve(&self, name: &str) -> Result<Option<AnalyzeTarget>, SQLError> {
58        let Some(name) = self.try_resolve_table_name(name).map_err(|error| {
59            uqa_sql::catalog::errors::storage_error("resolve ANALYZE target", &error)
60        })?
61        else {
62            return Ok(None);
63        };
64        self.try_table(&name)
65            .map(|table| {
66                table.map(|table| AnalyzeTarget {
67                    name,
68                    object_id: table.object_id(),
69                })
70            })
71            .map_err(|error| uqa_sql::catalog::errors::storage_error("read ANALYZE target", &error))
72    }
73
74    fn all_tables(&self) -> Vec<AnalyzeTarget> {
75        self.storage
76            .tables
77            .read()
78            .iter()
79            .map(|(name, table)| AnalyzeTarget {
80                name: name.qualified_name(),
81                object_id: table.object_id(),
82            })
83            .collect()
84    }
85
86    fn current_target(&self, object_id: [u8; 16]) -> Option<AnalyzeTarget> {
87        self.storage.tables.read().iter().find_map(|(name, table)| {
88            (table.object_id() == object_id).then(|| AnalyzeTarget {
89                name: name.qualified_name(),
90                object_id,
91            })
92        })
93    }
94
95    fn descendants(&self, name: &str) -> Result<Vec<String>, SQLError> {
96        self.hierarchy_scan_tables(name, true)
97    }
98}
99
100impl AnalyzeLocks for Engine {
101    fn bind_name(&self, name: &str) -> Result<crate::row_locks::ScopedRelationLock<'_>, SQLError> {
102        self.temporary_relation_lock(name, crate::row_locks::RelationLockMode::AccessShare)
103    }
104
105    fn acquire(
106        &self,
107        name: &str,
108        mode: crate::row_locks::RelationLockMode,
109    ) -> Result<(), SQLError> {
110        self.prepare_transaction_lock_wait()?;
111        self.lock_relation(name, mode)
112    }
113
114    fn refresh_after_wait(&self) -> Result<(), SQLError> {
115        self.refresh_explicit_statement_snapshot()
116    }
117}
118
119impl AnalyzeNotices for Engine {
120    fn notice(&self, notice: uqa_sql::SQLNotice) {
121        self.push_sql_notice(notice);
122    }
123}
124struct VacuumMetadata(Arc<TableState>);
125impl VacuumRelation for VacuumMetadata {
126    fn column_names(&self) -> BTreeSet<String> {
127        self.0
128            .columns
129            .read()
130            .iter()
131            .map(|column| column.name.clone())
132            .collect()
133    }
134}
135impl VacuumCatalog for Engine {
136    fn resolve_relation_kind(
137        &self,
138        name: &str,
139    ) -> Result<Option<(String, &'static str)>, SQLError> {
140        self.try_resolve_visible_relation_kind(name)
141    }
142    fn require_table(&self, name: &str) -> Result<Box<dyn VacuumRelation + '_>, SQLError> {
143        Engine::require_table(self, name)
144            .map(|state| Box::new(VacuumMetadata(state)) as Box<dyn VacuumRelation>)
145    }
146}
147impl VacuumPrivileges for Engine {
148    fn ensure_maintain(&self, table: &str) -> Result<(), SQLError> {
149        self.ensure_table_privilege(table, TableAclPrivilege::Maintain)
150    }
151}
152struct VacuumTableBinding<'a> {
153    engine: &'a Engine,
154    table: Arc<TableState>,
155}
156struct SavedVacuumStatistics<'a> {
157    engine: &'a Engine,
158    table: &'a TableState,
159    statistics: uqa_planner::ColumnStatistics,
160    loaded: bool,
161    dirty: bool,
162}
163impl VacuumStatistics for SavedVacuumStatistics<'_> {
164    fn loaded(&self) -> bool {
165        self.loaded
166    }
167    fn dirty(&self) -> bool {
168        self.dirty
169    }
170    fn restore(&self) {
171        *self.table.column_stats.write() = self.statistics.clone();
172        self.table
173            .column_stats_loaded
174            .store(self.loaded, Ordering::Release);
175        self.table
176            .column_stats_dirty
177            .store(self.dirty, Ordering::Release);
178    }
179    fn persist(&self, table: &str) -> StorageBackendResult<()> {
180        if let Some(catalog) = self.engine.storage.catalog.as_ref() {
181            Engine::persist_column_stats(
182                catalog.as_ref(),
183                table,
184                &self.statistics,
185                self.table.object_id(),
186                self.statistics
187                    .values()
188                    .next()
189                    .map_or(0, |stats| stats.row_count),
190                // Statistics saved from before are no new sample.
191                None,
192            )?;
193        }
194        Ok(())
195    }
196}
197impl VacuumRelations for Engine {
198    fn require_table(&self, name: &str) -> Result<Box<dyn VacuumTable + '_>, SQLError> {
199        Engine::require_table(self, name).map(|table| {
200            Box::new(VacuumTableBinding {
201                engine: self,
202                table,
203            }) as Box<dyn VacuumTable>
204        })
205    }
206    fn scan_tables(&self, name: &str, descendants: bool) -> Result<Vec<String>, SQLError> {
207        self.hierarchy_scan_tables(name, descendants)
208    }
209}
210impl VacuumTable for VacuumTableBinding<'_> {
211    fn statistics(&self) -> Box<dyn VacuumStatistics + '_> {
212        let statistics = self.table.column_stats.read().clone();
213        let loaded = self.table.column_stats_loaded.load(Ordering::Acquire);
214        let dirty = self.table.column_stats_dirty.load(Ordering::Acquire);
215        Box::new(SavedVacuumStatistics {
216            engine: self.engine,
217            table: &self.table,
218            statistics,
219            loaded,
220            dirty,
221        })
222    }
223    fn documents(&self) -> VacuumDocuments<'_> {
224        Box::new(self.table.document_store.read())
225    }
226    fn document_vectors(&self, document: &Document) -> Result<DocumentVectors, SQLError> {
227        Engine::document_vector_values(&self.table, document)
228    }
229    fn clear_documents(&self) -> StorageBackendResult<()> {
230        self.table.discard_document_count();
231        self.table.document_store.write().clear()
232    }
233    fn clear_text_index(&self) -> StorageBackendResult<()> {
234        self.table.inverted_index.write().clear()
235    }
236    fn vector_indexes(&self) -> VacuumVectorIndexes<'_> {
237        Box::new(self.table.vector_indexes.write())
238    }
239    fn clear_value_indexes(&self) {
240        self.table.value_indexes.write().clear();
241    }
242    fn persistence(&self) -> RelationPersistence {
243        self.table.persistence
244    }
245    fn mark_doc_count_dirty(&self) {
246        self.table.discard_document_count();
247    }
248}
249impl VacuumLocks for Engine {
250    fn lock_exclusive(&self, table: &str) -> Result<(), SQLError> {
251        self.lock_relation(table, crate::row_locks::RelationLockMode::AccessExclusive)
252    }
253    fn release_session(&self) {
254        self.row_locks.release_session(self.session_id);
255    }
256}
257impl VacuumStorage for Engine {
258    fn reclaim_obsolete(&self) -> StorageBackendResult<()> {
259        if let Some(backend) = self.storage.backend.as_ref() {
260            backend.reclaim_obsolete()?;
261        }
262        Ok(())
263    }
264
265    fn vacuum(&self) -> StorageBackendResult<()> {
266        if let Some(backend) = self.storage.backend.as_ref() {
267            backend.vacuum()?;
268        }
269        Ok(())
270    }
271    fn clear_btree_indexes(&self, table: &str) -> StorageBackendResult<()> {
272        if let Some(backend) = self.storage.backend.as_ref() {
273            backend.clear_btree_indexes(table)?;
274        }
275        Ok(())
276    }
277}
278impl VacuumRows for Engine {
279    fn restore_document(
280        &self,
281        table: &str,
282        id: DocId,
283        document: StoredDocument,
284        vectors: DocumentVectors,
285    ) -> Result<(), SQLError> {
286        self.add_prepared_stored_document_with_vector_values_inner(
287            table,
288            id,
289            document,
290            vectors,
291            uqa_execution::mutation::publication::InsertedIdentity::Vacant,
292        )
293    }
294    fn refresh_indexes(&self, table: &str) -> StorageBackendResult<()> {
295        self.refresh_value_indexes_for_table(table)
296    }
297    fn note_table_data_changed(&self) {
298        Engine::note_table_data_changed(self);
299    }
300}
301impl VacuumStatisticsRefresh for Engine {
302    fn table_names(&self, operation: &str) -> Result<Vec<String>, SQLError> {
303        self.maintenance_table_names(operation)
304    }
305    fn analyze_target(
306        &self,
307        table: &str,
308        columns: &[String],
309        descendants: bool,
310    ) -> StorageBackendResult<()> {
311        self.run_analyze_target(table, columns, descendants)
312    }
313}
314impl VacuumTransactions for Engine {
315    fn depth(&self) -> usize {
316        self.transaction_depth()
317    }
318    fn with_maintenance_write(&self, write: VacuumWrite<'_>) -> StorageBackendResult<()> {
319        self.with_read_only_compatible_storage_transaction(|engine| {
320            write(&engine.vacuum_execution_context())
321        })
322    }
323}