1use super::{
10 document_store_read_error, document_store_write_error, Arc, BTreeMap, DocId, Document, Engine,
11 FieldName, SQLError, TableState, Value,
12};
13use uqa_storage::{DocumentMetadata, DocumentStore, StoredDocument};
14
15enum CommandOverlayDocument {
16 Present(uqa_storage::StoredDocument),
17 Deleted,
18}
19
20mod exact_lookup;
21mod overlay;
22
23impl Engine {
24 pub(super) fn raw_command_visible_document(
25 &self,
26 table: &str,
27 state: &TableState,
28 doc_id: DocId,
29 ) -> Result<Option<StoredDocument>, SQLError> {
30 match self.command_overlay_document(table, doc_id)? {
31 Some(CommandOverlayDocument::Present(document)) => Ok(Some(document)),
32 Some(CommandOverlayDocument::Deleted) => Ok(None),
33 None => state
34 .document_store
35 .read()
36 .get_stored(doc_id)
37 .map_err(|error| document_store_read_error("read document", &error)),
38 }
39 }
40
41 pub(super) fn materialize_query_document(
42 columns: &[uqa_sql::ast::ColumnDef],
43 document: &mut StoredDocument,
44 ) -> Result<(), SQLError> {
45 crate::generated::materialize_virtual_generated_columns(columns, document.fields_mut())?;
46 if uqa_execution::query::document_projection::projection_uses_tuple_xmin(
47 uqa_sql::semantics::XMIN_COLUMN,
48 columns,
49 ) && !document
50 .fields()
51 .contains_key(uqa_sql::semantics::XMIN_COLUMN)
52 {
53 let xmin = document
54 .metadata()
55 .tuple_xmin()
56 .map_or(Value::Null, |xmin| Value::Int(i64::from(xmin)));
57 document
58 .fields_mut()
59 .insert(uqa_sql::semantics::XMIN_COLUMN.into(), xmin);
60 }
61 Ok(())
62 }
63
64 pub(crate) fn get_document_for_mutation(
66 &self,
67 table: &str,
68 doc_id: DocId,
69 ) -> Result<Option<Document>, SQLError> {
70 let state = self.require_table(table)?;
71 let mut document = self.raw_command_visible_document(table, &state, doc_id)?;
72 if let Some(document) = document.as_mut() {
73 crate::generated::materialize_virtual_generated_columns(
74 &state.columns.read(),
75 document.fields_mut(),
76 )?;
77 }
78 Ok(document.map(StoredDocument::into_fields))
79 }
80
81 pub(crate) fn get_query_document_metadata(
82 &self,
83 table: &str,
84 doc_id: DocId,
85 ) -> Result<Option<DocumentMetadata>, SQLError> {
86 let table_state = self.require_query_table(table)?;
87 self.raw_command_visible_document(table, &table_state, doc_id)
88 .map(|document| document.map(|document| document.metadata()))
89 }
90
91 pub(crate) fn get_committed_document(
93 &self,
94 table: &str,
95 doc_id: DocId,
96 ) -> Result<Option<StoredDocument>, SQLError> {
97 let Some(provider) = self.storage.provider.as_ref() else {
98 let state = self.require_table(table)?;
99 let mut document = self.raw_command_visible_document(table, &state, doc_id)?;
100 if let Some(document) = document.as_mut() {
101 crate::generated::materialize_virtual_generated_columns(
102 &state.columns.read(),
103 document.fields_mut(),
104 )?;
105 }
106 return Ok(document);
107 };
108 let canonical = self
109 .try_resolve_table_name(table)
110 .map_err(|error| SQLError::Internal(format!("resolve table `{table}`: {error}")))?
111 .unwrap_or_else(|| table.to_string());
112 let session = provider.open_session().map_err(|error| {
113 SQLError::Internal(format!(
114 "open independent session to recheck `{canonical}` row {doc_id}: {error}"
115 ))
116 })?;
117 let mut document = session
118 .backend
119 .document_store(&canonical)
120 .get_stored(doc_id)
121 .map_err(|error| document_store_read_error("read latest committed document", &error))?;
122 if let Some(document) = document.as_mut() {
123 let table = self.require_table(&canonical)?;
124 crate::generated::materialize_virtual_generated_columns(
125 &table.columns.read(),
126 document.fields_mut(),
127 )?;
128 }
129 Ok(document)
130 }
131
132 pub(crate) fn committed_retrieval_entries(
134 &self,
135 table: &str,
136 predicate: &uqa_execution::ScalarExpr,
137 params: &[uqa_sql::SQLParam],
138 ) -> Result<Option<Vec<crate::ScoredEntry>>, SQLError> {
139 self.with_committed_retrieval(table, |session| {
140 crate::operator_tree_bridge::run_optimised(session, table, Some(predicate), params)
141 })
142 }
143
144 pub(crate) fn with_committed_retrieval<R>(
145 &self,
146 table: &str,
147 read: impl FnOnce(&Engine) -> Result<R, SQLError>,
148 ) -> Result<R, SQLError> {
149 if self.storage.provider.is_none() {
150 return read(self);
151 }
152 let session = self.new_internal_read_session().map_err(|error| {
153 SQLError::Internal(format!(
154 "open independent session to recheck retrieval on `{table}`: {error}"
155 ))
156 })?;
157 read(&session)
158 }
159
160 pub(crate) fn committed_knn_entries(
162 &self,
163 table: &str,
164 field: &str,
165 query_vector: &[f32],
166 top_k: usize,
167 ) -> Result<Vec<crate::ScoredEntry>, SQLError> {
168 if self.storage.provider.is_none() {
169 return self.knn_search_leaf(
170 table,
171 field,
172 query_vector,
173 top_k,
174 self.runtime.diagnostics.capture().as_ref(),
175 );
176 }
177 let session = self.new_internal_read_session().map_err(|error| {
178 SQLError::Internal(format!(
179 "open independent session to recheck vector retrieval on `{table}`: {error}"
180 ))
181 })?;
182 session.knn_search_leaf(
183 table,
184 field,
185 query_vector,
186 top_k,
187 self.runtime.diagnostics.capture().as_ref(),
188 )
189 }
190
191 pub(crate) fn get_documents_with_materialized_projection(
193 &self,
194 table: &str,
195 doc_ids: &[DocId],
196 projection: &[String],
197 ) -> Result<BTreeMap<DocId, Document>, SQLError> {
198 let t = self.require_table(table)?;
199 let columns = t.columns.read().clone();
200 let mut documents = t
201 .document_store
202 .read()
203 .get_stored_many(doc_ids)
204 .map_err(|error| {
205 document_store_read_error("read generated document projection", &error)
206 })?;
207 if let Some(changes) = self.command_overlay_changes(table)? {
208 for doc_id in doc_ids {
209 if !changes.contains_change(*doc_id).map_err(|error| {
210 document_store_read_error("read private generated document projection", &error)
211 })? {
212 continue;
213 }
214 if let Some(document) = changes.get_stored(*doc_id).map_err(|error| {
215 document_store_read_error("read private generated document projection", &error)
216 })? {
217 documents.insert(*doc_id, document);
218 } else {
219 documents.remove(doc_id);
220 }
221 }
222 }
223 for document in documents.values_mut() {
224 crate::generated::materialize_projected_virtual_generated_columns(
225 &columns,
226 document.fields_mut(),
227 projection,
228 )?;
229 if uqa_execution::query::document_projection::projections_use_tuple_xmin(
230 projection, &columns,
231 ) && !document
232 .fields()
233 .contains_key(uqa_sql::semantics::XMIN_COLUMN)
234 {
235 let xmin = document
236 .metadata()
237 .tuple_xmin()
238 .map_or(Value::Null, |xmin| Value::Int(i64::from(xmin)));
239 document
240 .fields_mut()
241 .insert(uqa_sql::semantics::XMIN_COLUMN.into(), xmin);
242 }
243 }
244 Ok(documents
245 .into_iter()
246 .map(|(doc_id, document)| (doc_id, document.into_fields()))
247 .collect())
248 }
249
250 pub(crate) fn get_query_document_fields_multi(
251 &self,
252 table: &str,
253 doc_ids: &[DocId],
254 fields: &[&str],
255 ) -> Result<BTreeMap<DocId, Vec<Value>>, SQLError> {
256 let table_state = self.require_query_table(table)?;
257 let columns = table_state.columns.read().clone();
258 let changes = self.command_overlay_changes(table)?;
259 let changes_error =
260 |error| document_store_read_error("read private document projection", &error);
261 let mut persisted_ids = Vec::with_capacity(doc_ids.len());
262 let mut private_ids = Vec::new();
263 for id in doc_ids.iter().copied() {
264 match changes
265 .as_ref()
266 .map(|changes| changes.change_presence(id))
267 .transpose()
268 .map_err(changes_error)?
269 .flatten()
270 {
271 None => persisted_ids.push(id),
272 Some(true) => private_ids.push(id),
273 Some(false) => {}
274 }
275 }
276 let mut projected = uqa_execution::query::document_projection::read_document_projection(
277 &**table_state.document_store.read(),
278 &persisted_ids,
279 fields,
280 &columns,
281 )?;
282 if let Some(changes) = changes {
283 projected.extend(
284 uqa_execution::query::document_projection::read_document_projection(
285 &changes,
286 &private_ids,
287 fields,
288 &columns,
289 )?,
290 );
291 }
292 Ok(projected)
293 }
294
295 pub(crate) fn get_document_fields(
296 &self,
297 table: &str,
298 doc_ids: &[DocId],
299 field: &str,
300 ) -> Result<BTreeMap<DocId, Value>, SQLError> {
301 let rows = self.get_query_document_fields_multi(table, doc_ids, &[field])?;
302 let mut out = BTreeMap::new();
303 for (doc_id, mut values) in rows {
304 if values.len() != 1 {
305 return Err(SQLError::Internal(format!(
306 "read document field returned {} projected values for document {doc_id}; expected 1",
307 values.len()
308 )));
309 }
310 out.insert(doc_id, values.remove(0));
311 }
312 Ok(out)
313 }
314
315 pub fn update_document_fields(
322 &self,
323 table: &str,
324 doc_id: DocId,
325 updates: BTreeMap<String, Value>,
326 vectors: BTreeMap<String, Vec<f32>>,
327 ) -> Result<bool, SQLError> {
328 let vector_values = vectors
329 .into_iter()
330 .map(|(field, vector)| (field, vec![vector]))
331 .collect();
332 self.update_document_fields_with_vector_values(table, doc_id, updates, vector_values)
333 }
334
335 pub fn update_document_fields_with_vector_values(
336 &self,
337 table: &str,
338 doc_id: DocId,
339 updates: BTreeMap<String, Value>,
340 vectors: BTreeMap<String, Vec<Vec<f32>>>,
341 ) -> Result<bool, SQLError> {
342 let columns = updates.keys().cloned().collect::<Vec<_>>();
343 let strength =
344 uqa_execution::query::locking::context::update_lock_strength(self, table, &columns);
345 self.with_evaluating_row_write_transaction(table, doc_id, strength, |engine| {
346 engine.update_document_fields_with_vector_values_inner(table, doc_id, updates, vectors)
347 })
348 }
349
350 pub(super) fn update_document_fields_with_vector_values_inner(
351 &self,
352 table: &str,
353 doc_id: DocId,
354 updates: BTreeMap<String, Value>,
355 vectors: BTreeMap<String, Vec<Vec<f32>>>,
356 ) -> Result<bool, SQLError> {
357 let Some(t) = self
358 .try_table(table)
359 .map_err(|error| SQLError::Internal(format!("resolve table `{table}`: {error}")))?
360 else {
361 return Err(SQLError::UnknownTable(table.to_string()));
362 };
363 if let Some(read) = self.serializable_table_state_read(&t)? {
364 read.observe_row(doc_id)?;
365 }
366 let Some(mut doc) = t
367 .document_store
368 .read()
369 .get(doc_id)
370 .map_err(|error| document_store_read_error("read document for update", &error))?
371 else {
372 return Ok(false);
373 };
374 self.validate_vector_values(table, &vectors)?;
375 for (k, v) in updates {
376 doc.insert(k, v);
377 }
378 let mut replacement_vectors = Self::document_vector_values(&t, &doc)?;
379 for (field, values) in vectors {
380 replacement_vectors.insert(field, values);
381 }
382 self.add_document_with_vector_values_inner(
386 table,
387 doc_id,
388 doc,
389 replacement_vectors,
390 uqa_execution::mutation::publication::InsertedIdentity::Unknown,
391 )?;
392 Ok(true)
393 }
394
395 pub fn patch_document_fields(
399 &self,
400 table: &str,
401 doc_id: DocId,
402 updates: &BTreeMap<String, Value>,
403 vectors: &BTreeMap<String, Vec<f32>>,
404 ) -> Result<bool, SQLError> {
405 let vector_values: BTreeMap<String, Vec<Vec<f32>>> = vectors
406 .iter()
407 .map(|(field, vector)| (field.clone(), vec![vector.clone()]))
408 .collect();
409 self.patch_document_fields_with_vector_values(table, doc_id, updates, &vector_values)
410 }
411
412 pub fn patch_document_fields_with_vector_values(
413 &self,
414 table: &str,
415 doc_id: DocId,
416 updates: &BTreeMap<String, Value>,
417 vectors: &BTreeMap<String, Vec<Vec<f32>>>,
418 ) -> Result<bool, SQLError> {
419 let columns = updates.keys().cloned().collect::<Vec<_>>();
420 let strength =
421 uqa_execution::query::locking::context::update_lock_strength(self, table, &columns);
422 self.with_evaluating_row_write_transaction(table, doc_id, strength, |engine| {
423 engine.patch_document_fields_with_vector_values_inner(table, doc_id, updates, vectors)
424 })
425 }
426
427 pub(super) fn patch_document_fields_with_vector_values_inner(
428 &self,
429 table: &str,
430 doc_id: DocId,
431 updates: &BTreeMap<String, Value>,
432 vectors: &BTreeMap<String, Vec<Vec<f32>>>,
433 ) -> Result<bool, SQLError> {
434 let Some(t) = self
435 .try_table(table)
436 .map_err(|error| SQLError::Internal(format!("resolve table `{table}`: {error}")))?
437 else {
438 return Err(SQLError::UnknownTable(table.to_string()));
439 };
440 if let Some(read) = self.serializable_table_state_read(&t)? {
441 read.observe_row(doc_id)?;
442 }
443 let Some(mut document) = self
444 .raw_command_visible_document(table, &t, doc_id)?
445 .map(StoredDocument::into_fields)
446 else {
447 return Ok(false);
448 };
449 self.validate_vector_values(table, vectors)?;
450 for (field, value) in updates {
451 if matches!(value, Value::Null) {
452 document.remove(field);
453 } else {
454 document.insert(field.clone(), value.clone());
455 }
456 }
457
458 let vector_fields = t.vector_indexes.read().keys().cloned().collect::<Vec<_>>();
459 let mut replacement_vectors = vectors.clone();
460 for field in vector_fields {
461 if !updates.contains_key(&field) || replacement_vectors.contains_key(&field) {
462 continue;
463 }
464 let values = match document.get(&field) {
465 Some(value) => Self::field_index_vectors(&t, &field, value)?.unwrap_or_default(),
466 None => Vec::new(),
467 };
468 replacement_vectors.insert(field, values);
469 }
470
471 self.add_document_with_vector_values_inner(
477 table,
478 doc_id,
479 document,
480 replacement_vectors,
481 uqa_execution::mutation::publication::InsertedIdentity::Unknown,
482 )?;
483 Ok(true)
484 }
485
486 pub(crate) fn rewrite_prepared_document(
488 &self,
489 table: &str,
490 doc_id: DocId,
491 document: Document,
492 ) -> Result<(), SQLError> {
493 self.rewrite_prepared_document_with_fts(table, doc_id, document, true)
494 }
495
496 pub(crate) fn rewrite_prepared_document_deferred_fts(
497 &self,
498 table: &str,
499 doc_id: DocId,
500 document: Document,
501 ) -> Result<(), SQLError> {
502 self.rewrite_prepared_document_with_fts(table, doc_id, document, false)
503 }
504
505 fn rewrite_prepared_document_with_fts(
506 &self,
507 table: &str,
508 doc_id: DocId,
509 document: Document,
510 index_fts: bool,
511 ) -> Result<(), SQLError> {
512 let table_name = self
513 .try_resolve_table_name(table)
514 .map_err(|error| SQLError::Internal(format!("resolve table `{table}`: {error}")))?
515 .ok_or_else(|| SQLError::UnknownTable(table.to_string()))?;
516 let table_state = self
517 .try_table(&table_name)
518 .map_err(|error| SQLError::Internal(format!("resolve table `{table}`: {error}")))?
519 .ok_or_else(|| SQLError::UnknownTable(table_name.clone()))?;
520 let mut vectors = Self::document_vector_values(&table_state, &document)?;
521 if !vectors.is_empty() {
525 let control = self.query_retention_control()?;
526 let indexes = table_state.vector_indexes.read();
527 let mut unchanged = Vec::new();
528 for (field, values) in &vectors {
529 if let Some(index) = indexes.get(field) {
530 let same = index
531 .matches_document_vectors(doc_id, values, &control)
532 .map_err(|error| {
533 uqa_execution::storage_errors::storage_error(
534 "compare document vectors",
535 &error,
536 )
537 })?;
538 if same {
539 unchanged.push(field.clone());
540 }
541 }
542 }
543 for field in unchanged {
544 vectors.remove(&field);
545 }
546 }
547 self.with_prepared_row_write_transaction(&table_name, |engine| {
548 if index_fts {
549 engine.add_prepared_document_with_vector_values_inner(
550 &table_name,
551 doc_id,
552 document,
553 vectors,
554 uqa_execution::mutation::publication::InsertedIdentity::Unknown,
555 )
556 } else {
557 engine.add_prepared_document_with_vector_values_deferred_fts_inner(
558 &table_name,
559 doc_id,
560 document,
561 vectors,
562 uqa_execution::mutation::publication::InsertedIdentity::Unknown,
563 )
564 }
565 })
566 }
567
568 pub(crate) fn rewrite_document_for_schema_change(
574 &self,
575 table: &str,
576 doc_id: DocId,
577 document: Document,
578 ) -> Result<(), SQLError> {
579 let table_name = self
580 .try_resolve_table_name(table)
581 .map_err(|error| SQLError::Internal(format!("resolve table `{table}`: {error}")))?
582 .ok_or_else(|| SQLError::UnknownTable(table.to_string()))?;
583 let t = self
584 .try_table(&table_name)
585 .map_err(|error| SQLError::Internal(format!("resolve table `{table}`: {error}")))?
586 .ok_or_else(|| SQLError::UnknownTable(table_name.clone()))?;
587 let vector_fields: Vec<FieldName> = t.vector_indexes.read().keys().cloned().collect();
588 let mut vectors: BTreeMap<FieldName, Vec<Vec<f32>>> = BTreeMap::new();
589 for field in vector_fields {
590 let Some(value) = document.get(&field) else {
591 continue;
592 };
593 if let Some(values) = Self::field_index_vectors(&t, &field, value)? {
594 vectors.insert(field, values);
595 }
596 }
597 let mut text_fields: BTreeMap<FieldName, String> = BTreeMap::new();
598 for field in t.fts_fields() {
599 if let Some(Value::Str(value)) = document.get(&field) {
600 text_fields.insert(field, value.clone());
601 }
602 }
603 {
604 let mut store = t.document_store.write();
605 let metadata = store
606 .get_metadata(doc_id)
607 .map_err(|err| document_store_read_error("read tuple metadata for schema rewrite", &err))?
608 .ok_or_else(|| {
609 SQLError::Internal(format!(
610 "table `{table_name}` listed document {doc_id} for a schema rewrite but omitted its tuple metadata"
611 ))
612 })?;
613 store
614 .put_stored(doc_id, StoredDocument::with_metadata(document, metadata))
615 .map_err(|err| document_store_write_error(&err))?;
616 }
617 uqa_execution::serializable::text::add_document(
618 self,
619 &table_name,
620 t.columns.snapshot(),
621 t.inverted_index.write().as_mut(),
622 doc_id,
623 text_fields,
624 )?;
625 for (field, index) in t
626 .vector_indexes
627 .write()
628 .live_mut()
629 .map_err(|error| {
630 uqa_execution::storage_errors::storage_error("write vector registrations", &error)
631 })?
632 .iter_mut()
633 {
634 index
635 .add_many(doc_id, vectors.remove(field).unwrap_or_default())
636 .map_err(|error| SQLError::Internal(format!("index document vector: {error}")))?;
637 }
638 self.mark_row_write(&table_name, &t, super::DocumentCountChange::Unchanged)
639 .map_err(|err| SQLError::Internal(format!("invalidate column stats: {err}")))?;
640 self.note_row_changed(&table_name, doc_id)?;
641 self.publish_command_document(&table_name, doc_id)?;
642 Ok(())
643 }
644
645 pub fn delete_document(&self, table: &str, doc_id: DocId) -> Result<(), SQLError> {
646 self.with_implicit_row_write_transaction(
647 table,
648 doc_id,
649 uqa_sql::ast::LockStrength::ForUpdate,
650 |engine| engine.delete_document_inner(table, doc_id),
651 )
652 }
653
654 pub(super) fn delete_document_inner(&self, table: &str, doc_id: DocId) -> Result<(), SQLError> {
655 self.delete_document_with_text(table, doc_id, true)
656 }
657
658 pub(crate) fn delete_prepared_document_deferred_fts(
659 &self,
660 table: &str,
661 doc_id: DocId,
662 ) -> Result<(), SQLError> {
663 self.with_prepared_row_write_transaction(table, |engine| {
664 engine.delete_document_with_text(table, doc_id, false)
665 })
666 }
667
668 fn delete_document_with_text(
669 &self,
670 table: &str,
671 doc_id: DocId,
672 index_text: bool,
673 ) -> Result<(), SQLError> {
674 let table_name = self
675 .try_resolve_table_name(table)
676 .map_err(|error| SQLError::Internal(format!("resolve table `{table}`: {error}")))?
677 .ok_or_else(|| SQLError::UnknownTable(table.to_string()))?;
678 let t = self
679 .try_table(&table_name)
680 .map_err(|error| SQLError::Internal(format!("resolve table `{table}`: {error}")))?
681 .ok_or_else(|| SQLError::UnknownTable(table_name.clone()))?;
682 if let Some(read) = self.serializable_table_state_read(&t)? {
683 read.observe_row(doc_id)?;
684 }
685 let existed = t
686 .document_store
687 .read()
688 .get(doc_id)
689 .map_err(|err| document_store_write_error(&err))?
690 .is_some();
691 if existed {
692 uqa_execution::serializable::observe_row_write(self, &table_name, doc_id)?;
693 }
694 let old_indexed = self.value_indexes_old_values(&t, doc_id)?;
695 self.observe_value_index_write(
696 &table_name,
697 &t,
698 doc_id,
699 existed,
700 old_indexed.as_ref(),
701 None,
702 )?;
703 for (field, index) in t.vector_indexes.read().iter() {
704 uqa_execution::serializable::vector::observe_write(
705 self,
706 &table_name,
707 &t.columns.snapshot(),
708 field,
709 index,
710 doc_id,
711 uqa_execution::serializable::vector::VectorChange::Delete,
712 )?;
713 }
714 let mut store = t.document_store.write();
715 store
716 .delete(doc_id)
717 .map_err(|err| document_store_write_error(&err))?;
718 self.persist_value_indexes_apply_write(&table_name, doc_id, None, None)?;
719 if old_indexed.is_some() {
720 self.value_indexes_apply_write(&t, doc_id, None)?;
721 }
722 drop(store);
723 if index_text {
724 uqa_execution::serializable::text::remove_document(
725 self,
726 &table_name,
727 t.columns.snapshot(),
728 t.inverted_index.write().as_mut(),
729 doc_id,
730 )?;
731 }
732 for idx in t
733 .vector_indexes
734 .write()
735 .live_mut()
736 .map_err(|error| {
737 uqa_execution::storage_errors::storage_error("write vector registrations", &error)
738 })?
739 .values_mut()
740 {
741 idx.as_mut()
742 .delete(doc_id)
743 .map_err(|error| SQLError::Internal(format!("delete indexed vector: {error}")))?;
744 }
745 let documents = if existed {
746 super::DocumentCountChange::Removed
747 } else {
748 super::DocumentCountChange::Unchanged
749 };
750 self.mark_row_write(&table_name, &t, documents)
751 .map_err(|err| SQLError::Internal(format!("invalidate column stats: {err}")))?;
752 if existed {
753 self.note_row_deleted(&table_name, doc_id)?;
754 }
755 self.publish_command_document(&table_name, doc_id)?;
757 Ok(())
758 }
759}
760
761#[cfg(test)]
762mod tests;