Skip to main content

uqa_engine/
tables.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7use super::{
8    standard_analyzer, Analyzer, Arc, AtomicBool, BTreeMap, DocId, Document, DocumentStore, Engine,
9    FieldName, HNSWIndex, IVFIndex, InvertedIndex, MemoryDocumentStore, MemoryInvertedIndex,
10    MemoryVectorIndex, RelationIdentity, RwLock, SQLError, StorageBackendError,
11    StorageBackendResult, TableSchema, TableState, VectorFieldSchema, VectorIndex,
12    VectorIndexOpenMode, VectorIndexSpec,
13};
14use crate::state::BoundTableSecurity;
15use uqa_execution::catalog::definition_revision::TablePublicationKind;
16
17impl Engine {
18    pub(crate) fn is_persistent(&self) -> bool {
19        self.storage.catalog.is_some()
20    }
21
22    pub(crate) fn try_save_table_schema(
23        &self,
24        name: &str,
25        table: &TableState,
26    ) -> StorageBackendResult<()> {
27        let columns = table.columns.read().clone();
28        self.try_save_table_schema_with_columns(name, table, &columns)
29    }
30
31    pub(crate) fn try_save_table_schema_with_columns(
32        &self,
33        name: &str,
34        table: &TableState,
35        columns: &[uqa_sql::ast::ColumnDef],
36    ) -> StorageBackendResult<()> {
37        let constraints = uqa_sql::ast::TableConstraintSet {
38            columns_declared: Some(*table.columns_declared.read()),
39            checks: table.table_checks.read().clone(),
40            foreign_keys: table.foreign_keys.read().clone(),
41            key_constraints: table.key_constraints.read().clone(),
42            persistence: table.persistence,
43            on_commit: table.on_commit,
44            hierarchy: table.hierarchy.read().clone(),
45            catalog_oids: table.recorded_catalog_oids(),
46            row_type_array_name: table.row_type_array_name.read().clone(),
47            dropped_attributes: table.dropped_attributes.read().clone(),
48        };
49        self.try_save_table_schema_with_components(name, table, columns, &constraints)
50    }
51
52    pub(crate) fn try_save_table_schema_with_components(
53        &self,
54        name: &str,
55        table: &TableState,
56        columns: &[uqa_sql::ast::ColumnDef],
57        constraints: &uqa_sql::ast::TableConstraintSet,
58    ) -> StorageBackendResult<()> {
59        let security = table.security();
60        self.try_save_table_schema_with_components_and_security(
61            name,
62            table,
63            columns,
64            constraints,
65            &security,
66        )
67    }
68
69    pub(crate) fn try_save_table_schema_with_components_and_security(
70        &self,
71        name: &str,
72        table: &TableState,
73        columns: &[uqa_sql::ast::ColumnDef],
74        constraints: &uqa_sql::ast::TableConstraintSet,
75        security: &crate::state::BoundTableSecurity,
76    ) -> StorageBackendResult<()> {
77        self.try_save_table_schema_candidate(
78            name,
79            table,
80            columns,
81            constraints,
82            security,
83            TablePublicationKind::Definition,
84        )
85    }
86
87    pub(crate) fn try_save_table_schema_candidate(
88        &self,
89        name: &str,
90        table: &TableState,
91        columns: &[uqa_sql::ast::ColumnDef],
92        constraints: &uqa_sql::ast::TableConstraintSet,
93        security: &crate::state::BoundTableSecurity,
94        kind: TablePublicationKind,
95    ) -> StorageBackendResult<()> {
96        if table.persistence == uqa_sql::ast::RelationPersistence::Temporary {
97            if kind != TablePublicationKind::ExpressionNames {
98                self.note_prepared_table_change(table);
99            }
100            return Ok(());
101        }
102        let Some(catalog) = self.storage.catalog.as_ref() else {
103            if kind != TablePublicationKind::ExpressionNames {
104                self.note_prepared_table_change(table);
105            }
106            return Ok(());
107        };
108        let analyzer_json =
109            serde_json::to_string(&*table.analyzer.read()).map_err(StorageBackendError::from)?;
110        let vector_fields: Vec<VectorFieldSchema> = table
111            .vector_indexes
112            .read()
113            .iter()
114            .map(|(field, idx)| VectorFieldSchema {
115                field: field.clone(),
116                dimensions: idx.dimensions(),
117            })
118            .collect();
119        let columns_json = serde_json::to_string(columns).map_err(StorageBackendError::from)?;
120        // The table's state is the authority for the OIDs it was created with.
121        let constraints = uqa_sql::ast::TableConstraintSet {
122            catalog_oids: table.recorded_catalog_oids(),
123            ..constraints.clone()
124        };
125        let constraints_json =
126            uqa_execution::schema::indexes::constraint_names::encode_for_catalog(
127                catalog.as_ref(),
128                &constraints,
129            )?;
130        catalog.save_table(&TableSchema {
131            relation: RelationIdentity::from_legacy_name(name)
132                .map_err(StorageBackendError::Other)?,
133            security: security.row().into(),
134            object_id: table.object_id(),
135            storage_generation: table.storage_generation(),
136            analyzer_json,
137            fts_fields: table.fts_fields(),
138            vector_fields,
139            columns_json,
140            constraints_json,
141        })?;
142        if kind != TablePublicationKind::Declaration {
143            uqa_execution::catalog::tuples::publication::queue_relation(
144                catalog.as_ref(),
145                &RelationIdentity::from_legacy_name(name).map_err(StorageBackendError::Other)?,
146                table.object_id(),
147                !constraints.checks.is_empty()
148                    || !constraints.foreign_keys.is_empty()
149                    || !constraints.key_constraints.is_empty()
150                    || columns.iter().any(|column| {
151                        column.not_null || column.check.is_some() || column.references.is_some()
152                    }),
153            )?;
154        }
155        self.note_table_catalog_changed();
156        if kind != TablePublicationKind::ExpressionNames {
157            uqa_execution::catalog::definition_revision::publish_table(
158                catalog.as_ref(),
159                table.object_id(),
160            )?;
161            self.note_prepared_table_change(table);
162        }
163        Ok(())
164    }
165
166    pub(crate) fn try_persist_table_schema(&self, table: &str) -> StorageBackendResult<bool> {
167        let table_name = self
168            .try_resolve_table_name(table)?
169            .ok_or_else(|| StorageBackendError::Other(format!("table `{table}` does not exist")))?;
170        let t = self.try_table(&table_name)?.ok_or_else(|| {
171            StorageBackendError::Other(format!("table `{table_name}` does not exist"))
172        })?;
173        self.try_save_table_schema(&table_name, &t)?;
174        Ok(true)
175    }
176
177    /// Register a table. `fts_fields` is the list of field names that are
178    /// tokenized into the inverted index when documents are inserted.
179    /// Other fields are still stored in the document store but are not
180    /// queryable via `text_match` / [`uqa_operators::TermOperator`].
181    pub fn create_table(
182        &self,
183        name: impl Into<String>,
184        analyzer: Analyzer,
185        fts_fields: Vec<FieldName>,
186    ) -> StorageBackendResult<()> {
187        let raw_name = name.into();
188        self.with_implicit_storage_transaction(move |engine| {
189            let owner = engine
190                .relation_creation_context()
191                .bind_owner()
192                .map_err(|error| StorageBackendError::backend("CREATE TABLE owner", error))?;
193            engine.create_table_inner(
194                &raw_name,
195                analyzer,
196                fts_fields,
197                uqa_sql::ast::RelationPersistence::Permanent,
198                uqa_sql::ast::OnCommitAction::PreserveRows,
199                &owner,
200            )
201        })
202    }
203
204    /// Create a table whose name relation creation resolved, under the OIDs `CREATE TABLE` allocated for it or, when none are given, OIDs allocated now.
205    #[expect(
206        clippy::too_many_arguments,
207        reason = "the lifecycle attributes and the OIDs a statement allocated are set once at creation"
208    )]
209    pub(crate) fn create_table_with_lifecycle(
210        &self,
211        name: &str,
212        analyzer: Analyzer,
213        fts_fields: Vec<FieldName>,
214        persistence: uqa_sql::ast::RelationPersistence,
215        on_commit: uqa_sql::ast::OnCommitAction,
216        owner: &uqa_execution::catalog::security::roles::locking::RoleBinding,
217        catalog_oids: Option<uqa_sql::catalog::relation_oids::RelationCatalogOids>,
218    ) -> StorageBackendResult<()> {
219        self.create_resolved_table(
220            name,
221            analyzer,
222            fts_fields,
223            persistence,
224            on_commit,
225            owner,
226            catalog_oids,
227        )
228    }
229
230    /// Create a table named through the API, whose name resolves among the durable schemas.
231    fn create_table_inner(
232        &self,
233        raw_name: &str,
234        analyzer: Analyzer,
235        fts_fields: Vec<FieldName>,
236        persistence: uqa_sql::ast::RelationPersistence,
237        on_commit: uqa_sql::ast::OnCommitAction,
238        owner: &uqa_execution::catalog::security::roles::locking::RoleBinding,
239    ) -> StorageBackendResult<()> {
240        let name = self.relation_creation_context().api_name(raw_name)?;
241        self.create_resolved_table(
242            &name,
243            analyzer,
244            fts_fields,
245            persistence,
246            on_commit,
247            owner,
248            None,
249        )
250    }
251
252    /// Create a table under the canonical name that relation creation resolved, in the namespace and with the persistence it chose. `CREATE TABLE` passes the OIDs it allocated where `heap_create_with_catalog` allocates them; a table the API or `CREATE TABLE AS` creates reserves its row type name and takes its OIDs here.
253    #[expect(
254        clippy::too_many_arguments,
255        reason = "the lifecycle attributes and the OIDs a statement allocated are set once at creation"
256    )]
257    fn create_resolved_table(
258        &self,
259        name: &str,
260        analyzer: Analyzer,
261        fts_fields: Vec<FieldName>,
262        persistence: uqa_sql::ast::RelationPersistence,
263        on_commit: uqa_sql::ast::OnCommitAction,
264        owner: &uqa_execution::catalog::security::roles::locking::RoleBinding,
265        catalog_oids: Option<uqa_sql::catalog::relation_oids::RelationCatalogOids>,
266    ) -> StorageBackendResult<()> {
267        let relation = Self::resolved_relation_identity(name)?;
268        if let Some(kind) = self.relation_kind_at(name)? {
269            return Err(StorageBackendError::Other(format!(
270                "relation `{name}` already exists as {kind}"
271            )));
272        }
273        let default_revision = (!fts_fields.is_empty())
274            .then(|| analyzer.compile())
275            .transpose()?;
276        let analyzer = match &default_revision {
277            Some(revision) => revision.descriptor().configuration()?,
278            None => analyzer,
279        };
280        let (docs, inv): (Box<dyn DocumentStore>, Box<dyn InvertedIndex>) = if let Some(backend) =
281            self.storage
282                .backend
283                .as_ref()
284                .filter(|_| persistence != uqa_sql::ast::RelationPersistence::Temporary)
285        {
286            (
287                backend.document_store(name),
288                backend.inverted_index(name, analyzer.clone()),
289            )
290        } else {
291            (
292                Box::new(MemoryDocumentStore::new()),
293                Box::new(MemoryInvertedIndex::new(analyzer.clone())),
294            )
295        };
296        self.relation_creation_context()
297            .retain_owner(owner)
298            .map_err(|error| StorageBackendError::backend("CREATE TABLE owner", error))?;
299        let catalog_oids = if let Some(catalog_oids) = catalog_oids {
300            catalog_oids
301        } else {
302            self.relation_creation_context()
303                .reserve_row_type_name(name)
304                .map_err(|error| StorageBackendError::backend("CREATE TABLE name", error))?;
305            self.catalog_identity_reservation_context()
306                .allocator(uqa_execution::catalog::identity::allocate_catalog_object_id)
307                .allocate_relation_oids(
308                    uqa_sql::catalog::relation_oids::RelationOidKind::Table,
309                    &relation,
310                )
311                .map_err(|error| StorageBackendError::backend("CREATE TABLE OIDs", error))?
312        };
313        let row_type_array_name = uqa_execution::schema::types::arrays::reserve_array_name(
314            &self.relation_creation_context(),
315            &relation.schema,
316            &relation.name,
317        )
318        .map_err(|error| StorageBackendError::backend("CREATE TABLE array type", error))?;
319        let table = TableState {
320            lifecycle_id: std::sync::atomic::AtomicU64::new(crate::next_table_lifecycle_id()),
321            object_id: crate::new_table_object_id()?,
322            security: crate::state::CatalogCell::new(BoundTableSecurity::owner(owner.identity())),
323            storage_generation: RwLock::new(crate::new_table_storage_generation()?),
324            document_store: RwLock::new(docs),
325            inverted_index: RwLock::new(inv),
326            vector_indexes: RwLock::new(uqa_storage::vector_index::VectorIndexes::default()),
327            fts_fields: crate::state::CatalogCell::new(fts_fields),
328            columns: crate::state::CatalogCell::new(Vec::new()),
329            columns_declared: crate::state::CatalogCell::new(false),
330            next_id: parking_lot::Mutex::new(1),
331            maps_integer_keys: AtomicBool::new(true),
332            analyzer: crate::state::CatalogCell::new(analyzer),
333            column_stats: crate::state::CatalogCell::new(uqa_planner::ColumnStatistics::default()),
334            column_stats_loaded: AtomicBool::new(true),
335            column_stats_dirty: AtomicBool::new(true),
336            statistics_maintenance: parking_lot::Mutex::default(),
337            table_checks: crate::state::CatalogCell::new(Vec::new()),
338            foreign_keys: crate::state::CatalogCell::new(Vec::new()),
339            key_constraints: crate::state::CatalogCell::new(Vec::new()),
340            hierarchy: crate::state::CatalogCell::new(uqa_sql::ast::TableHierarchy::default()),
341            value_indexes: RwLock::new(BTreeMap::new()),
342            doc_count_cache: std::sync::atomic::AtomicU64::new(0),
343            doc_count_dirty: AtomicBool::new(true),
344            persistence,
345            on_commit,
346            catalog_oids: Some(catalog_oids),
347            row_type_array_name: crate::state::CatalogCell::new(Some(row_type_array_name)),
348            dropped_attributes: crate::state::CatalogCell::new(Vec::new()),
349        };
350        let table_arc = Arc::new(table);
351        if self.is_persistent() && persistence != uqa_sql::ast::RelationPersistence::Temporary {
352            self.try_save_table_schema(name, &table_arc)?;
353        }
354        let analyzer_bindings =
355            self.initialize_table_analyzer_bindings(name, &table_arc, default_revision)?;
356        self.note_prepared_table_change(&table_arc);
357        self.storage.tables.write().insert(relation, table_arc);
358        self.durable
359            .table_field_analyzers
360            .write()
361            .extend(analyzer_bindings);
362        self.clear_regtype_output_cache();
363        if persistence == uqa_sql::ast::RelationPersistence::Temporary {
364            self.note_table_catalog_changed();
365        }
366        Ok(())
367    }
368
369    /// Register a vector field on a table. Existing document values in the
370    /// same field are indexed immediately; later calls to [`Engine::add_vector`]
371    /// or [`Engine::add_document_with_vectors`] keep it current. `CREATE INDEX
372    /// ... USING ivf` or `CREATE INDEX ... USING hnsw` upgrades the field to
373    /// the corresponding approximate backend.
374    pub fn create_vector_field(
375        &self,
376        table: &str,
377        field: impl Into<FieldName>,
378        dimensions: u32,
379    ) -> StorageBackendResult<bool> {
380        let field = field.into();
381        self.with_implicit_storage_definition_transaction(|engine| {
382            engine.install_vector_field(
383                table,
384                field,
385                dimensions,
386                VectorIndexSpec::BruteForce,
387                false,
388                true,
389            )
390        })
391    }
392
393    pub(crate) fn rebuild_vector_field_with_spec(
394        &self,
395        table: &str,
396        field: impl Into<FieldName>,
397        dimensions: u32,
398        spec: VectorIndexSpec,
399    ) -> StorageBackendResult<bool> {
400        let field = field.into();
401        self.with_implicit_storage_transaction(|engine| {
402            engine.rebuild_vector_field_in_transaction(table, field, dimensions, spec)
403        })
404    }
405
406    pub(crate) fn rebuild_vector_field_in_transaction(
407        &self,
408        table: &str,
409        field: impl Into<FieldName>,
410        dimensions: u32,
411        spec: VectorIndexSpec,
412    ) -> StorageBackendResult<bool> {
413        self.install_vector_field(table, field.into(), dimensions, spec, true, true)
414    }
415
416    pub(crate) fn rebuild_vector_field(
417        &self,
418        table: &str,
419        field: impl Into<FieldName>,
420        dimensions: u32,
421    ) -> StorageBackendResult<bool> {
422        self.rebuild_vector_field_with_spec(table, field, dimensions, VectorIndexSpec::BruteForce)
423    }
424
425    pub(crate) fn drop_vector_field_index(
426        &self,
427        table: &str,
428        field: impl Into<FieldName>,
429        dimensions: u32,
430    ) -> StorageBackendResult<bool> {
431        self.rebuild_vector_field(table, field, dimensions)
432    }
433
434    pub(crate) fn drop_vector_index_metadata(
435        &self,
436        table: &str,
437        field: &str,
438    ) -> StorageBackendResult<()> {
439        if let Some(backend) = self.storage.backend.as_ref() {
440            backend.drop_vector_index_metadata(table, field)?;
441        }
442        Ok(())
443    }
444
445    pub(crate) fn restore_vector_field_index(
446        &self,
447        table: &str,
448        field: impl Into<FieldName>,
449        dimensions: u32,
450        spec: VectorIndexSpec,
451    ) -> StorageBackendResult<bool> {
452        let t = self
453            .try_table(table)?
454            .ok_or_else(|| StorageBackendError::Other(format!("table `{table}` does not exist")))?;
455        let field = field.into();
456        let idx = self.build_vector_index_for_restore(table, &field, dimensions, spec)?;
457        t.vector_indexes.write().live_mut()?.insert(field, idx);
458        Ok(true)
459    }
460
461    pub(crate) fn restore_fts_field_from_catalog(
462        &self,
463        table: &str,
464        field: &str,
465        analyzer: Option<&str>,
466    ) -> Result<(), String> {
467        let t = self
468            .try_table(table)
469            .map_err(|err| format!("resolve table `{table}`: {err}"))?
470            .ok_or_else(|| format!("unknown table `{table}`"))?;
471        if let Some(analyzer_name) = analyzer {
472            let bindings = self.durable.table_field_analyzers.read();
473            let binding = bindings
474                .get(&(table.to_owned(), field.to_owned()))
475                .ok_or_else(|| "GIN field has no restored analyzer binding".to_owned())?;
476            if binding.owner != uqa_storage::AnalyzerBindingOwner::Gin
477                || binding.index.name.as_deref() != Some(analyzer_name.trim())
478            {
479                return Err("GIN field conflicts with restored analyzer ownership".into());
480            }
481        }
482        {
483            let mut fts = t.fts_fields.write();
484            if !fts.iter().any(|f| f == field) {
485                fts.push(field.to_string());
486            }
487        }
488        Ok(())
489    }
490
491    pub(crate) fn install_vector_field(
492        &self,
493        table: &str,
494        field: FieldName,
495        dimensions: u32,
496        spec: VectorIndexSpec,
497        replace_existing: bool,
498        persist_schema: bool,
499    ) -> StorageBackendResult<bool> {
500        let Some(table_name) = self.try_resolve_table_name(table)? else {
501            return Err(StorageBackendError::Other(format!(
502                "table `{table}` does not exist"
503            )));
504        };
505        let Some(t) = self.try_table(&table_name)? else {
506            return Err(StorageBackendError::Other(format!(
507                "table `{table_name}` disappeared while installing vector field `{field}`"
508            )));
509        };
510        if !replace_existing {
511            if let Some(existing) = t.vector_indexes.read().get(&field) {
512                let existing_dimensions = existing.dimensions();
513                if existing_dimensions == dimensions {
514                    return Ok(false);
515                }
516                return Err(StorageBackendError::Other(format!(
517                    "vector field `{table_name}.{field}` has dimension {existing_dimensions}, requested {dimensions}"
518                )));
519            }
520        }
521        let mut idx = self.build_vector_index(&table_name, &field, dimensions, spec)?;
522        if idx.count()? == 0 {
523            Self::backfill_vector_index(&t, &field, idx.as_mut())?;
524        }
525        idx.initialize()?;
526        let old = t
527            .vector_indexes
528            .write()
529            .live_mut()?
530            .insert(field.clone(), idx);
531        if persist_schema && self.is_persistent() {
532            if let Err(err) = self.try_save_table_schema(&table_name, &t) {
533                let mut vectors = t.vector_indexes.write();
534                let indexes = vectors.live_mut()?;
535                indexes.remove(&field);
536                if let Some(old) = old {
537                    indexes.insert(field, old);
538                }
539                return Err(err);
540            }
541        }
542        Ok(true)
543    }
544
545    fn build_vector_index(
546        &self,
547        table: &str,
548        field: &str,
549        dimensions: u32,
550        spec: VectorIndexSpec,
551    ) -> StorageBackendResult<Box<dyn VectorIndex>> {
552        self.build_vector_index_with_mode(
553            table,
554            field,
555            dimensions,
556            spec,
557            VectorIndexOpenMode::Create,
558        )
559    }
560
561    pub(crate) fn build_vector_index_for_restore(
562        &self,
563        table: &str,
564        field: &str,
565        dimensions: u32,
566        spec: VectorIndexSpec,
567    ) -> StorageBackendResult<Box<dyn VectorIndex>> {
568        self.build_vector_index_with_mode(
569            table,
570            field,
571            dimensions,
572            spec,
573            VectorIndexOpenMode::Restore,
574        )
575    }
576
577    pub(crate) fn build_vector_index_with_mode(
578        &self,
579        table: &str,
580        field: &str,
581        dimensions: u32,
582        spec: VectorIndexSpec,
583        mode: VectorIndexOpenMode,
584    ) -> StorageBackendResult<Box<dyn VectorIndex>> {
585        // Callers pass the canonical name after resolving the table. Looking
586        // it up in the already-loaded registry is essential during catalog
587        // restoration: a normal `try_table` lookup would recursively enter
588        // catalog synchronization while its mutex is already held.
589        if let VectorIndexSpec::DiskANN(parameters) = spec {
590            let row = uqa_execution::catalog::index::vectors::field_index(
591                self.durable.catalog_indexes.read().values(),
592                table,
593                field,
594            )?
595            .cloned()
596            .ok_or_else(|| {
597                StorageBackendError::Other("DiskANN field has no catalog index".into())
598            })?;
599            return self.build_catalog_diskann_index(&row, field, dimensions, parameters, mode);
600        }
601        let relation =
602            RelationIdentity::from_legacy_name(table).map_err(StorageBackendError::Other)?;
603        let temporary = self
604            .storage
605            .tables
606            .read()
607            .get(&relation)
608            .is_some_and(|table| table.persistence == uqa_sql::ast::RelationPersistence::Temporary);
609        if temporary {
610            Self::memory_vector_index(dimensions, spec)
611        } else if let Some(backend) = self.storage.backend.as_ref() {
612            backend.vector_index(table, field, dimensions, spec, mode)
613        } else {
614            Self::memory_vector_index(dimensions, spec)
615        }
616    }
617
618    fn memory_vector_index(
619        dimensions: u32,
620        spec: VectorIndexSpec,
621    ) -> StorageBackendResult<Box<dyn VectorIndex>> {
622        let index: Box<dyn VectorIndex> = match spec {
623            VectorIndexSpec::DiskANN(_) => {
624                return Err(StorageBackendError::Other(
625                    "DiskANN requires its retained resource and catalog binding".into(),
626                ))
627            }
628            VectorIndexSpec::BruteForce => Box::new(MemoryVectorIndex::new(dimensions)),
629            VectorIndexSpec::IVF(params) => Box::new(IVFIndex::with_params(
630                dimensions,
631                params.nlist,
632                params.nprobe,
633                params.train_threshold,
634            )),
635            VectorIndexSpec::HNSW(params) => Box::new(HNSWIndex::with_params(dimensions, params)?),
636        };
637        Ok(index)
638    }
639
640    fn backfill_vector_index(
641        table: &TableState,
642        field: &str,
643        idx: &mut dyn VectorIndex,
644    ) -> StorageBackendResult<()> {
645        let docs = table.document_store.read().snapshot()?;
646        for (doc_id, document) in docs.iter_all()? {
647            let Some(value) = document.get(field) else {
648                continue;
649            };
650            if let Some(vectors) = Self::field_index_vectors(table, field, value)
651                .map_err(|error| StorageBackendError::Other(error.to_string()))?
652            {
653                idx.add_many(doc_id, vectors)?;
654            }
655        }
656        Ok(())
657    }
658
659    pub fn add_vector(
660        &self,
661        table: &str,
662        doc_id: DocId,
663        field: &str,
664        vector: Vec<f32>,
665    ) -> Result<bool, SQLError> {
666        self.with_implicit_row_write_transaction(
667            table,
668            doc_id,
669            uqa_sql::ast::LockStrength::ForNoKeyUpdate,
670            |engine| engine.add_vector_inner(table, doc_id, field, vector),
671        )
672    }
673
674    fn add_vector_inner(
675        &self,
676        table: &str,
677        doc_id: DocId,
678        field: &str,
679        vector: Vec<f32>,
680    ) -> Result<bool, SQLError> {
681        let Some(t) = self
682            .try_table(table)
683            .map_err(|error| SQLError::Internal(format!("resolve table `{table}`: {error}")))?
684        else {
685            return Err(SQLError::UnknownTable(table.to_string()));
686        };
687        let mut registrations = t.vector_indexes.write();
688        let idxs = registrations.live_mut().map_err(|error| {
689            uqa_execution::storage_errors::storage_error("write vector registrations", &error)
690        })?;
691        let Some(idx) = idxs.get_mut(field) else {
692            return Err(SQLError::TypeMismatch(format!(
693                "vector field `{table}.{field}` is not registered"
694            )));
695        };
696        uqa_execution::serializable::vector::observe_write(
697            self,
698            table,
699            &t.columns.snapshot(),
700            field,
701            idx.as_ref(),
702            doc_id,
703            uqa_execution::serializable::vector::VectorChange::Single(&vector),
704        )?;
705        idx.as_mut()
706            .add(doc_id, vector)
707            .map_err(|error| SQLError::Internal(format!("index document vector: {error}")))?;
708        drop(registrations);
709        self.note_table_data_changed();
710        self.note_row_changed(table, doc_id)?;
711        Ok(true)
712    }
713
714    pub fn add_vector_values(
715        &self,
716        table: &str,
717        doc_id: DocId,
718        field: &str,
719        vectors: Vec<Vec<f32>>,
720    ) -> Result<bool, SQLError> {
721        self.with_implicit_row_write_transaction(
722            table,
723            doc_id,
724            uqa_sql::ast::LockStrength::ForNoKeyUpdate,
725            |engine| engine.add_vector_values_inner(table, doc_id, field, vectors),
726        )
727    }
728
729    fn add_vector_values_inner(
730        &self,
731        table: &str,
732        doc_id: DocId,
733        field: &str,
734        vectors: Vec<Vec<f32>>,
735    ) -> Result<bool, SQLError> {
736        let Some(t) = self
737            .try_table(table)
738            .map_err(|error| SQLError::Internal(format!("resolve table `{table}`: {error}")))?
739        else {
740            return Err(SQLError::UnknownTable(table.to_string()));
741        };
742        let mut registrations = t.vector_indexes.write();
743        let idxs = registrations.live_mut().map_err(|error| {
744            uqa_execution::storage_errors::storage_error("write vector registrations", &error)
745        })?;
746        let Some(idx) = idxs.get_mut(field) else {
747            return Err(SQLError::TypeMismatch(format!(
748                "vector field `{table}.{field}` is not registered"
749            )));
750        };
751        uqa_execution::serializable::vector::observe_write(
752            self,
753            table,
754            &t.columns.snapshot(),
755            field,
756            idx.as_ref(),
757            doc_id,
758            uqa_execution::serializable::vector::VectorChange::Tensor(&vectors),
759        )?;
760        idx.as_mut()
761            .add_many(doc_id, vectors)
762            .map_err(|error| SQLError::Internal(format!("index document vectors: {error}")))?;
763        drop(registrations);
764        self.note_table_data_changed();
765        self.note_row_changed(table, doc_id)?;
766        Ok(true)
767    }
768
769    pub(crate) fn validate_vector_values(
770        &self,
771        table: &str,
772        vectors: &BTreeMap<FieldName, Vec<Vec<f32>>>,
773    ) -> Result<(), SQLError> {
774        let Some(t) = self
775            .try_table(table)
776            .map_err(|error| SQLError::Internal(format!("resolve table `{table}`: {error}")))?
777        else {
778            return Err(SQLError::UnknownTable(table.to_string()));
779        };
780        let indexes = t.vector_indexes.read();
781        for (field, values) in vectors {
782            let Some(index) = indexes.get(field) else {
783                return Err(SQLError::UnknownColumn(format!("{table}.{field}")));
784            };
785            let expected = usize::try_from(index.dimensions()).map_err(|_| {
786                SQLError::TypeMismatch(format!(
787                    "vector field `{table}.{field}` dimension exceeds the platform usize range"
788                ))
789            })?;
790            if let Some(vector) = values.iter().find(|vector| vector.len() != expected) {
791                return Err(SQLError::VectorDimMismatch {
792                    expected,
793                    actual: vector.len(),
794                });
795            }
796            if let Some((ordinal, component, value)) =
797                values.iter().enumerate().find_map(|(ordinal, vector)| {
798                    vector
799                        .iter()
800                        .copied()
801                        .enumerate()
802                        .find(|(_, value)| !value.is_finite())
803                        .map(|(component, value)| (ordinal, component, value))
804                })
805            {
806                return Err(SQLError::TypeMismatch(format!(
807                    "vector field `{table}.{field}` vector {ordinal} component {component} must be finite, got {value}"
808                )));
809            }
810        }
811        Ok(())
812    }
813
814    pub fn add_document_with_vectors(
815        &self,
816        table: &str,
817        doc_id: DocId,
818        document: Document,
819        vectors: BTreeMap<FieldName, Vec<f32>>,
820    ) -> Result<(), SQLError> {
821        let vector_values = vectors
822            .into_iter()
823            .map(|(field, vector)| (field, vec![vector]))
824            .collect();
825        self.add_document_with_vector_values(table, doc_id, document, vector_values)
826    }
827
828    pub fn add_document_with_vector_values(
829        &self,
830        table: &str,
831        doc_id: DocId,
832        document: Document,
833        vectors: BTreeMap<FieldName, Vec<Vec<f32>>>,
834    ) -> Result<(), SQLError> {
835        self.with_evaluating_row_write_transaction(
836            table,
837            doc_id,
838            uqa_sql::ast::LockStrength::ForUpdate,
839            |engine| {
840                engine.add_document_with_vector_values_inner(
841                    table,
842                    doc_id,
843                    document,
844                    vectors,
845                    uqa_execution::mutation::publication::InsertedIdentity::Unknown,
846                )
847            },
848        )
849    }
850
851    pub(crate) fn add_document_with_vector_values_inner(
852        &self,
853        table: &str,
854        doc_id: DocId,
855        document: Document,
856        vectors: BTreeMap<FieldName, Vec<Vec<f32>>>,
857        inserted: uqa_execution::mutation::publication::InsertedIdentity,
858    ) -> Result<(), SQLError> {
859        self.validate_vector_values(table, &vectors)?;
860        self.add_document_impl(table, doc_id, document, inserted)?;
861        for (field, vectors) in vectors {
862            self.add_vector_values_inner(table, doc_id, &field, vectors)?;
863        }
864        Ok(())
865    }
866
867    pub(crate) fn add_prepared_document_with_vector_values(
868        &self,
869        table: &str,
870        doc_id: DocId,
871        document: Document,
872        vectors: BTreeMap<FieldName, Vec<Vec<f32>>>,
873        inserted: uqa_execution::mutation::publication::InsertedIdentity,
874    ) -> Result<(), SQLError> {
875        self.with_inserted_row_write_transaction(table, doc_id, inserted, |engine| {
876            engine.add_prepared_document_with_vector_values_inner(
877                table, doc_id, document, vectors, inserted,
878            )
879        })
880    }
881
882    pub(crate) fn add_prepared_document_with_vector_values_deferred_fts(
883        &self,
884        table: &str,
885        doc_id: DocId,
886        document: Document,
887        vectors: BTreeMap<FieldName, Vec<Vec<f32>>>,
888        inserted: uqa_execution::mutation::publication::InsertedIdentity,
889    ) -> Result<(), SQLError> {
890        self.with_inserted_row_write_transaction(table, doc_id, inserted, |engine| {
891            engine.add_prepared_document_with_vector_values_deferred_fts_inner(
892                table, doc_id, document, vectors, inserted,
893            )
894        })
895    }
896
897    pub(crate) fn add_prepared_document_with_vector_values_deferred_fts_inner(
898        &self,
899        table: &str,
900        doc_id: DocId,
901        document: Document,
902        vectors: BTreeMap<FieldName, Vec<Vec<f32>>>,
903        inserted: uqa_execution::mutation::publication::InsertedIdentity,
904    ) -> Result<(), SQLError> {
905        self.validate_vector_values(table, &vectors)?;
906        self.add_prepared_document_without_fts_impl(table, doc_id, document, inserted)?;
907        for (field, vectors) in vectors {
908            self.add_vector_values_inner(table, doc_id, &field, vectors)?;
909        }
910        Ok(())
911    }
912
913    pub(crate) fn add_prepared_document_with_vector_values_inner(
914        &self,
915        table: &str,
916        doc_id: DocId,
917        document: Document,
918        vectors: BTreeMap<FieldName, Vec<Vec<f32>>>,
919        inserted: uqa_execution::mutation::publication::InsertedIdentity,
920    ) -> Result<(), SQLError> {
921        self.validate_vector_values(table, &vectors)?;
922        self.add_prepared_document_impl(table, doc_id, document, inserted)?;
923        for (field, vectors) in vectors {
924            self.add_vector_values_inner(table, doc_id, &field, vectors)?;
925        }
926        Ok(())
927    }
928
929    pub(crate) fn add_prepared_stored_document_with_vector_values_inner(
930        &self,
931        table: &str,
932        doc_id: DocId,
933        document: uqa_storage::StoredDocument,
934        vectors: BTreeMap<FieldName, Vec<Vec<f32>>>,
935        inserted: uqa_execution::mutation::publication::InsertedIdentity,
936    ) -> Result<(), SQLError> {
937        self.validate_vector_values(table, &vectors)?;
938        self.add_prepared_stored_document_impl(table, doc_id, document, inserted)?;
939        for (field, vectors) in vectors {
940            self.add_vector_values_inner(table, doc_id, &field, vectors)?;
941        }
942        Ok(())
943    }
944
945    pub fn create_default_table(
946        &self,
947        name: impl Into<String>,
948        fts_fields: Vec<FieldName>,
949    ) -> StorageBackendResult<()> {
950        self.create_table(name, standard_analyzer("english"), fts_fields)
951    }
952}
953mod diskann;