Skip to main content

uqa_engine/capabilities/
index_creation.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Metadata and publication adapters for SQL-owned index declarations and execution-owned builds.
8use crate::{capabilities::RelationResolution, Engine};
9use uqa_execution::schema::indexes::registry::{
10    IndexPublicationKind, IndexRegistryContext, IndexRegistryPublication,
11};
12use uqa_execution::schema::indexes::renaming::{
13    IndexRenameContext, IndexRenameTransactions, IndexRenameWrite,
14};
15use uqa_execution::schema::indexes::{
16    creation::{IndexCreationContext, IndexCreationNamespace, IndexCreationPublication},
17    IndexBuildContext,
18};
19use uqa_sql::{
20    ast::{ColumnType, IndexKey},
21    catalog::{errors::storage_error, index::IndexDefinition},
22    schema::indexes::vectors::VectorIndexCatalog,
23    SQLError,
24};
25use uqa_storage::vector_index::VectorIndexSpec;
26use uqa_storage::{CatalogIndexRow, StorageBackendError, StorageBackendResult};
27impl Engine {
28    pub(crate) fn index_registry_context(&self) -> IndexRegistryContext<'_> {
29        IndexRegistryContext {
30            identities: self.catalog_identity_reservation_context(),
31            constraint_catalog: self,
32            publication: self,
33            builds: self,
34            retirement: self,
35            vectors: self,
36            tables: self,
37            locks: self,
38            lock_catalog: self,
39        }
40    }
41    pub(crate) fn index_creation_context(&self) -> IndexCreationContext<'_> {
42        let runtime = self.query_runtime_view();
43        IndexCreationContext {
44            creation: self.relation_creation_context(),
45            namespace: self,
46            names: self,
47            schema: self,
48            bindings: self,
49            unique: IndexBuildContext {
50                catalog: self,
51                reads: self,
52                expressions: self.constraint_execution_context().index_expressions(),
53                memory: runtime.settings,
54                description: self,
55            },
56            vectors: self,
57            publication: self,
58            notices: runtime.notices,
59        }
60    }
61}
62
63impl IndexRegistryPublication for Engine {
64    fn persist_index(
65        &self,
66        row: &CatalogIndexRow,
67        kind: IndexPublicationKind,
68    ) -> StorageBackendResult<()> {
69        let relation = uqa_core::RelationIdentity::from_legacy_name(&row.table_name)
70            .map_err(StorageBackendError::Other)?;
71        let table = self
72            .storage
73            .tables
74            .read()
75            .get(&relation)
76            .cloned()
77            .ok_or_else(|| {
78                StorageBackendError::Other(format!("index table `{}` disappeared", row.table_name))
79            })?;
80        if table.persistence != uqa_sql::ast::RelationPersistence::Temporary {
81            if let Some(catalog) = &self.storage.catalog {
82                catalog.save_catalog_index_row(row)?;
83                self.note_table_catalog_changed();
84            }
85        }
86        if kind == IndexPublicationKind::Definition {
87            self.note_prepared_table_change(&table);
88        }
89        Ok(())
90    }
91
92    fn erase_index(
93        &self,
94        row: &CatalogIndexRow,
95        kind: IndexPublicationKind,
96    ) -> StorageBackendResult<()> {
97        let relation = uqa_core::RelationIdentity::from_legacy_name(&row.table_name)
98            .map_err(StorageBackendError::Other)?;
99        let temporary = self
100            .storage
101            .tables
102            .read()
103            .get(&relation)
104            .is_some_and(|table| table.persistence == uqa_sql::ast::RelationPersistence::Temporary);
105        if !temporary {
106            if let Some(catalog) = &self.storage.catalog {
107                catalog.drop_catalog_index(&row.relation)?;
108                self.note_table_catalog_changed();
109            }
110        }
111        if kind == IndexPublicationKind::Definition {
112            self.note_prepared_relation_change(&relation);
113        }
114        Ok(())
115    }
116
117    fn publish_index(&self, row: CatalogIndexRow) {
118        self.durable
119            .catalog_indexes
120            .write()
121            .insert(row.relation.clone(), row);
122        self.note_catalog_registry_changed();
123    }
124
125    fn forget_index(&self, relation: &uqa_core::RelationIdentity) {
126        self.durable.catalog_indexes.write().remove(relation);
127        self.note_catalog_registry_changed();
128    }
129
130    fn rebind_diskann_index(&self, row: &CatalogIndexRow) -> StorageBackendResult<()> {
131        let (field, dimensions, parameters) =
132            uqa_execution::schema::indexes::diskann::target(self, row)?;
133        let index = self.build_catalog_diskann_index(
134            row,
135            &field,
136            dimensions,
137            parameters,
138            uqa_storage::VectorIndexOpenMode::Restore,
139        )?;
140        let relation = uqa_core::RelationIdentity::from_legacy_name(&row.table_name)
141            .map_err(StorageBackendError::Other)?;
142        let table = self
143            .storage
144            .tables
145            .read()
146            .get(&relation)
147            .cloned()
148            .ok_or_else(|| StorageBackendError::Other("renamed index table disappeared".into()))?;
149        table
150            .vector_indexes
151            .write()
152            .live_mut()?
153            .insert(field, index);
154        Ok(())
155    }
156
157    fn refresh_index_table(&self, table: &str) -> StorageBackendResult<()> {
158        self.refresh_value_indexes_for_table(table)
159    }
160}
161
162impl IndexRenameTransactions for Engine {
163    fn with_index_rename(
164        &self,
165        write: IndexRenameWrite<'_>,
166    ) -> Result<uqa_sql::SQLResult, SQLError> {
167        self.with_implicit_definition_transaction(|engine| {
168            write(&IndexRenameContext {
169                registry: engine.index_registry_context(),
170                constraints: engine.constraint_alter_context(),
171                binding: engine.table_alter_binding_context(),
172            })
173        })
174    }
175}
176impl IndexCreationNamespace for Engine {
177    fn ensure_table_owner(&self, table: &str) -> Result<(), SQLError> {
178        Engine::ensure_table_owner(self, table).map(|_| ())
179    }
180
181    fn relation_exists(&self, name: &str) -> Result<bool, SQLError> {
182        Ok(matches!(
183            self.resolve_bound_relation_kind(name)?,
184            RelationResolution::Found(_, _)
185        ))
186    }
187}
188impl VectorIndexCatalog for Engine {
189    fn resolve_table_name(&self, name: &str) -> Result<Option<String>, SQLError> {
190        self.try_resolve_table_name(name)
191            .map_err(|error| storage_error("CREATE INDEX", &error))
192    }
193    fn column_type(&self, table: &str, column: &str) -> Result<Option<ColumnType>, SQLError> {
194        Engine::column_type(self, table, column)
195            .map_err(|error| storage_error("CREATE INDEX", &error))
196    }
197    fn vector_index_names(&self, table: &str, column: &str) -> Result<Vec<String>, SQLError> {
198        self.vector_catalog_index_names_for_column(table, column)
199            .map_err(|error| storage_error("CREATE INDEX", &error))
200    }
201}
202impl IndexCreationPublication for Engine {
203    fn create_diskann_field(
204        &self,
205        row: &CatalogIndexRow,
206        field: &str,
207        dimensions: u32,
208        parameters: uqa_storage::vector_index::DiskANNIndexParams,
209    ) -> Result<(), SQLError> {
210        self.prepare_explicit_transaction_writer()?;
211        self.install_catalog_diskann_index(row, field, dimensions, parameters)
212            .map_err(|error| storage_error("CREATE INDEX diskann", &error))
213    }
214    fn add_text_field(
215        &self,
216        table: &str,
217        column: &str,
218        analyzer: Option<&str>,
219    ) -> Result<(), SQLError> {
220        // Admit a deferred statement writer before changing physical storage. Initial restoration already owns its backend transaction and has no session frame to promote.
221        self.prepare_explicit_transaction_writer()?;
222        self.add_fts_field_with_analyzer_inner(table, column.to_string(), analyzer)
223    }
224    fn rebuild_vector_field(
225        &self,
226        table: &str,
227        column: &str,
228        dimensions: u32,
229        spec: VectorIndexSpec,
230    ) -> Result<bool, SQLError> {
231        self.prepare_explicit_transaction_writer()?;
232        self.rebuild_vector_field_in_transaction(table, column, dimensions, spec)
233            .map_err(|error| storage_error("CREATE INDEX vector field", &error))
234    }
235    fn register_index(
236        &self,
237        name: &str,
238        method: &str,
239        table: &str,
240        keys: &[IndexKey],
241        options: &[(String, String)],
242        definition: &IndexDefinition,
243    ) -> Result<(), SQLError> {
244        self.register_catalog_index_definition(name, method, table, keys, options, definition)
245            .map_err(|error| storage_error("CREATE INDEX", &error))?;
246        Ok(())
247    }
248    fn planned_partition_indexes(
249        &self,
250        name: &str,
251        method: &str,
252        table: &str,
253        keys: &[IndexKey],
254        options: &[(String, String)],
255        definition: &IndexDefinition,
256    ) -> Result<std::collections::BTreeMap<String, String>, SQLError> {
257        self.planned_catalog_partition_indexes(name, method, table, keys, options, definition)
258            .map_err(|error| storage_error("CREATE INDEX", &error))
259    }
260}