Skip to main content

uqa_execution/query/
table_snapshot.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Query-table row adaptation and reconstruction from a retained base and evaluated private rows.
8
9use std::sync::Arc;
10use uqa_core::memory::{BudgetedMap, BudgetedVec, MemoryReservation};
11use uqa_core::{DocId, FieldName, Value};
12use uqa_sql::{ast::ColumnDef, schema::retention::RetainedColumns, ColumnType, SQLError};
13use uqa_storage::inverted_index::RetainedInvertedIndexBuilder;
14use uqa_storage::{
15    read_control::StorageReadControl,
16    vector_index::{RetainedVectorIndexBuilder, RetainedVectorIndexesBuilder, VectorIndexes},
17};
18use uqa_storage::{
19    DocumentStore, InvertedIndex, RetainedDocumentStoreBuilder, StorageBackendError,
20};
21
22mod documents;
23mod layout;
24mod vector_metadata;
25mod vectors;
26use super::document_changes::DocumentChanges;
27use layout::RowLayout;
28pub use vector_metadata::{retain_vector_indexes, VectorDimensions};
29use vectors::{SnapshotVector, VectorSources};
30
31#[cfg(test)]
32mod tests;
33
34/// The selected catalog supplies immutable column definitions, field revisions and registered vector dimensions. The reconstruction does not consult live catalog state.
35pub struct SnapshotSchema<'a> {
36    pub columns: Arc<Vec<ColumnDef>>,
37    pub text_fields: &'a [FieldName],
38    pub text_revisions: &'a dyn InvertedIndex,
39    pub vector_dimensions: &'a dyn VectorDimensions,
40}
41
42pub struct MaterializedTable {
43    pub documents: Box<dyn DocumentStore>,
44    pub text: Box<dyn InvertedIndex>,
45    pub vectors: VectorIndexes,
46    pub document_count: u64,
47}
48
49struct SnapshotBuilder {
50    text: RetainedInvertedIndexBuilder,
51    vectors: BudgetedVec<(FieldName, SnapshotVector, MemoryReservation)>,
52    control: StorageReadControl,
53}
54
55/// Retain the immutable base instead of copying its documents into another complete store. Private replacements and row-layout metadata are shared by nested views, and projected reads avoid unrelated fields. Text/vector reconstruction still retains its resulting indexes.
56pub fn retain(
57    source: Arc<dyn DocumentStore>,
58    source_columns: &[ColumnDef],
59    schema: &SnapshotSchema<'_>,
60    changes: DocumentChanges,
61    control: &StorageReadControl,
62) -> Result<MaterializedTable, SQLError> {
63    retain_with_vector_indexes(source, source_columns, schema, changes, None, control)
64}
65
66/// Retain compatible physical indexes from the fixed source, or the selected new definition when every base row has an evaluated replacement or deletion. Canonical sources stay with their evaluated rows; unsupported selections retain the existing reconstruction path.
67pub fn retain_with_vector_indexes(
68    source: Arc<dyn DocumentStore>,
69    source_columns: &[ColumnDef],
70    schema: &SnapshotSchema<'_>,
71    changes: DocumentChanges,
72    base_vectors: Option<&dyn VectorDimensions>,
73    control: &StorageReadControl,
74) -> Result<MaterializedTable, SQLError> {
75    let cancellation = control.cancellation();
76    cancellation.check()?;
77    let columns = RetainedColumns::capture(&schema.columns, control.memory(), cancellation)?;
78    let layout = RowLayout::new(source_columns, columns.clone(), control)
79        .map_err(|error| snapshot_error("base row layout", &error))?;
80    let documents = documents::RetainedDocuments::new(
81        source,
82        layout,
83        RowLayout::new(&schema.columns, columns, control)
84            .map_err(|error| snapshot_error("private row layout", &error))?,
85        changes,
86        control,
87    )
88    .map_err(|error| snapshot_error("retained documents", &error))?;
89    let sources = base_vectors.map(|indexes| documents.vector_sources(indexes, source_columns));
90    let mut result = SnapshotBuilder::with_vector_sources(schema, sources.as_ref(), control)?;
91    let document_count = u64::try_from(
92        documents
93            .len()
94            .map_err(|error| snapshot_error("document count", &error))?,
95    )
96    .map_err(|_| SQLError::Internal("query snapshot document count overflow".into()))?;
97    let fields = index_fields_for_reconstruction(schema, Some(&result), control)?;
98    if fields.is_empty() {
99        return result.finish(Box::new(documents), document_count);
100    }
101    let mut after = None;
102    loop {
103        cancellation.check()?;
104        let ids = documents
105            .id_page(after, crate::DEFAULT_BATCH_SIZE)
106            .map_err(|error| snapshot_error("document ids", &error))?;
107        let Some(last) = ids.last().copied() else {
108            break;
109        };
110        after = Some(last);
111        result.index_projection(&documents, &ids, &fields, schema)?;
112    }
113    cancellation.check()?;
114    result.finish(Box::new(documents), document_count)
115}
116
117#[cfg(test)]
118fn index_fields<'a>(
119    schema: &'a SnapshotSchema<'_>,
120    control: &StorageReadControl,
121) -> Result<BudgetedVec<&'a str>, SQLError> {
122    index_fields_for_reconstruction(schema, None, control)
123}
124
125fn index_fields_for_reconstruction<'a>(
126    schema: &'a SnapshotSchema<'_>,
127    builder: Option<&SnapshotBuilder>,
128    control: &StorageReadControl,
129) -> Result<BudgetedVec<&'a str>, SQLError> {
130    control.cancellation().check()?;
131    let mut selected = BudgetedMap::new(control.memory());
132    for field in schema.text_fields {
133        control.cancellation().check()?;
134        selected
135            .insert(field.as_str(), ())
136            .map_err(|error| snapshot_error("index field selection", &error.into()))?;
137    }
138    schema.vector_dimensions.visit(&mut |field, _| {
139        control.cancellation().check()?;
140        if builder.is_some_and(|builder| {
141            builder.vectors.iter().any(|(name, index, _)| {
142                name == field && matches!(index, SnapshotVector::Physical(_))
143            })
144        }) {
145            return Ok(());
146        }
147        selected
148            .insert(field, ())
149            .map_err(|error| snapshot_error("index field selection", &error.into()))?;
150        Ok(())
151    })?;
152    let mut fields = BudgetedVec::new(control.memory());
153    fields
154        .reserve(selected.len())
155        .map_err(|error| snapshot_error("index field projection", &error.into()))?;
156    for (field, ()) in selected.iter() {
157        control.cancellation().check()?;
158        fields
159            .push(*field)
160            .map_err(|error| snapshot_error("index field projection", &error.into()))?;
161    }
162    Ok(fields)
163}
164
165/// Copy a mutable source into a controlled immutable corpus, or share an already retained source. Provider row pages keep their payload reservations through corpus adoption. The existing read adapter maps original column identities and shares evaluated private rows and selected definitions; capture does not construct defaults or unrequested generated values for every row. Text/vector reconstruction evaluates its requested fields. Owned read outputs retain their separate producer boundaries.
166pub fn materialize(
167    source: &dyn DocumentStore,
168    source_columns: &[ColumnDef],
169    schema: &SnapshotSchema<'_>,
170    changes: DocumentChanges,
171    control: &StorageReadControl,
172) -> Result<MaterializedTable, SQLError> {
173    let cancellation = control.cancellation();
174    cancellation.check()?;
175    if let Some(source) = source
176        .retained_snapshot()
177        .map_err(|error| snapshot_error("retained documents", &error))?
178    {
179        return retain(source, source_columns, schema, changes, control);
180    }
181    let mut retained = RetainedDocumentStoreBuilder::new(control);
182    let mut after = None;
183    loop {
184        cancellation.check()?;
185        let ids = uqa_storage::document_store::read_document_ids(
186            source,
187            after,
188            crate::DEFAULT_BATCH_SIZE,
189            control,
190        )
191        .map_err(|error| snapshot_error("document ids", &error))?;
192        let Some(last) = ids.last().copied() else {
193            break;
194        };
195        after = Some(last);
196        let mut selected = uqa_core::memory::BudgetedVec::new(control.memory());
197        for id in ids.iter().copied() {
198            cancellation.check()?;
199            if !changes
200                .contains_change(id)
201                .map_err(|error| snapshot_error("document selection", &error))?
202            {
203                selected
204                    .push(id)
205                    .map_err(|error| snapshot_error("document selection", &error.into()))?;
206            }
207        }
208        if selected.is_empty() {
209            continue;
210        }
211        let (documents, _page_memory) =
212            uqa_storage::document_store::read_stored_documents(source, &selected, control)
213                .map_err(|error| snapshot_error("documents", &error))?
214                .into_parts();
215        for (id, document) in selected.iter().copied().zip(documents) {
216            cancellation.check()?;
217            if let Some(document) = document {
218                retained
219                    .add_retained_document(id, document)
220                    .map_err(|error| snapshot_error("document", &error))?;
221            }
222        }
223    }
224    cancellation.check()?;
225    let documents = retained
226        .finish()
227        .map_err(|error| snapshot_error("documents", &error))?;
228    retain(
229        Arc::new(documents),
230        source_columns,
231        schema,
232        changes,
233        control,
234    )
235}
236
237pub fn empty(
238    schema: &SnapshotSchema<'_>,
239    control: &StorageReadControl,
240) -> Result<MaterializedTable, SQLError> {
241    let documents = RetainedDocumentStoreBuilder::new(control)
242        .finish()
243        .map_err(|error| snapshot_error("documents", &error))?;
244    SnapshotBuilder::new(schema, control)?.finish(Box::new(documents), 0)
245}
246
247impl SnapshotBuilder {
248    fn new(schema: &SnapshotSchema<'_>, control: &StorageReadControl) -> Result<Self, SQLError> {
249        Self::with_vector_sources(schema, None, control)
250    }
251
252    fn with_vector_sources(
253        schema: &SnapshotSchema<'_>,
254        sources: Option<&VectorSources<'_>>,
255        control: &StorageReadControl,
256    ) -> Result<Self, SQLError> {
257        control.cancellation().check()?;
258        let revisions = schema.text_fields.iter().map(|field| {
259            control.check()?;
260            Ok((
261                field.as_str(),
262                schema.text_revisions.index_analyzer_revision(field)?,
263                schema.text_revisions.search_analyzer_revision(field)?,
264            ))
265        });
266        let text = RetainedInvertedIndexBuilder::from_revisions(
267            schema
268                .text_revisions
269                .default_analyzer_binding()
270                .map_err(|error| snapshot_error("default analyzer binding", &error))?,
271            revisions,
272            control,
273        )
274        .map_err(|error| snapshot_error("inverted index", &error))?;
275        let mut vectors = BudgetedVec::new(control.memory());
276        schema.vector_dimensions.visit(&mut |field, dimensions| {
277            control.cancellation().check()?;
278            vectors
279                .reserve(1)
280                .map_err(|error| snapshot_error("vector metadata", &error.into()))?;
281            let (name, memory) = vector_metadata::copy_field(field, control)?;
282            let physical = sources
283                .map(|sources| sources.retain(field, dimensions, schema, control))
284                .transpose()?
285                .flatten();
286            let index = physical.map_or_else(
287                || {
288                    SnapshotVector::Reconstructed(RetainedVectorIndexBuilder::new(
289                        dimensions, control,
290                    ))
291                },
292                SnapshotVector::Physical,
293            );
294            vectors
295                .push((name, index, memory))
296                .map_err(|error| snapshot_error("vector metadata", &error.into()))?;
297            Ok(())
298        })?;
299        Ok(Self {
300            text,
301            vectors,
302            control: control.clone(),
303        })
304    }
305
306    fn finish(
307        self,
308        documents: Box<dyn DocumentStore>,
309        document_count: u64,
310    ) -> Result<MaterializedTable, SQLError> {
311        let (builders, _builder_memory) = self.vectors.into_parts();
312        let mut vectors = RetainedVectorIndexesBuilder::new(&self.control);
313        for (field, index, memory) in builders {
314            self.control.cancellation().check()?;
315            match index {
316                SnapshotVector::Reconstructed(index) => {
317                    let index = index
318                        .finish()
319                        .map_err(|error| snapshot_error("vector index", &error))?;
320                    vectors.insert_admitted(field, index, memory)
321                }
322                SnapshotVector::Physical(index) => vectors.insert_admitted(
323                    field,
324                    uqa_storage::ReadOnlySnapshot::new(index),
325                    memory,
326                ),
327            }
328            .map_err(|error| snapshot_error("vector index metadata", &error))?;
329        }
330        Ok(MaterializedTable {
331            documents,
332            text: Box::new(
333                self.text
334                    .finish()
335                    .map_err(|error| snapshot_error("inverted index", &error))?,
336            ),
337            vectors: vectors
338                .finish()
339                .map_err(|error| snapshot_error("vector indexes", &error))?,
340            document_count,
341        })
342    }
343
344    fn index_projection(
345        &mut self,
346        documents: &dyn DocumentStore,
347        ids: &[DocId],
348        fields: &[&str],
349        schema: &SnapshotSchema<'_>,
350    ) -> Result<(), SQLError> {
351        let mut failure = None;
352        let visited = documents.for_each_fields_multi_ref_with_presence(
353            ids,
354            fields,
355            &mut |id, present, values| {
356                if !present {
357                    return true;
358                }
359                let indexed = self.index_fields(
360                    id,
361                    |field| fields.binary_search(&field).ok().map(|slot| values[slot]),
362                    schema,
363                );
364                if let Err(error) = indexed {
365                    failure = Some(error);
366                    return false;
367                }
368                true
369            },
370        );
371        // Keep the first consumer failure when a provider notices cancellation while unwinding its borrowed projection.
372        if let Some(error) = failure {
373            return Err(error);
374        }
375        visited.map_err(|error| snapshot_error("index fields", &error))
376    }
377
378    fn index_fields<'a>(
379        &mut self,
380        id: DocId,
381        mut value_for: impl FnMut(&str) -> Option<&'a Value>,
382        schema: &SnapshotSchema<'_>,
383    ) -> Result<(), SQLError> {
384        let fields = schema
385            .text_fields
386            .iter()
387            .filter_map(|field| match value_for(field) {
388                Some(Value::Str(value)) => Some((field.as_str(), value.as_str())),
389                _ => None,
390            });
391        self.text
392            .add_document(id, fields)
393            .map_err(|error| snapshot_error("inverted index", &error))?;
394        for (field, index, _) in self.vectors.iter_mut() {
395            let SnapshotVector::Reconstructed(index) = index else {
396                continue;
397            };
398            let Some(value) = value_for(field) else {
399                continue;
400            };
401            let fallback = ColumnType::Vector(index.dimensions());
402            let ty = schema
403                .columns
404                .iter()
405                .find(|column| column.name == *field)
406                .map(|column| &column.ty)
407                .filter(|ty| matches!(ty, ColumnType::Tensor(_) | ColumnType::Vector(_)))
408                .unwrap_or(&fallback);
409            let vectors = uqa_sql::assignment::vectors::index_vectors_for_type_budgeted(
410                value,
411                ty,
412                self.control.memory(),
413                &mut || self.control.cancellation().check(),
414            )?;
415            index
416                .add_document(id, vectors)
417                .map_err(|error| snapshot_error("vector index", &error))?;
418        }
419        Ok(())
420    }
421}
422
423fn snapshot_error(component: &str, error: &StorageBackendError) -> SQLError {
424    crate::storage_errors::storage_error(&format!("construct query {component} snapshot"), error)
425}