Skip to main content

uqa_engine/table_storage/
documents.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Document lookup, conflict probing, mutation, rewrite, and deletion.
8
9use 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    /// Read only user fields for a tuple rewrite. A successful rewrite receives fresh tuple metadata at the storage publication boundary.
65    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    /// Read the latest committed tuple through an independent persistent session while this session keeps its statement snapshot pinned.
92    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    /// Execute a retrieval predicate against the latest committed index state through an independent session while this session keeps its statement snapshot pinned. A tuple-local recheck uses it so a substituted committed image is judged by the retrieval predicate the way `PostgreSQL` re-evaluates the WHERE clause on the new tuple. Without a provider the engine has a single shared state already.
133    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    /// Execute one raw KNN leaf against the latest committed vector-index state for a tuple-local hierarchy recheck.
156    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    /// Fetch complete physical documents while materializing only the virtual generated or storage-owned tuple columns named by `projection`; projected execution paths use this boundary so unrelated virtual expressions remain deferred.
187    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    /// Apply per-column updates to an existing document. Mirrors the
311    /// `DO UPDATE SET col = expr` branch of an ON CONFLICT clause.
312    /// Returns whether the row was updated; `Ok(false)` when the
313    /// document no longer exists. Storage write failures surface as
314    /// `Err` so the enclosing transaction rolls back instead of
315    /// committing a delete whose re-insert never happened.
316    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_evaluating_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        // Each index's replacement path validates/stages before publishing.
378        // Never delete the old row/index state first: an analyzer or backend
379        // failure must leave the prior version queryable.
380        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    /// Apply field-level updates to the current command-visible row.
391    /// Callers must only use this path when constraints and
392    /// referential actions do not need the old or complete new row.
393    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_evaluating_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        // The common replacement path stages text analysis and vector input
467        // before publishing and updates the document/value indexes as one
468        // logical row version. This avoids the old patch -> remove -> add
469        // sequence where an analyzer failure left the stored row changed and
470        // its postings deleted in a memory engine.
471        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    /// Rewrite one row for SQL `UPDATE`. The caller has already acquired the tuple lock at the strength `update_lock_strength` derived from the changed columns and holds the relation lock, so this path must not re-lock: taking `FOR UPDATE` here would make a non-key update conflict with concurrent `FOR KEY SHARE` holders and publish an inflated mutation strength, both contrary to `PostgreSQL` 18.
482    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        // The SQL row and its tuple metadata are still rewritten. Retain an
517        // index only when its actual canonical values match the replacement;
518        // comparing document fields alone would miss direct index API writes.
519        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    /// Rewrite a row while a column is being dropped or renamed. The
564    /// operation changes field names, not the indexed values: catalog
565    /// lifecycle code drops or renames the durable postings afterward.
566    /// Maintaining them against the half-updated schema here would replace a
567    /// renamed field with NULL before its metadata has moved.
568    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        // A caller can have staged this row without publishing it yet.
751        self.publish_command_document(&table_name, doc_id)?;
752        Ok(())
753    }
754}
755
756#[cfg(test)]
757mod tests;