Skip to main content

uqa_storage/read_only_snapshot/
inverted.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7use std::collections::BTreeMap;
8use std::sync::Arc;
9
10use uqa_analysis::Analyzer;
11use uqa_core::memory::Budgeted;
12use uqa_core::{DocId, FieldName, IndexStats, PostingEntry, PostingList, TokenOccurrence};
13
14use crate::block_max_index::BlockMaxScorer;
15use crate::clustered_postings::{BudgetedPostingReadCursor, OccurrencePosting, PostingCursor};
16use crate::inverted_index::{AnalyzerPhase, IndexedFieldMetadata, InvertedIndexChangeVisitor};
17use crate::read_control::StorageReadControl;
18use crate::{InvertedIndex, StorageBackendResult, TokenTermKey};
19
20use super::{read_only_error, ReadOnlySnapshot};
21
22impl ReadOnlySnapshot<dyn InvertedIndex> {
23    /// Erase a captured provider's concrete type after reserving its shared allocation, keeping all producer leases with the immutable index.
24    pub fn from_budgeted_inverted<T: InvertedIndex + 'static>(
25        snapshot: Budgeted<T>,
26    ) -> StorageBackendResult<Self> {
27        let snapshot = ReadOnlySnapshot::from_budgeted(snapshot)?;
28        Ok(Self(snapshot.0, snapshot.1, snapshot.2, None))
29    }
30}
31
32impl<T: InvertedIndex + ?Sized> ReadOnlySnapshot<T> {
33    /// Retain the first selected read control. Generation reservations can be shared without giving an unrelated reader the prior reader's cancellation signal.
34    pub fn with_inverted_read_control(
35        mut self,
36        control: &StorageReadControl,
37    ) -> StorageBackendResult<Self> {
38        control.check()?;
39        if self.2.is_none() {
40            self.2 = Some(control.clone());
41        }
42        self.check_inverted_read()?;
43        Ok(self)
44    }
45
46    fn check_inverted_read(&self) -> StorageBackendResult<()> {
47        self.2.as_ref().map_or(Ok(()), StorageReadControl::check)
48    }
49
50    fn inverted_control<'a>(
51        &'a self,
52        requested: &'a StorageReadControl,
53    ) -> StorageBackendResult<&'a StorageReadControl> {
54        requested.check()?;
55        self.check_inverted_read()?;
56        // Retention and read workspace can have different limits; preserve the explicit reader allowance.
57        Ok(requested)
58    }
59}
60
61impl InvertedIndex for ReadOnlySnapshot<dyn InvertedIndex> {
62    fn source_rebuild_required(&self) -> StorageBackendResult<bool> {
63        self.check_inverted_read()?;
64        self.0.source_rebuild_required()
65    }
66
67    fn analyzer(&self) -> &Analyzer {
68        self.0.analyzer()
69    }
70
71    fn default_analyzer_binding(
72        &self,
73    ) -> StorageBackendResult<crate::inverted_index::AnalyzerDefault> {
74        self.check_inverted_read()?;
75        self.0.default_analyzer_binding()
76    }
77
78    fn add_document(
79        &mut self,
80        _doc_id: DocId,
81        _fields: BTreeMap<FieldName, String>,
82    ) -> StorageBackendResult<()> {
83        Err(read_only_error())
84    }
85
86    fn try_add_document(
87        &mut self,
88        _doc_id: DocId,
89        _fields: BTreeMap<FieldName, String>,
90    ) -> StorageBackendResult<()> {
91        Err(read_only_error())
92    }
93
94    fn try_add_documents(
95        &mut self,
96        _documents: Vec<(DocId, BTreeMap<FieldName, String>)>,
97    ) -> StorageBackendResult<()> {
98        Err(read_only_error())
99    }
100
101    fn try_add_documents_observed(
102        &mut self,
103        _documents: Vec<(DocId, BTreeMap<FieldName, String>)>,
104        _visit: &mut InvertedIndexChangeVisitor<'_>,
105    ) -> StorageBackendResult<()> {
106        Err(read_only_error())
107    }
108
109    fn try_remove_document_observed(
110        &mut self,
111        _doc_id: DocId,
112        _visit: &mut InvertedIndexChangeVisitor<'_>,
113    ) -> StorageBackendResult<()> {
114        Err(read_only_error())
115    }
116
117    fn remove_document(&mut self, _doc_id: DocId) -> StorageBackendResult<()> {
118        Err(read_only_error())
119    }
120
121    fn try_remove_document(&mut self, _doc_id: DocId) -> StorageBackendResult<()> {
122        Err(read_only_error())
123    }
124
125    fn clear(&mut self) -> StorageBackendResult<()> {
126        Err(read_only_error())
127    }
128
129    fn try_clear(&mut self) -> StorageBackendResult<()> {
130        Err(read_only_error())
131    }
132
133    fn try_rebuild_documents(
134        &mut self,
135        _source: &mut dyn crate::inverted_index::TextIndexSource,
136    ) -> StorageBackendResult<()> {
137        Err(read_only_error())
138    }
139
140    fn get_posting_list(&self, field: &str, term: &str) -> StorageBackendResult<PostingList> {
141        self.check_inverted_read()?;
142        self.0.get_posting_list(field, term)
143    }
144
145    fn get_posting_list_key(
146        &self,
147        field: &str,
148        term: &TokenTermKey,
149    ) -> StorageBackendResult<PostingList> {
150        self.check_inverted_read()?;
151        self.0.get_posting_list_key(field, term)
152    }
153
154    fn posting_cursor_key(
155        &self,
156        field: &str,
157        term: &TokenTermKey,
158    ) -> StorageBackendResult<Box<dyn PostingCursor>> {
159        self.check_inverted_read()?;
160        self.0.posting_cursor_key(field, term)
161    }
162
163    fn posting_read_cursor_key<'a>(
164        &'a self,
165        field: &'a str,
166        term: &TokenTermKey,
167    ) -> StorageBackendResult<Box<dyn crate::clustered_postings::PostingReadCursor + 'a>> {
168        self.0.posting_read_cursor_key(field, term)
169    }
170
171    fn posting_read_cursor_key_budgeted<'a>(
172        &'a self,
173        field: &'a str,
174        term: &'a TokenTermKey,
175        control: &StorageReadControl,
176    ) -> StorageBackendResult<BudgetedPostingReadCursor<'a>> {
177        self.0
178            .posting_read_cursor_key_budgeted(field, term, self.inverted_control(control)?)
179    }
180
181    fn visit_score_clusters(
182        &self,
183        field: &str,
184        term: &TokenTermKey,
185        after: Option<u64>,
186        limit: usize,
187        control: &StorageReadControl,
188        visit: &mut crate::clustered_postings::ScoreClusterVisitor<'_>,
189    ) -> StorageBackendResult<()> {
190        self.0.visit_score_clusters(
191            field,
192            term,
193            after,
194            limit,
195            self.inverted_control(control)?,
196            visit,
197        )
198    }
199
200    fn get_occurrences_budgeted(
201        &self,
202        doc_id: DocId,
203        field: &str,
204        term: &TokenTermKey,
205        control: &StorageReadControl,
206    ) -> StorageBackendResult<Budgeted<Vec<TokenOccurrence>>> {
207        self.0
208            .get_occurrences_budgeted(doc_id, field, term, self.inverted_control(control)?)
209    }
210
211    fn get_occurrence_postings(
212        &self,
213        field: &str,
214        term: &TokenTermKey,
215    ) -> StorageBackendResult<Vec<OccurrencePosting>> {
216        self.check_inverted_read()?;
217        self.0.get_occurrence_postings(field, term)
218    }
219
220    fn get_occurrences(
221        &self,
222        doc_id: DocId,
223        field: &str,
224        term: &TokenTermKey,
225    ) -> StorageBackendResult<Vec<TokenOccurrence>> {
226        self.check_inverted_read()?;
227        self.0.get_occurrences(doc_id, field, term)
228    }
229
230    fn indexed_field_metadata(
231        &self,
232        doc_id: DocId,
233        field: &str,
234    ) -> StorageBackendResult<Option<IndexedFieldMetadata>> {
235        self.check_inverted_read()?;
236        self.0.indexed_field_metadata(doc_id, field)
237    }
238
239    fn doc_freq_key(&self, field: &str, term: &TokenTermKey) -> StorageBackendResult<u64> {
240        self.check_inverted_read()?;
241        self.0.doc_freq_key(field, term)
242    }
243
244    fn doc_freq_key_budgeted(
245        &self,
246        field: &str,
247        term: &TokenTermKey,
248        control: &StorageReadControl,
249    ) -> StorageBackendResult<u64> {
250        self.check_inverted_read()?;
251        let frequency = self.0.doc_freq_key_budgeted(field, term, control)?;
252        self.check_inverted_read()?;
253        Ok(frequency)
254    }
255
256    fn get_term_freq_key(
257        &self,
258        doc_id: DocId,
259        field: &str,
260        term: &TokenTermKey,
261    ) -> StorageBackendResult<u64> {
262        self.check_inverted_read()?;
263        self.0.get_term_freq_key(doc_id, field, term)
264    }
265
266    fn vocabulary_keys(&self, field: &str) -> StorageBackendResult<Vec<TokenTermKey>> {
267        self.check_inverted_read()?;
268        self.0.vocabulary_keys(field)
269    }
270
271    fn get_posting_lists_bulk(
272        &self,
273        field: &str,
274        terms: &[String],
275    ) -> StorageBackendResult<Vec<PostingList>> {
276        self.check_inverted_read()?;
277        self.0.get_posting_lists_bulk(field, terms)
278    }
279
280    fn posting_cursor(
281        &self,
282        field: &str,
283        term: &str,
284    ) -> StorageBackendResult<Box<dyn PostingCursor>> {
285        self.check_inverted_read()?;
286        self.0.posting_cursor(field, term)
287    }
288
289    fn posting_cursors_bulk(
290        &self,
291        field: &str,
292        terms: &[String],
293    ) -> StorageBackendResult<Vec<Box<dyn PostingCursor>>> {
294        self.check_inverted_read()?;
295        self.0.posting_cursors_bulk(field, terms)
296    }
297
298    fn posting_cursors_keys_bulk(
299        &self,
300        field: &str,
301        terms: &[TokenTermKey],
302    ) -> StorageBackendResult<Vec<Box<dyn PostingCursor>>> {
303        self.check_inverted_read()?;
304        self.0.posting_cursors_keys_bulk(field, terms)
305    }
306
307    fn get_posting_lists_keys_bulk(
308        &self,
309        field: &str,
310        terms: &[TokenTermKey],
311    ) -> StorageBackendResult<Vec<PostingList>> {
312        self.check_inverted_read()?;
313        self.0.get_posting_lists_keys_bulk(field, terms)
314    }
315
316    fn persisted_block_max_scores_keys_bulk(
317        &self,
318        field: &str,
319        terms: &[TokenTermKey],
320        scorer_fingerprint: &str,
321    ) -> StorageBackendResult<Vec<Option<Vec<f64>>>> {
322        self.check_inverted_read()?;
323        self.0
324            .persisted_block_max_scores_keys_bulk(field, terms, scorer_fingerprint)
325    }
326
327    fn get_scoring_inputs_keys_bulk(
328        &self,
329        doc_ids: &[DocId],
330        field: &str,
331        terms: &[TokenTermKey],
332    ) -> StorageBackendResult<Vec<(u64, Vec<u64>)>> {
333        self.check_inverted_read()?;
334        self.0.get_scoring_inputs_keys_bulk(doc_ids, field, terms)
335    }
336
337    fn rebuild_persisted_block_max(
338        &mut self,
339        _field: &str,
340        _scorer: &dyn BlockMaxScorer,
341        _scorer_fingerprint: &str,
342    ) -> StorageBackendResult<bool> {
343        Err(read_only_error())
344    }
345
346    fn persisted_block_max_scores(
347        &self,
348        field: &str,
349        term: &str,
350        scorer_fingerprint: &str,
351    ) -> StorageBackendResult<Option<Vec<f64>>> {
352        self.check_inverted_read()?;
353        self.0
354            .persisted_block_max_scores(field, term, scorer_fingerprint)
355    }
356
357    fn persisted_block_max_scores_bulk(
358        &self,
359        field: &str,
360        terms: &[String],
361        scorer_fingerprint: &str,
362    ) -> StorageBackendResult<Vec<Option<Vec<f64>>>> {
363        self.check_inverted_read()?;
364        self.0
365            .persisted_block_max_scores_bulk(field, terms, scorer_fingerprint)
366    }
367
368    fn for_each_posting(
369        &self,
370        field: &str,
371        term: &str,
372        visit: &mut dyn FnMut(&PostingEntry),
373    ) -> StorageBackendResult<()> {
374        self.check_inverted_read()?;
375        self.0.for_each_posting(field, term, visit)
376    }
377
378    fn for_each_term_freq(
379        &self,
380        field: &str,
381        term: &str,
382        visit: &mut dyn FnMut(DocId, u64),
383    ) -> StorageBackendResult<()> {
384        self.check_inverted_read()?;
385        self.0.for_each_term_freq(field, term, visit)
386    }
387
388    fn doc_freq(&self, field: &str, term: &str) -> StorageBackendResult<u64> {
389        self.check_inverted_read()?;
390        self.0.doc_freq(field, term)
391    }
392
393    fn get_doc_length(&self, doc_id: DocId, field: &str) -> StorageBackendResult<u64> {
394        self.check_inverted_read()?;
395        self.0.get_doc_length(doc_id, field)
396    }
397
398    fn get_term_freq(&self, doc_id: DocId, field: &str, term: &str) -> StorageBackendResult<u64> {
399        self.check_inverted_read()?;
400        self.0.get_term_freq(doc_id, field, term)
401    }
402
403    fn doc_count(&self) -> StorageBackendResult<u64> {
404        self.check_inverted_read()?;
405        self.0.doc_count()
406    }
407
408    fn total_field_length(&self, field: &str) -> StorageBackendResult<u64> {
409        self.check_inverted_read()?;
410        self.0.total_field_length(field)
411    }
412
413    fn field_doc_count(&self, field: &str) -> StorageBackendResult<u64> {
414        self.check_inverted_read()?;
415        self.0.field_doc_count(field)
416    }
417
418    fn field_stats(&self, field: &str) -> StorageBackendResult<IndexStats> {
419        self.check_inverted_read()?;
420        self.0.field_stats(field)
421    }
422
423    fn field_stats_scalar(&self, field: &str) -> StorageBackendResult<IndexStats> {
424        self.check_inverted_read()?;
425        self.0.field_stats_scalar(field)
426    }
427
428    fn field_stats_scalar_budgeted(
429        &self,
430        field: &str,
431        control: &StorageReadControl,
432    ) -> StorageBackendResult<IndexStats> {
433        self.0
434            .field_stats_scalar_budgeted(field, self.inverted_control(control)?)
435    }
436
437    fn vocabulary_terms(&self, field: &str) -> StorageBackendResult<Vec<String>> {
438        self.check_inverted_read()?;
439        self.0.vocabulary_terms(field)
440    }
441
442    fn stats(&self) -> StorageBackendResult<IndexStats> {
443        self.check_inverted_read()?;
444        self.0.stats()
445    }
446
447    fn posting_count(&self, field: Option<&str>) -> StorageBackendResult<u64> {
448        self.check_inverted_read()?;
449        self.0.posting_count(field)
450    }
451
452    fn doc_length_count(&self, field: Option<&str>) -> StorageBackendResult<u64> {
453        self.check_inverted_read()?;
454        self.0.doc_length_count(field)
455    }
456
457    fn term_count(&self, field: Option<&str>) -> StorageBackendResult<u64> {
458        self.check_inverted_read()?;
459        self.0.term_count(field)
460    }
461
462    fn snapshot(&self) -> StorageBackendResult<Arc<dyn InvertedIndex>> {
463        self.check_inverted_read()?;
464        Ok(Arc::new(self.clone()))
465    }
466
467    fn snapshot_with_control(
468        &self,
469        control: &StorageReadControl,
470    ) -> StorageBackendResult<Arc<dyn InvertedIndex>> {
471        control.check()?;
472        if self.1.is_some() || self.2.is_some() {
473            return self.clone().with_inverted_read_control(control)?.snapshot();
474        }
475        Ok(Arc::new(ReadOnlySnapshot::new(
476            self.0.snapshot_with_control(control)?,
477        )))
478    }
479
480    fn field_names(&self) -> StorageBackendResult<Vec<FieldName>> {
481        self.check_inverted_read()?;
482        self.0.field_names()
483    }
484
485    fn field_names_budgeted(
486        &self,
487        control: &StorageReadControl,
488    ) -> StorageBackendResult<uqa_core::memory::BudgetedVec<uqa_core::memory::BudgetedString>> {
489        self.check_inverted_read()?;
490        let fields = self.0.field_names_budgeted(control)?;
491        self.check_inverted_read()?;
492        Ok(fields)
493    }
494
495    fn get_posting_list_any_field(&self, term: &str) -> StorageBackendResult<PostingList> {
496        self.check_inverted_read()?;
497        self.0.get_posting_list_any_field(term)
498    }
499
500    fn doc_freq_any_field(&self, term: &str) -> StorageBackendResult<u64> {
501        self.check_inverted_read()?;
502        self.0.doc_freq_any_field(term)
503    }
504
505    fn get_total_doc_length(&self, doc_id: DocId) -> StorageBackendResult<u64> {
506        self.check_inverted_read()?;
507        self.0.get_total_doc_length(doc_id)
508    }
509
510    fn get_doc_lengths_bulk(
511        &self,
512        doc_ids: &[DocId],
513        field: &str,
514    ) -> StorageBackendResult<BTreeMap<DocId, u64>> {
515        self.check_inverted_read()?;
516        self.0.get_doc_lengths_bulk(doc_ids, field)
517    }
518
519    fn get_term_freqs_bulk(
520        &self,
521        doc_ids: &[DocId],
522        field: &str,
523        term: &str,
524    ) -> StorageBackendResult<BTreeMap<DocId, u64>> {
525        self.check_inverted_read()?;
526        self.0.get_term_freqs_bulk(doc_ids, field, term)
527    }
528
529    fn get_scoring_inputs_bulk(
530        &self,
531        doc_ids: &[DocId],
532        field: &str,
533        terms: &[String],
534    ) -> StorageBackendResult<Vec<(u64, Vec<u64>)>> {
535        self.check_inverted_read()?;
536        self.0.get_scoring_inputs_bulk(doc_ids, field, terms)
537    }
538
539    fn get_total_term_freq(&self, doc_id: DocId, term: &str) -> StorageBackendResult<u64> {
540        self.check_inverted_read()?;
541        self.0.get_total_term_freq(doc_id, term)
542    }
543
544    fn set_field_analyzer(
545        &mut self,
546        _field: &str,
547        _analyzer: Analyzer,
548        _phase: AnalyzerPhase,
549    ) -> Result<(), String> {
550        Err(read_only_error().to_string())
551    }
552
553    fn remove_field_analyzers(&mut self, _field: &str) -> Result<(), String> {
554        Err(read_only_error().to_string())
555    }
556
557    fn get_field_analyzer(&self, field: &str) -> Analyzer {
558        self.0.get_field_analyzer(field)
559    }
560
561    fn get_search_analyzer(&self, field: &str) -> Analyzer {
562        self.0.get_search_analyzer(field)
563    }
564
565    fn index_analyzer_revision(
566        &self,
567        field: &str,
568    ) -> StorageBackendResult<Arc<uqa_analysis::CompiledAnalyzer>> {
569        self.check_inverted_read()?;
570        self.0.index_analyzer_revision(field)
571    }
572
573    fn search_analyzer_revision(
574        &self,
575        field: &str,
576    ) -> StorageBackendResult<Arc<uqa_analysis::CompiledAnalyzer>> {
577        self.check_inverted_read()?;
578        self.0.search_analyzer_revision(field)
579    }
580
581    fn set_field_analyzer_revision(
582        &mut self,
583        _field: &str,
584        _revision: Arc<uqa_analysis::CompiledAnalyzer>,
585        _phase: AnalyzerPhase,
586    ) -> Result<(), String> {
587        Err(read_only_error().to_string())
588    }
589
590    fn set_field_analyzer_revisions(
591        &mut self,
592        _field: &str,
593        _index: Arc<uqa_analysis::CompiledAnalyzer>,
594        _search: Arc<uqa_analysis::CompiledAnalyzer>,
595    ) -> Result<(), String> {
596        Err(read_only_error().to_string())
597    }
598
599    fn rebuild_with_analyzer_revision(
600        &mut self,
601        _field: &str,
602        _revision: Arc<uqa_analysis::CompiledAnalyzer>,
603        _phase: AnalyzerPhase,
604        _source: &mut dyn crate::inverted_index::TextIndexSource,
605    ) -> StorageBackendResult<()> {
606        Err(read_only_error())
607    }
608
609    fn try_rebuild_documents_cancellable(
610        &mut self,
611        _source: &mut dyn crate::inverted_index::TextIndexSource,
612        _cancellation: &uqa_core::CancellationToken,
613    ) -> StorageBackendResult<()> {
614        Err(read_only_error())
615    }
616
617    fn rebuild_with_analyzer_revision_cancellable(
618        &mut self,
619        _field: &str,
620        _revision: Arc<uqa_analysis::CompiledAnalyzer>,
621        _phase: AnalyzerPhase,
622        _source: &mut dyn crate::inverted_index::TextIndexSource,
623        _cancellation: &uqa_core::CancellationToken,
624    ) -> StorageBackendResult<()> {
625        Err(read_only_error())
626    }
627}