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 if self.storage.provider.is_none() {
140 return crate::operator_tree_bridge::run_optimised(
141 self,
142 table,
143 Some(predicate),
144 params,
145 );
146 }
147 let session = self.new_internal_read_session().map_err(|error| {
148 SQLError::Internal(format!(
149 "open independent session to recheck retrieval on `{table}`: {error}"
150 ))
151 })?;
152 crate::operator_tree_bridge::run_optimised(&session, table, Some(predicate), params)
153 }
154
155 pub(crate) fn committed_knn_entries(
157 &self,
158 table: &str,
159 field: &str,
160 query_vector: &[f32],
161 top_k: usize,
162 ) -> Result<Vec<crate::ScoredEntry>, SQLError> {
163 if self.storage.provider.is_none() {
164 return self.knn_search_leaf(
165 table,
166 field,
167 query_vector,
168 top_k,
169 self.runtime.diagnostics.capture().as_ref(),
170 );
171 }
172 let session = self.new_internal_read_session().map_err(|error| {
173 SQLError::Internal(format!(
174 "open independent session to recheck vector retrieval on `{table}`: {error}"
175 ))
176 })?;
177 session.knn_search_leaf(
178 table,
179 field,
180 query_vector,
181 top_k,
182 self.runtime.diagnostics.capture().as_ref(),
183 )
184 }
185
186 pub(crate) fn get_documents_with_materialized_projection(
188 &self,
189 table: &str,
190 doc_ids: &[DocId],
191 projection: &[String],
192 ) -> Result<BTreeMap<DocId, Document>, SQLError> {
193 let t = self.require_table(table)?;
194 let columns = t.columns.read().clone();
195 let mut documents = t
196 .document_store
197 .read()
198 .get_stored_many(doc_ids)
199 .map_err(|error| {
200 document_store_read_error("read generated document projection", &error)
201 })?;
202 if let Some(changes) = self.command_overlay_changes(table)? {
203 for doc_id in doc_ids {
204 if !changes.contains_change(*doc_id).map_err(|error| {
205 document_store_read_error("read private generated document projection", &error)
206 })? {
207 continue;
208 }
209 if let Some(document) = changes.get_stored(*doc_id).map_err(|error| {
210 document_store_read_error("read private generated document projection", &error)
211 })? {
212 documents.insert(*doc_id, document);
213 } else {
214 documents.remove(doc_id);
215 }
216 }
217 }
218 for document in documents.values_mut() {
219 crate::generated::materialize_projected_virtual_generated_columns(
220 &columns,
221 document.fields_mut(),
222 projection,
223 )?;
224 if uqa_execution::query::document_projection::projections_use_tuple_xmin(
225 projection, &columns,
226 ) && !document
227 .fields()
228 .contains_key(uqa_sql::semantics::XMIN_COLUMN)
229 {
230 let xmin = document
231 .metadata()
232 .tuple_xmin()
233 .map_or(Value::Null, |xmin| Value::Int(i64::from(xmin)));
234 document
235 .fields_mut()
236 .insert(uqa_sql::semantics::XMIN_COLUMN.into(), xmin);
237 }
238 }
239 Ok(documents
240 .into_iter()
241 .map(|(doc_id, document)| (doc_id, document.into_fields()))
242 .collect())
243 }
244
245 pub(crate) fn get_query_document_fields_multi(
246 &self,
247 table: &str,
248 doc_ids: &[DocId],
249 fields: &[&str],
250 ) -> Result<BTreeMap<DocId, Vec<Value>>, SQLError> {
251 let table_state = self.require_query_table(table)?;
252 let columns = table_state.columns.read().clone();
253 let changes = self.command_overlay_changes(table)?;
254 let changes_error =
255 |error| document_store_read_error("read private document projection", &error);
256 let mut persisted_ids = Vec::with_capacity(doc_ids.len());
257 let mut private_ids = Vec::new();
258 for id in doc_ids.iter().copied() {
259 match changes
260 .as_ref()
261 .map(|changes| changes.change_presence(id))
262 .transpose()
263 .map_err(changes_error)?
264 .flatten()
265 {
266 None => persisted_ids.push(id),
267 Some(true) => private_ids.push(id),
268 Some(false) => {}
269 }
270 }
271 let mut projected = uqa_execution::query::document_projection::read_document_projection(
272 &**table_state.document_store.read(),
273 &persisted_ids,
274 fields,
275 &columns,
276 )?;
277 if let Some(changes) = changes {
278 projected.extend(
279 uqa_execution::query::document_projection::read_document_projection(
280 &changes,
281 &private_ids,
282 fields,
283 &columns,
284 )?,
285 );
286 }
287 Ok(projected)
288 }
289
290 pub(crate) fn get_document_fields(
291 &self,
292 table: &str,
293 doc_ids: &[DocId],
294 field: &str,
295 ) -> Result<BTreeMap<DocId, Value>, SQLError> {
296 let rows = self.get_query_document_fields_multi(table, doc_ids, &[field])?;
297 let mut out = BTreeMap::new();
298 for (doc_id, mut values) in rows {
299 if values.len() != 1 {
300 return Err(SQLError::Internal(format!(
301 "read document field returned {} projected values for document {doc_id}; expected 1",
302 values.len()
303 )));
304 }
305 out.insert(doc_id, values.remove(0));
306 }
307 Ok(out)
308 }
309
310 pub fn update_document_fields(
317 &self,
318 table: &str,
319 doc_id: DocId,
320 updates: BTreeMap<String, Value>,
321 vectors: BTreeMap<String, Vec<f32>>,
322 ) -> Result<bool, SQLError> {
323 let vector_values = vectors
324 .into_iter()
325 .map(|(field, vector)| (field, vec![vector]))
326 .collect();
327 self.update_document_fields_with_vector_values(table, doc_id, updates, vector_values)
328 }
329
330 pub fn update_document_fields_with_vector_values(
331 &self,
332 table: &str,
333 doc_id: DocId,
334 updates: BTreeMap<String, Value>,
335 vectors: BTreeMap<String, Vec<Vec<f32>>>,
336 ) -> Result<bool, SQLError> {
337 let columns = updates.keys().cloned().collect::<Vec<_>>();
338 let strength =
339 uqa_execution::query::locking::context::update_lock_strength(self, table, &columns);
340 self.with_implicit_row_write_transaction(table, doc_id, strength, |engine| {
341 engine.update_document_fields_with_vector_values_inner(table, doc_id, updates, vectors)
342 })
343 }
344
345 pub(super) fn update_document_fields_with_vector_values_inner(
346 &self,
347 table: &str,
348 doc_id: DocId,
349 updates: BTreeMap<String, Value>,
350 vectors: BTreeMap<String, Vec<Vec<f32>>>,
351 ) -> Result<bool, SQLError> {
352 let Some(t) = self
353 .try_table(table)
354 .map_err(|error| SQLError::Internal(format!("resolve table `{table}`: {error}")))?
355 else {
356 return Err(SQLError::UnknownTable(table.to_string()));
357 };
358 if let Some(read) = self.serializable_table_state_read(&t)? {
359 read.observe_row(doc_id)?;
360 }
361 let Some(mut doc) = t
362 .document_store
363 .read()
364 .get(doc_id)
365 .map_err(|error| document_store_read_error("read document for update", &error))?
366 else {
367 return Ok(false);
368 };
369 self.validate_vector_values(table, &vectors)?;
370 for (k, v) in updates {
371 doc.insert(k, v);
372 }
373 let mut replacement_vectors = Self::document_vector_values(&t, &doc)?;
374 for (field, values) in vectors {
375 replacement_vectors.insert(field, values);
376 }
377 self.add_document_with_vector_values_inner(
381 table,
382 doc_id,
383 doc,
384 replacement_vectors,
385 uqa_execution::mutation::publication::InsertedIdentity::Unknown,
386 )?;
387 Ok(true)
388 }
389
390 pub fn patch_document_fields(
394 &self,
395 table: &str,
396 doc_id: DocId,
397 updates: &BTreeMap<String, Value>,
398 vectors: &BTreeMap<String, Vec<f32>>,
399 ) -> Result<bool, SQLError> {
400 let vector_values: BTreeMap<String, Vec<Vec<f32>>> = vectors
401 .iter()
402 .map(|(field, vector)| (field.clone(), vec![vector.clone()]))
403 .collect();
404 self.patch_document_fields_with_vector_values(table, doc_id, updates, &vector_values)
405 }
406
407 pub fn patch_document_fields_with_vector_values(
408 &self,
409 table: &str,
410 doc_id: DocId,
411 updates: &BTreeMap<String, Value>,
412 vectors: &BTreeMap<String, Vec<Vec<f32>>>,
413 ) -> Result<bool, SQLError> {
414 let columns = updates.keys().cloned().collect::<Vec<_>>();
415 let strength =
416 uqa_execution::query::locking::context::update_lock_strength(self, table, &columns);
417 self.with_implicit_row_write_transaction(table, doc_id, strength, |engine| {
418 engine.patch_document_fields_with_vector_values_inner(table, doc_id, updates, vectors)
419 })
420 }
421
422 pub(super) fn patch_document_fields_with_vector_values_inner(
423 &self,
424 table: &str,
425 doc_id: DocId,
426 updates: &BTreeMap<String, Value>,
427 vectors: &BTreeMap<String, Vec<Vec<f32>>>,
428 ) -> Result<bool, SQLError> {
429 let Some(t) = self
430 .try_table(table)
431 .map_err(|error| SQLError::Internal(format!("resolve table `{table}`: {error}")))?
432 else {
433 return Err(SQLError::UnknownTable(table.to_string()));
434 };
435 if let Some(read) = self.serializable_table_state_read(&t)? {
436 read.observe_row(doc_id)?;
437 }
438 let Some(mut document) = self
439 .raw_command_visible_document(table, &t, doc_id)?
440 .map(StoredDocument::into_fields)
441 else {
442 return Ok(false);
443 };
444 self.validate_vector_values(table, vectors)?;
445 for (field, value) in updates {
446 if matches!(value, Value::Null) {
447 document.remove(field);
448 } else {
449 document.insert(field.clone(), value.clone());
450 }
451 }
452
453 let vector_fields = t.vector_indexes.read().keys().cloned().collect::<Vec<_>>();
454 let mut replacement_vectors = vectors.clone();
455 for field in vector_fields {
456 if !updates.contains_key(&field) || replacement_vectors.contains_key(&field) {
457 continue;
458 }
459 let values = match document.get(&field) {
460 Some(value) => Self::field_index_vectors(&t, &field, value)?.unwrap_or_default(),
461 None => Vec::new(),
462 };
463 replacement_vectors.insert(field, values);
464 }
465
466 self.add_document_with_vector_values_inner(
472 table,
473 doc_id,
474 document,
475 replacement_vectors,
476 uqa_execution::mutation::publication::InsertedIdentity::Unknown,
477 )?;
478 Ok(true)
479 }
480
481 pub(crate) fn rewrite_prepared_document(
483 &self,
484 table: &str,
485 doc_id: DocId,
486 document: Document,
487 ) -> Result<(), SQLError> {
488 self.rewrite_prepared_document_with_fts(table, doc_id, document, true)
489 }
490
491 pub(crate) fn rewrite_prepared_document_deferred_fts(
492 &self,
493 table: &str,
494 doc_id: DocId,
495 document: Document,
496 ) -> Result<(), SQLError> {
497 self.rewrite_prepared_document_with_fts(table, doc_id, document, false)
498 }
499
500 fn rewrite_prepared_document_with_fts(
501 &self,
502 table: &str,
503 doc_id: DocId,
504 document: Document,
505 index_fts: bool,
506 ) -> Result<(), SQLError> {
507 let table_name = self
508 .try_resolve_table_name(table)
509 .map_err(|error| SQLError::Internal(format!("resolve table `{table}`: {error}")))?
510 .ok_or_else(|| SQLError::UnknownTable(table.to_string()))?;
511 let table_state = self
512 .try_table(&table_name)
513 .map_err(|error| SQLError::Internal(format!("resolve table `{table}`: {error}")))?
514 .ok_or_else(|| SQLError::UnknownTable(table_name.clone()))?;
515 let mut vectors = Self::document_vector_values(&table_state, &document)?;
516 if !vectors.is_empty() {
520 let control = self.query_retention_control()?;
521 let indexes = table_state.vector_indexes.read();
522 let mut unchanged = Vec::new();
523 for (field, values) in &vectors {
524 if let Some(index) = indexes.get(field) {
525 let same = index
526 .matches_document_vectors(doc_id, values, &control)
527 .map_err(|error| {
528 uqa_execution::storage_errors::storage_error(
529 "compare document vectors",
530 &error,
531 )
532 })?;
533 if same {
534 unchanged.push(field.clone());
535 }
536 }
537 }
538 for field in unchanged {
539 vectors.remove(&field);
540 }
541 }
542 self.with_prepared_row_write_transaction(&table_name, |engine| {
543 if index_fts {
544 engine.add_prepared_document_with_vector_values_inner(
545 &table_name,
546 doc_id,
547 document,
548 vectors,
549 uqa_execution::mutation::publication::InsertedIdentity::Unknown,
550 )
551 } else {
552 engine.add_prepared_document_with_vector_values_deferred_fts_inner(
553 &table_name,
554 doc_id,
555 document,
556 vectors,
557 uqa_execution::mutation::publication::InsertedIdentity::Unknown,
558 )
559 }
560 })
561 }
562
563 pub(crate) fn rewrite_document_for_schema_change(
569 &self,
570 table: &str,
571 doc_id: DocId,
572 document: Document,
573 ) -> Result<(), SQLError> {
574 let table_name = self
575 .try_resolve_table_name(table)
576 .map_err(|error| SQLError::Internal(format!("resolve table `{table}`: {error}")))?
577 .ok_or_else(|| SQLError::UnknownTable(table.to_string()))?;
578 let t = self
579 .try_table(&table_name)
580 .map_err(|error| SQLError::Internal(format!("resolve table `{table}`: {error}")))?
581 .ok_or_else(|| SQLError::UnknownTable(table_name.clone()))?;
582 let vector_fields: Vec<FieldName> = t.vector_indexes.read().keys().cloned().collect();
583 let mut vectors: BTreeMap<FieldName, Vec<Vec<f32>>> = BTreeMap::new();
584 for field in vector_fields {
585 let Some(value) = document.get(&field) else {
586 continue;
587 };
588 if let Some(values) = Self::field_index_vectors(&t, &field, value)? {
589 vectors.insert(field, values);
590 }
591 }
592 let mut text_fields: BTreeMap<FieldName, String> = BTreeMap::new();
593 for field in t.fts_fields() {
594 if let Some(Value::Str(value)) = document.get(&field) {
595 text_fields.insert(field, value.clone());
596 }
597 }
598 {
599 let mut store = t.document_store.write();
600 let metadata = store
601 .get_metadata(doc_id)
602 .map_err(|err| document_store_read_error("read tuple metadata for schema rewrite", &err))?
603 .ok_or_else(|| {
604 SQLError::Internal(format!(
605 "table `{table_name}` listed document {doc_id} for a schema rewrite but omitted its tuple metadata"
606 ))
607 })?;
608 store
609 .put_stored(doc_id, StoredDocument::with_metadata(document, metadata))
610 .map_err(|err| document_store_write_error(&err))?;
611 }
612 uqa_execution::serializable::text::add_document(
613 self,
614 &table_name,
615 t.columns.snapshot(),
616 t.inverted_index.write().as_mut(),
617 doc_id,
618 text_fields,
619 )?;
620 for (field, index) in t
621 .vector_indexes
622 .write()
623 .live_mut()
624 .map_err(|error| {
625 uqa_execution::storage_errors::storage_error("write vector registrations", &error)
626 })?
627 .iter_mut()
628 {
629 index
630 .add_many(doc_id, vectors.remove(field).unwrap_or_default())
631 .map_err(|error| SQLError::Internal(format!("index document vector: {error}")))?;
632 }
633 self.mark_row_write(&table_name, &t, super::DocumentCountChange::Unchanged)
634 .map_err(|err| SQLError::Internal(format!("invalidate column stats: {err}")))?;
635 self.note_row_changed(&table_name, doc_id)?;
636 self.publish_command_document(&table_name, doc_id)?;
637 Ok(())
638 }
639
640 pub fn delete_document(&self, table: &str, doc_id: DocId) -> Result<(), SQLError> {
641 self.with_implicit_row_write_transaction(
642 table,
643 doc_id,
644 uqa_sql::ast::LockStrength::ForUpdate,
645 |engine| engine.delete_document_inner(table, doc_id),
646 )
647 }
648
649 pub(super) fn delete_document_inner(&self, table: &str, doc_id: DocId) -> Result<(), SQLError> {
650 self.delete_document_with_text(table, doc_id, true)
651 }
652
653 pub(crate) fn delete_prepared_document_deferred_fts(
654 &self,
655 table: &str,
656 doc_id: DocId,
657 ) -> Result<(), SQLError> {
658 self.with_prepared_row_write_transaction(table, |engine| {
659 engine.delete_document_with_text(table, doc_id, false)
660 })
661 }
662
663 fn delete_document_with_text(
664 &self,
665 table: &str,
666 doc_id: DocId,
667 index_text: bool,
668 ) -> Result<(), SQLError> {
669 let table_name = self
670 .try_resolve_table_name(table)
671 .map_err(|error| SQLError::Internal(format!("resolve table `{table}`: {error}")))?
672 .ok_or_else(|| SQLError::UnknownTable(table.to_string()))?;
673 let t = self
674 .try_table(&table_name)
675 .map_err(|error| SQLError::Internal(format!("resolve table `{table}`: {error}")))?
676 .ok_or_else(|| SQLError::UnknownTable(table_name.clone()))?;
677 if let Some(read) = self.serializable_table_state_read(&t)? {
678 read.observe_row(doc_id)?;
679 }
680 let existed = t
681 .document_store
682 .read()
683 .get(doc_id)
684 .map_err(|err| document_store_write_error(&err))?
685 .is_some();
686 if existed {
687 uqa_execution::serializable::observe_row_write(self, &table_name, doc_id)?;
688 }
689 let old_indexed = Self::value_indexes_old_values(&t, doc_id);
690 self.observe_value_index_write(
691 &table_name,
692 &t,
693 doc_id,
694 existed,
695 old_indexed.as_ref(),
696 None,
697 )?;
698 for (field, index) in t.vector_indexes.read().iter() {
699 uqa_execution::serializable::vector::observe_write(
700 self,
701 &table_name,
702 &t.columns.snapshot(),
703 field,
704 index,
705 doc_id,
706 uqa_execution::serializable::vector::VectorChange::Delete,
707 )?;
708 }
709 let mut store = t.document_store.write();
710 store
711 .delete(doc_id)
712 .map_err(|err| document_store_write_error(&err))?;
713 self.persist_value_indexes_apply_write(&table_name, doc_id, None, None)?;
714 if let Some(old) = old_indexed.as_ref() {
715 Self::value_indexes_apply_write(&t, doc_id, Some(old), None);
716 }
717 drop(store);
718 if index_text {
719 uqa_execution::serializable::text::remove_document(
720 self,
721 &table_name,
722 t.columns.snapshot(),
723 t.inverted_index.write().as_mut(),
724 doc_id,
725 )?;
726 }
727 for idx in t
728 .vector_indexes
729 .write()
730 .live_mut()
731 .map_err(|error| {
732 uqa_execution::storage_errors::storage_error("write vector registrations", &error)
733 })?
734 .values_mut()
735 {
736 idx.as_mut()
737 .delete(doc_id)
738 .map_err(|error| SQLError::Internal(format!("delete indexed vector: {error}")))?;
739 }
740 let documents = if existed {
741 super::DocumentCountChange::Removed
742 } else {
743 super::DocumentCountChange::Unchanged
744 };
745 self.mark_row_write(&table_name, &t, documents)
746 .map_err(|err| SQLError::Internal(format!("invalidate column stats: {err}")))?;
747 if existed {
748 self.note_row_deleted(&table_name, doc_id)?;
749 }
750 self.publish_command_document(&table_name, doc_id)?;
752 Ok(())
753 }
754}
755
756#[cfg(test)]
757mod tests;