1use 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 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 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 #[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 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 #[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 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 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;