1use 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
34pub 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
55pub 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
66pub 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
165pub 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 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}