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        if persistence == uqa_sql::ast::RelationPersistence::Temporary {
220            return self.create_resolved_table(
221                name,
222                analyzer,
223                fts_fields,
224                persistence,
225                on_commit,
226                owner,
227                catalog_oids,
228            );
229        }
230        let name = name.to_string();
231        self.with_implicit_storage_transaction(move |engine| {
232            engine.create_resolved_table(
233                &name,
234                analyzer,
235                fts_fields,
236                persistence,
237                on_commit,
238                owner,
239                catalog_oids,
240            )
241        })
242    }
243
244    /// Create a table named through the API, whose name resolves among the durable schemas.
245    fn create_table_inner(
246        &self,
247        raw_name: &str,
248        analyzer: Analyzer,
249        fts_fields: Vec<FieldName>,
250        persistence: uqa_sql::ast::RelationPersistence,
251        on_commit: uqa_sql::ast::OnCommitAction,
252        owner: &uqa_execution::catalog::security::roles::locking::RoleBinding,
253    ) -> StorageBackendResult<()> {
254        let name = self.relation_creation_context().api_name(raw_name)?;
255        self.create_resolved_table(
256            &name,
257            analyzer,
258            fts_fields,
259            persistence,
260            on_commit,
261            owner,
262            None,
263        )
264    }
265
266    /// 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.
267    #[expect(
268        clippy::too_many_arguments,
269        reason = "the lifecycle attributes and the OIDs a statement allocated are set once at creation"
270    )]
271    fn create_resolved_table(
272        &self,
273        name: &str,
274        analyzer: Analyzer,
275        fts_fields: Vec<FieldName>,
276        persistence: uqa_sql::ast::RelationPersistence,
277        on_commit: uqa_sql::ast::OnCommitAction,
278        owner: &uqa_execution::catalog::security::roles::locking::RoleBinding,
279        catalog_oids: Option<uqa_sql::catalog::relation_oids::RelationCatalogOids>,
280    ) -> StorageBackendResult<()> {
281        let relation = Self::resolved_relation_identity(name)?;
282        if let Some(kind) = self.relation_kind_at(name)? {
283            return Err(StorageBackendError::Other(format!(
284                "relation `{name}` already exists as {kind}"
285            )));
286        }
287        let default_revision = (!fts_fields.is_empty())
288            .then(|| analyzer.compile())
289            .transpose()?;
290        let analyzer = match &default_revision {
291            Some(revision) => revision.descriptor().configuration()?,
292            None => analyzer,
293        };
294        let (docs, inv): (Box<dyn DocumentStore>, Box<dyn InvertedIndex>) = if let Some(backend) =
295            self.storage
296                .backend
297                .as_ref()
298                .filter(|_| persistence != uqa_sql::ast::RelationPersistence::Temporary)
299        {
300            (
301                backend.document_store(name),
302                backend.inverted_index(name, analyzer.clone()),
303            )
304        } else {
305            (
306                Box::new(MemoryDocumentStore::new()),
307                Box::new(MemoryInvertedIndex::new(analyzer.clone())),
308            )
309        };
310        self.relation_creation_context()
311            .retain_owner(owner)
312            .map_err(|error| StorageBackendError::backend("CREATE TABLE owner", error))?;
313        let catalog_oids = if let Some(catalog_oids) = catalog_oids {
314            catalog_oids
315        } else {
316            self.relation_creation_context()
317                .reserve_row_type_name(name)
318                .map_err(|error| StorageBackendError::backend("CREATE TABLE name", error))?;
319            self.catalog_identity_reservation_context()
320                .allocator(uqa_execution::catalog::identity::allocate_catalog_object_id)
321                .allocate_relation_oids(
322                    uqa_sql::catalog::relation_oids::RelationOidKind::Table,
323                    &relation,
324                )
325                .map_err(|error| StorageBackendError::backend("CREATE TABLE OIDs", error))?
326        };
327        let row_type_array_name = uqa_execution::schema::types::arrays::reserve_array_name(
328            &self.relation_creation_context(),
329            &relation.schema,
330            &relation.name,
331        )
332        .map_err(|error| StorageBackendError::backend("CREATE TABLE array type", error))?;
333        let table = TableState {
334            lifecycle_id: std::sync::atomic::AtomicU64::new(crate::next_table_lifecycle_id()),
335            object_id: crate::new_table_object_id()?,
336            security: crate::state::CatalogCell::new(BoundTableSecurity::owner(owner.identity())),
337            storage_generation: RwLock::new(crate::new_table_storage_generation()?),
338            document_store: RwLock::new(docs),
339            inverted_index: RwLock::new(inv),
340            vector_indexes: RwLock::new(uqa_storage::vector_index::VectorIndexes::default()),
341            fts_fields: crate::state::CatalogCell::new(fts_fields),
342            columns: crate::state::CatalogCell::new(Vec::new()),
343            columns_declared: crate::state::CatalogCell::new(false),
344            next_id: parking_lot::Mutex::new(1),
345            maps_integer_keys: AtomicBool::new(true),
346            analyzer: crate::state::CatalogCell::new(analyzer),
347            column_stats: crate::state::CatalogCell::new(BTreeMap::new()),
348            column_stats_loaded: AtomicBool::new(true),
349            column_stats_dirty: AtomicBool::new(true),
350            statistics_maintenance: parking_lot::Mutex::default(),
351            table_checks: crate::state::CatalogCell::new(Vec::new()),
352            foreign_keys: crate::state::CatalogCell::new(Vec::new()),
353            key_constraints: crate::state::CatalogCell::new(Vec::new()),
354            hierarchy: crate::state::CatalogCell::new(uqa_sql::ast::TableHierarchy::default()),
355            value_indexes: RwLock::new(BTreeMap::new()),
356            doc_count_cache: std::sync::atomic::AtomicU64::new(0),
357            doc_count_dirty: AtomicBool::new(true),
358            persistence,
359            on_commit,
360            catalog_oids: Some(catalog_oids),
361            row_type_array_name: crate::state::CatalogCell::new(Some(row_type_array_name)),
362            dropped_attributes: crate::state::CatalogCell::new(Vec::new()),
363        };
364        let table_arc = Arc::new(table);
365        if self.is_persistent() && persistence != uqa_sql::ast::RelationPersistence::Temporary {
366            self.try_save_table_schema(name, &table_arc)?;
367        }
368        let analyzer_bindings =
369            self.initialize_table_analyzer_bindings(name, &table_arc, default_revision)?;
370        self.note_prepared_table_change(&table_arc);
371        self.storage.tables.write().insert(relation, table_arc);
372        self.durable
373            .table_field_analyzers
374            .write()
375            .extend(analyzer_bindings);
376        self.clear_regtype_output_cache();
377        if persistence == uqa_sql::ast::RelationPersistence::Temporary {
378            self.note_table_catalog_changed();
379        }
380        Ok(())
381    }
382
383    /// Register a vector field on a table. Existing document values in the
384    /// same field are indexed immediately; later calls to [`Engine::add_vector`]
385    /// or [`Engine::add_document_with_vectors`] keep it current. `CREATE INDEX
386    /// ... USING ivf` or `CREATE INDEX ... USING hnsw` upgrades the field to
387    /// the corresponding approximate backend.
388    pub fn create_vector_field(
389        &self,
390        table: &str,
391        field: impl Into<FieldName>,
392        dimensions: u32,
393    ) -> StorageBackendResult<bool> {
394        let field = field.into();
395        self.with_implicit_storage_definition_transaction(|engine| {
396            engine.install_vector_field(
397                table,
398                field,
399                dimensions,
400                VectorIndexSpec::BruteForce,
401                false,
402                true,
403            )
404        })
405    }
406
407    pub(crate) fn rebuild_vector_field_with_spec(
408        &self,
409        table: &str,
410        field: impl Into<FieldName>,
411        dimensions: u32,
412        spec: VectorIndexSpec,
413    ) -> StorageBackendResult<bool> {
414        let field = field.into();
415        self.with_implicit_storage_transaction(|engine| {
416            engine.rebuild_vector_field_in_transaction(table, field, dimensions, spec)
417        })
418    }
419
420    pub(crate) fn rebuild_vector_field_in_transaction(
421        &self,
422        table: &str,
423        field: impl Into<FieldName>,
424        dimensions: u32,
425        spec: VectorIndexSpec,
426    ) -> StorageBackendResult<bool> {
427        self.install_vector_field(table, field.into(), dimensions, spec, true, true)
428    }
429
430    pub(crate) fn rebuild_vector_field(
431        &self,
432        table: &str,
433        field: impl Into<FieldName>,
434        dimensions: u32,
435    ) -> StorageBackendResult<bool> {
436        self.rebuild_vector_field_with_spec(table, field, dimensions, VectorIndexSpec::BruteForce)
437    }
438
439    pub(crate) fn drop_vector_field_index(
440        &self,
441        table: &str,
442        field: impl Into<FieldName>,
443        dimensions: u32,
444    ) -> StorageBackendResult<bool> {
445        self.rebuild_vector_field(table, field, dimensions)
446    }
447
448    pub(crate) fn drop_vector_index_metadata(
449        &self,
450        table: &str,
451        field: &str,
452    ) -> StorageBackendResult<()> {
453        if let Some(backend) = self.storage.backend.as_ref() {
454            backend.drop_vector_index_metadata(table, field)?;
455        }
456        Ok(())
457    }
458
459    pub(crate) fn restore_vector_field_index(
460        &self,
461        table: &str,
462        field: impl Into<FieldName>,
463        dimensions: u32,
464        spec: VectorIndexSpec,
465    ) -> StorageBackendResult<bool> {
466        let t = self
467            .try_table(table)?
468            .ok_or_else(|| StorageBackendError::Other(format!("table `{table}` does not exist")))?;
469        let field = field.into();
470        let idx = self.build_vector_index_for_restore(table, &field, dimensions, spec)?;
471        t.vector_indexes.write().live_mut()?.insert(field, idx);
472        Ok(true)
473    }
474
475    pub(crate) fn restore_fts_field_from_catalog(
476        &self,
477        table: &str,
478        field: &str,
479        analyzer: Option<&str>,
480    ) -> Result<(), String> {
481        let t = self
482            .try_table(table)
483            .map_err(|err| format!("resolve table `{table}`: {err}"))?
484            .ok_or_else(|| format!("unknown table `{table}`"))?;
485        if let Some(analyzer_name) = analyzer {
486            let bindings = self.durable.table_field_analyzers.read();
487            let binding = bindings
488                .get(&(table.to_owned(), field.to_owned()))
489                .ok_or_else(|| "GIN field has no restored analyzer binding".to_owned())?;
490            if binding.owner != uqa_storage::AnalyzerBindingOwner::Gin
491                || binding.index.name.as_deref() != Some(analyzer_name.trim())
492            {
493                return Err("GIN field conflicts with restored analyzer ownership".into());
494            }
495        }
496        {
497            let mut fts = t.fts_fields.write();
498            if !fts.iter().any(|f| f == field) {
499                fts.push(field.to_string());
500            }
501        }
502        Ok(())
503    }
504
505    fn install_vector_field(
506        &self,
507        table: &str,
508        field: FieldName,
509        dimensions: u32,
510        spec: VectorIndexSpec,
511        replace_existing: bool,
512        persist_schema: bool,
513    ) -> StorageBackendResult<bool> {
514        let Some(table_name) = self.try_resolve_table_name(table)? else {
515            return Err(StorageBackendError::Other(format!(
516                "table `{table}` does not exist"
517            )));
518        };
519        let Some(t) = self.try_table(&table_name)? else {
520            return Err(StorageBackendError::Other(format!(
521                "table `{table_name}` disappeared while installing vector field `{field}`"
522            )));
523        };
524        if !replace_existing {
525            if let Some(existing) = t.vector_indexes.read().get(&field) {
526                let existing_dimensions = existing.dimensions();
527                if existing_dimensions == dimensions {
528                    return Ok(false);
529                }
530                return Err(StorageBackendError::Other(format!(
531                    "vector field `{table_name}.{field}` has dimension {existing_dimensions}, requested {dimensions}"
532                )));
533            }
534        }
535        let mut idx = self.build_vector_index(&table_name, &field, dimensions, spec)?;
536        if idx.count()? == 0 {
537            Self::backfill_vector_index(&t, &field, idx.as_mut())?;
538        }
539        idx.initialize()?;
540        let old = t
541            .vector_indexes
542            .write()
543            .live_mut()?
544            .insert(field.clone(), idx);
545        if persist_schema && self.is_persistent() {
546            if let Err(err) = self.try_save_table_schema(&table_name, &t) {
547                let mut vectors = t.vector_indexes.write();
548                let indexes = vectors.live_mut()?;
549                indexes.remove(&field);
550                if let Some(old) = old {
551                    indexes.insert(field, old);
552                }
553                return Err(err);
554            }
555        }
556        Ok(true)
557    }
558
559    fn build_vector_index(
560        &self,
561        table: &str,
562        field: &str,
563        dimensions: u32,
564        spec: VectorIndexSpec,
565    ) -> StorageBackendResult<Box<dyn VectorIndex>> {
566        self.build_vector_index_with_mode(
567            table,
568            field,
569            dimensions,
570            spec,
571            VectorIndexOpenMode::Create,
572        )
573    }
574
575    pub(crate) fn build_vector_index_for_restore(
576        &self,
577        table: &str,
578        field: &str,
579        dimensions: u32,
580        spec: VectorIndexSpec,
581    ) -> StorageBackendResult<Box<dyn VectorIndex>> {
582        self.build_vector_index_with_mode(
583            table,
584            field,
585            dimensions,
586            spec,
587            VectorIndexOpenMode::Restore,
588        )
589    }
590
591    pub(crate) fn build_vector_index_with_mode(
592        &self,
593        table: &str,
594        field: &str,
595        dimensions: u32,
596        spec: VectorIndexSpec,
597        mode: VectorIndexOpenMode,
598    ) -> StorageBackendResult<Box<dyn VectorIndex>> {
599        // Callers pass the canonical name after resolving the table. Looking
600        // it up in the already-loaded registry is essential during catalog
601        // restoration: a normal `try_table` lookup would recursively enter
602        // catalog synchronization while its mutex is already held.
603        if let VectorIndexSpec::DiskANN(parameters) = spec {
604            let row = uqa_execution::catalog::index::vectors::field_index(
605                self.durable.catalog_indexes.read().values(),
606                table,
607                field,
608            )?
609            .cloned()
610            .ok_or_else(|| {
611                StorageBackendError::Other("DiskANN field has no catalog index".into())
612            })?;
613            return self.build_catalog_diskann_index(&row, field, dimensions, parameters, mode);
614        }
615        let relation =
616            RelationIdentity::from_legacy_name(table).map_err(StorageBackendError::Other)?;
617        let temporary = self
618            .storage
619            .tables
620            .read()
621            .get(&relation)
622            .is_some_and(|table| table.persistence == uqa_sql::ast::RelationPersistence::Temporary);
623        if temporary {
624            Self::memory_vector_index(dimensions, spec)
625        } else if let Some(backend) = self.storage.backend.as_ref() {
626            backend.vector_index(table, field, dimensions, spec, mode)
627        } else {
628            Self::memory_vector_index(dimensions, spec)
629        }
630    }
631
632    fn memory_vector_index(
633        dimensions: u32,
634        spec: VectorIndexSpec,
635    ) -> StorageBackendResult<Box<dyn VectorIndex>> {
636        let index: Box<dyn VectorIndex> = match spec {
637            VectorIndexSpec::DiskANN(_) => {
638                return Err(StorageBackendError::Other(
639                    "DiskANN requires its retained resource and catalog binding".into(),
640                ))
641            }
642            VectorIndexSpec::BruteForce => Box::new(MemoryVectorIndex::new(dimensions)),
643            VectorIndexSpec::IVF(params) => Box::new(IVFIndex::with_params(
644                dimensions,
645                params.nlist,
646                params.nprobe,
647                params.train_threshold,
648            )),
649            VectorIndexSpec::HNSW(params) => Box::new(HNSWIndex::with_params(dimensions, params)?),
650        };
651        Ok(index)
652    }
653
654    fn backfill_vector_index(
655        table: &TableState,
656        field: &str,
657        idx: &mut dyn VectorIndex,
658    ) -> StorageBackendResult<()> {
659        let docs = table.document_store.read().snapshot()?;
660        for (doc_id, document) in docs.iter_all()? {
661            let Some(value) = document.get(field) else {
662                continue;
663            };
664            if let Some(vectors) = Self::field_index_vectors(table, field, value)
665                .map_err(|error| StorageBackendError::Other(error.to_string()))?
666            {
667                idx.add_many(doc_id, vectors)?;
668            }
669        }
670        Ok(())
671    }
672
673    pub fn add_vector(
674        &self,
675        table: &str,
676        doc_id: DocId,
677        field: &str,
678        vector: Vec<f32>,
679    ) -> Result<bool, SQLError> {
680        self.with_implicit_row_write_transaction(
681            table,
682            doc_id,
683            uqa_sql::ast::LockStrength::ForNoKeyUpdate,
684            |engine| engine.add_vector_inner(table, doc_id, field, vector),
685        )
686    }
687
688    fn add_vector_inner(
689        &self,
690        table: &str,
691        doc_id: DocId,
692        field: &str,
693        vector: Vec<f32>,
694    ) -> Result<bool, SQLError> {
695        let Some(t) = self
696            .try_table(table)
697            .map_err(|error| SQLError::Internal(format!("resolve table `{table}`: {error}")))?
698        else {
699            return Err(SQLError::UnknownTable(table.to_string()));
700        };
701        let mut registrations = t.vector_indexes.write();
702        let idxs = registrations.live_mut().map_err(|error| {
703            uqa_execution::storage_errors::storage_error("write vector registrations", &error)
704        })?;
705        let Some(idx) = idxs.get_mut(field) else {
706            return Err(SQLError::TypeMismatch(format!(
707                "vector field `{table}.{field}` is not registered"
708            )));
709        };
710        uqa_execution::serializable::vector::observe_write(
711            self,
712            table,
713            &t.columns.snapshot(),
714            field,
715            idx.as_ref(),
716            doc_id,
717            uqa_execution::serializable::vector::VectorChange::Single(&vector),
718        )?;
719        idx.as_mut()
720            .add(doc_id, vector)
721            .map_err(|error| SQLError::Internal(format!("index document vector: {error}")))?;
722        drop(registrations);
723        self.note_table_data_changed();
724        self.note_row_changed(table, doc_id)?;
725        Ok(true)
726    }
727
728    pub fn add_vector_values(
729        &self,
730        table: &str,
731        doc_id: DocId,
732        field: &str,
733        vectors: Vec<Vec<f32>>,
734    ) -> Result<bool, SQLError> {
735        self.with_implicit_row_write_transaction(
736            table,
737            doc_id,
738            uqa_sql::ast::LockStrength::ForNoKeyUpdate,
739            |engine| engine.add_vector_values_inner(table, doc_id, field, vectors),
740        )
741    }
742
743    fn add_vector_values_inner(
744        &self,
745        table: &str,
746        doc_id: DocId,
747        field: &str,
748        vectors: Vec<Vec<f32>>,
749    ) -> Result<bool, SQLError> {
750        let Some(t) = self
751            .try_table(table)
752            .map_err(|error| SQLError::Internal(format!("resolve table `{table}`: {error}")))?
753        else {
754            return Err(SQLError::UnknownTable(table.to_string()));
755        };
756        let mut registrations = t.vector_indexes.write();
757        let idxs = registrations.live_mut().map_err(|error| {
758            uqa_execution::storage_errors::storage_error("write vector registrations", &error)
759        })?;
760        let Some(idx) = idxs.get_mut(field) else {
761            return Err(SQLError::TypeMismatch(format!(
762                "vector field `{table}.{field}` is not registered"
763            )));
764        };
765        uqa_execution::serializable::vector::observe_write(
766            self,
767            table,
768            &t.columns.snapshot(),
769            field,
770            idx.as_ref(),
771            doc_id,
772            uqa_execution::serializable::vector::VectorChange::Tensor(&vectors),
773        )?;
774        idx.as_mut()
775            .add_many(doc_id, vectors)
776            .map_err(|error| SQLError::Internal(format!("index document vectors: {error}")))?;
777        drop(registrations);
778        self.note_table_data_changed();
779        self.note_row_changed(table, doc_id)?;
780        Ok(true)
781    }
782
783    pub(crate) fn validate_vector_values(
784        &self,
785        table: &str,
786        vectors: &BTreeMap<FieldName, Vec<Vec<f32>>>,
787    ) -> Result<(), SQLError> {
788        let Some(t) = self
789            .try_table(table)
790            .map_err(|error| SQLError::Internal(format!("resolve table `{table}`: {error}")))?
791        else {
792            return Err(SQLError::UnknownTable(table.to_string()));
793        };
794        let indexes = t.vector_indexes.read();
795        for (field, values) in vectors {
796            let Some(index) = indexes.get(field) else {
797                return Err(SQLError::UnknownColumn(format!("{table}.{field}")));
798            };
799            let expected = usize::try_from(index.dimensions()).map_err(|_| {
800                SQLError::TypeMismatch(format!(
801                    "vector field `{table}.{field}` dimension exceeds the platform usize range"
802                ))
803            })?;
804            if let Some(vector) = values.iter().find(|vector| vector.len() != expected) {
805                return Err(SQLError::VectorDimMismatch {
806                    expected,
807                    actual: vector.len(),
808                });
809            }
810            if let Some((ordinal, component, value)) =
811                values.iter().enumerate().find_map(|(ordinal, vector)| {
812                    vector
813                        .iter()
814                        .copied()
815                        .enumerate()
816                        .find(|(_, value)| !value.is_finite())
817                        .map(|(component, value)| (ordinal, component, value))
818                })
819            {
820                return Err(SQLError::TypeMismatch(format!(
821                    "vector field `{table}.{field}` vector {ordinal} component {component} must be finite, got {value}"
822                )));
823            }
824        }
825        Ok(())
826    }
827
828    pub fn add_document_with_vectors(
829        &self,
830        table: &str,
831        doc_id: DocId,
832        document: Document,
833        vectors: BTreeMap<FieldName, Vec<f32>>,
834    ) -> Result<(), SQLError> {
835        let vector_values = vectors
836            .into_iter()
837            .map(|(field, vector)| (field, vec![vector]))
838            .collect();
839        self.add_document_with_vector_values(table, doc_id, document, vector_values)
840    }
841
842    pub fn add_document_with_vector_values(
843        &self,
844        table: &str,
845        doc_id: DocId,
846        document: Document,
847        vectors: BTreeMap<FieldName, Vec<Vec<f32>>>,
848    ) -> Result<(), SQLError> {
849        self.with_implicit_row_write_transaction(
850            table,
851            doc_id,
852            uqa_sql::ast::LockStrength::ForUpdate,
853            |engine| {
854                engine.add_document_with_vector_values_inner(
855                    table,
856                    doc_id,
857                    document,
858                    vectors,
859                    uqa_execution::mutation::publication::InsertedIdentity::Unknown,
860                )
861            },
862        )
863    }
864
865    pub(crate) fn add_document_with_vector_values_inner(
866        &self,
867        table: &str,
868        doc_id: DocId,
869        document: Document,
870        vectors: BTreeMap<FieldName, Vec<Vec<f32>>>,
871        inserted: uqa_execution::mutation::publication::InsertedIdentity,
872    ) -> Result<(), SQLError> {
873        self.validate_vector_values(table, &vectors)?;
874        self.add_document_impl(table, doc_id, document, inserted)?;
875        for (field, vectors) in vectors {
876            self.add_vector_values_inner(table, doc_id, &field, vectors)?;
877        }
878        Ok(())
879    }
880
881    pub(crate) fn add_prepared_document_with_vector_values(
882        &self,
883        table: &str,
884        doc_id: DocId,
885        document: Document,
886        vectors: BTreeMap<FieldName, Vec<Vec<f32>>>,
887        inserted: uqa_execution::mutation::publication::InsertedIdentity,
888    ) -> Result<(), SQLError> {
889        self.with_inserted_row_write_transaction(table, doc_id, inserted, |engine| {
890            engine.add_prepared_document_with_vector_values_inner(
891                table, doc_id, document, vectors, inserted,
892            )
893        })
894    }
895
896    pub(crate) fn add_prepared_document_with_vector_values_deferred_fts(
897        &self,
898        table: &str,
899        doc_id: DocId,
900        document: Document,
901        vectors: BTreeMap<FieldName, Vec<Vec<f32>>>,
902        inserted: uqa_execution::mutation::publication::InsertedIdentity,
903    ) -> Result<(), SQLError> {
904        self.with_inserted_row_write_transaction(table, doc_id, inserted, |engine| {
905            engine.add_prepared_document_with_vector_values_deferred_fts_inner(
906                table, doc_id, document, vectors, inserted,
907            )
908        })
909    }
910
911    pub(crate) fn add_prepared_document_with_vector_values_deferred_fts_inner(
912        &self,
913        table: &str,
914        doc_id: DocId,
915        document: Document,
916        vectors: BTreeMap<FieldName, Vec<Vec<f32>>>,
917        inserted: uqa_execution::mutation::publication::InsertedIdentity,
918    ) -> Result<(), SQLError> {
919        self.validate_vector_values(table, &vectors)?;
920        self.add_prepared_document_without_fts_impl(table, doc_id, document, inserted)?;
921        for (field, vectors) in vectors {
922            self.add_vector_values_inner(table, doc_id, &field, vectors)?;
923        }
924        Ok(())
925    }
926
927    pub(crate) fn add_prepared_document_with_vector_values_inner(
928        &self,
929        table: &str,
930        doc_id: DocId,
931        document: Document,
932        vectors: BTreeMap<FieldName, Vec<Vec<f32>>>,
933        inserted: uqa_execution::mutation::publication::InsertedIdentity,
934    ) -> Result<(), SQLError> {
935        self.validate_vector_values(table, &vectors)?;
936        self.add_prepared_document_impl(table, doc_id, document, inserted)?;
937        for (field, vectors) in vectors {
938            self.add_vector_values_inner(table, doc_id, &field, vectors)?;
939        }
940        Ok(())
941    }
942
943    pub(crate) fn add_prepared_stored_document_with_vector_values_inner(
944        &self,
945        table: &str,
946        doc_id: DocId,
947        document: uqa_storage::StoredDocument,
948        vectors: BTreeMap<FieldName, Vec<Vec<f32>>>,
949        inserted: uqa_execution::mutation::publication::InsertedIdentity,
950    ) -> Result<(), SQLError> {
951        self.validate_vector_values(table, &vectors)?;
952        self.add_prepared_stored_document_impl(table, doc_id, document, inserted)?;
953        for (field, vectors) in vectors {
954            self.add_vector_values_inner(table, doc_id, &field, vectors)?;
955        }
956        Ok(())
957    }
958
959    pub fn create_default_table(
960        &self,
961        name: impl Into<String>,
962        fts_fields: Vec<FieldName>,
963    ) -> StorageBackendResult<()> {
964        self.create_table(name, standard_analyzer("english"), fts_fields)
965    }
966}
967mod diskann;