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    fn rebind_persistent_vector_field(
162        &self,
163        table: &str,
164        field: &str,
165        dimensions: u32,
166        spec: VectorIndexSpec,
167    ) -> StorageBackendResult<()> {
168        let relation = uqa_core::RelationIdentity::from_legacy_name(table)
169            .map_err(StorageBackendError::Other)?;
170        let state = self
171            .storage
172            .tables
173            .read()
174            .get(&relation)
175            .cloned()
176            .ok_or_else(|| {
177                StorageBackendError::Other(format!("published index table `{table}` disappeared"))
178            })?;
179        if self.storage.backend.is_some()
180            && state.persistence != uqa_sql::ast::RelationPersistence::Temporary
181        {
182            if state.vector_indexes.read().get(field).is_some_and(|index| {
183                index.dimensions() == dimensions && index.physical_configuration() == Some(spec)
184            }) {
185                return Ok(());
186            }
187            let index = self.build_vector_index_for_restore(table, field, dimensions, spec)?;
188            state
189                .vector_indexes
190                .write()
191                .live_mut()?
192                .insert(field.into(), index);
193        }
194        Ok(())
195    }
196}
197
198impl IndexRenameTransactions for Engine {
199    fn with_index_rename(
200        &self,
201        write: IndexRenameWrite<'_>,
202    ) -> Result<uqa_sql::SQLResult, SQLError> {
203        self.with_implicit_definition_transaction(|engine| {
204            write(&IndexRenameContext {
205                registry: engine.index_registry_context(),
206                constraints: engine.constraint_alter_context(),
207                binding: engine.table_alter_binding_context(),
208            })
209        })
210    }
211}
212impl IndexCreationNamespace for Engine {
213    fn ensure_table_owner(&self, table: &str) -> Result<(), SQLError> {
214        Engine::ensure_table_owner(self, table).map(|_| ())
215    }
216
217    fn relation_exists(&self, name: &str) -> Result<bool, SQLError> {
218        Ok(matches!(
219            self.resolve_bound_relation_kind(name)?,
220            RelationResolution::Found(_, _)
221        ))
222    }
223}
224impl VectorIndexCatalog for Engine {
225    fn resolve_table_name(&self, name: &str) -> Result<Option<String>, SQLError> {
226        self.try_resolve_table_name(name)
227            .map_err(|error| storage_error("CREATE INDEX", &error))
228    }
229    fn column_type(&self, table: &str, column: &str) -> Result<Option<ColumnType>, SQLError> {
230        Engine::column_type(self, table, column)
231            .map_err(|error| storage_error("CREATE INDEX", &error))
232    }
233    fn vector_index_names(&self, table: &str, column: &str) -> Result<Vec<String>, SQLError> {
234        self.vector_catalog_index_names_for_column(table, column)
235            .map_err(|error| storage_error("CREATE INDEX", &error))
236    }
237}
238impl IndexCreationPublication for Engine {
239    fn create_diskann_field(
240        &self,
241        row: &CatalogIndexRow,
242        field: &str,
243        dimensions: u32,
244        parameters: uqa_storage::vector_index::DiskANNIndexParams,
245    ) -> Result<(), SQLError> {
246        self.prepare_explicit_transaction_writer()?;
247        self.install_catalog_diskann_index(row, field, dimensions, parameters)
248            .map_err(|error| storage_error("CREATE INDEX diskann", &error))
249    }
250    fn add_text_field(
251        &self,
252        table: &str,
253        column: &str,
254        analyzer: Option<&str>,
255    ) -> Result<(), SQLError> {
256        // Admit a deferred statement writer before changing physical storage. Initial restoration already owns its backend transaction and has no session frame to promote.
257        self.prepare_explicit_transaction_writer()?;
258        self.add_fts_field_with_analyzer_inner(table, column.to_string(), analyzer)
259    }
260    fn rebuild_vector_field(
261        &self,
262        table: &str,
263        column: &str,
264        dimensions: u32,
265        spec: VectorIndexSpec,
266    ) -> Result<bool, SQLError> {
267        self.prepare_explicit_transaction_writer()?;
268        self.rebuild_vector_field_in_transaction(table, column, dimensions, spec)
269            .map_err(|error| storage_error("CREATE INDEX vector field", &error))
270    }
271    fn register_index(
272        &self,
273        name: &str,
274        method: &str,
275        table: &str,
276        keys: &[IndexKey],
277        options: &[(String, String)],
278        definition: &IndexDefinition,
279    ) -> Result<(), SQLError> {
280        self.register_catalog_index_definition(name, method, table, keys, options, definition)
281            .map_err(|error| storage_error("CREATE INDEX", &error))?;
282        Ok(())
283    }
284    fn planned_partition_indexes(
285        &self,
286        name: &str,
287        method: &str,
288        table: &str,
289        keys: &[IndexKey],
290        options: &[(String, String)],
291        definition: &IndexDefinition,
292    ) -> Result<std::collections::BTreeMap<String, String>, SQLError> {
293        self.planned_catalog_partition_indexes(name, method, table, keys, options, definition)
294            .map_err(|error| storage_error("CREATE INDEX", &error))
295    }
296}