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