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        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    /// Execute one raw KNN leaf against the latest committed vector-index state for a tuple-local hierarchy recheck.
161    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    /// 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.
192    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    /// Apply per-column updates to an existing document. Mirrors the
316    /// `DO UPDATE SET col = expr` branch of an ON CONFLICT clause.
317    /// Returns whether the row was updated; `Ok(false)` when the
318    /// document no longer exists. Storage write failures surface as
319    /// `Err` so the enclosing transaction rolls back instead of
320    /// committing a delete whose re-insert never happened.
321    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        // Each index's replacement path validates/stages before publishing.
383        // Never delete the old row/index state first: an analyzer or backend
384        // failure must leave the prior version queryable.
385        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    /// Apply field-level updates to the current command-visible row.
396    /// Callers must only use this path when constraints and
397    /// referential actions do not need the old or complete new row.
398    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        // The common replacement path stages text analysis and vector input
472        // before publishing and updates the document/value indexes as one
473        // logical row version. This avoids the old patch -> remove -> add
474        // sequence where an analyzer failure left the stored row changed and
475        // its postings deleted in a memory engine.
476        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    /// 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.
487    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        // The SQL row and its tuple metadata are still rewritten. Retain an
522        // index only when its actual canonical values match the replacement;
523        // comparing document fields alone would miss direct index API writes.
524        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    /// Rewrite a row while a column is being dropped or renamed. The
569    /// operation changes field names, not the indexed values: catalog
570    /// lifecycle code drops or renames the durable postings afterward.
571    /// Maintaining them against the half-updated schema here would replace a
572    /// renamed field with NULL before its metadata has moved.
573    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        // A caller can have staged this row without publishing it yet.
756        self.publish_command_document(&table_name, doc_id)?;
757        Ok(())
758    }
759}
760
761#[cfg(test)]
762mod tests;