Struct ReadOnlySnapshot 

pub struct ReadOnlySnapshot<T: ?Sized>(/* private fields */);

Adapt an already captured snapshot to an owned read-only handle without copying its contents. The caller must supply the snapshot selected for its visibility boundary; this adapter does not capture or advance that boundary.

Implementations

impl<T: VectorRead + 'static> ReadOnlySnapshot<T>

pub fn with_canonical_vectors( self, control: Option<&StorageReadControl>, ) -> StorageBackendResult<Self>

Expose canonical values from an already captured immutable owner without copying coordinates or its directory. Cache owners may remain unbound; each reader later binds its own cancellation. A supplied control admits the facet header, while None preserves the existing uncontrolled snapshot API. The unique view identity is conservative across independently captured equal corpora and stable across shared/nested readers.

impl ReadOnlySnapshot<dyn InvertedIndex>

pub fn from_budgeted_inverted<T: InvertedIndex + 'static>( snapshot: Budgeted<T>, ) -> StorageBackendResult<Self>

Erase a captured provider’s concrete type after reserving its shared allocation, keeping all producer leases with the immutable index.

impl<T: InvertedIndex + ?Sized> ReadOnlySnapshot<T>

pub fn with_inverted_read_control( self, control: &StorageReadControl, ) -> StorageBackendResult<Self>

Retain the first selected read control. Generation reservations can be shared without giving an unrelated reader the prior reader’s cancellation signal.

impl<T: VectorIndex + ?Sized> ReadOnlySnapshot<T>

pub fn with_vector_read_control( self, control: &StorageReadControl, ) -> StorageBackendResult<Self>

Select query control for an already captured physical value. Cache owners bind each returned reader separately; nested readers preserve the first selected allowance and cancellation token.

impl<T> ReadOnlySnapshot<T>

pub fn from_budgeted(snapshot: Budgeted<T>) -> StorageBackendResult<Self>

Share a captured value without separating its allocations from their original allowance.

impl<T: ?Sized> ReadOnlySnapshot<T>

pub fn new(snapshot: Arc<T>) -> Self

Trait Implementations

impl<T: ?Sized> Clone for ReadOnlySnapshot<T>

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T: ?Sized> Deref for ReadOnlySnapshot<T>

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &T

Dereferences the value.

impl DocumentStore for ReadOnlySnapshot<dyn DocumentStore>

fn put_stored( &mut self, _doc_id: DocId, _document: StoredDocument, ) -> StorageBackendResult<()>

Persist one typed storage record. Every backend owns the physical representation of tuple metadata and must keep it outside the public field map.

fn get_stored( &self, doc_id: DocId, ) -> StorageBackendResult<Option<StoredDocument>>

Read one typed storage record without projecting metadata into user fields.

fn get_stored_many_controlled( &self, ids: &[DocId], control: &StorageReadControl, ) -> StorageBackendResult<RetainedDocumentPage>

Read one fixed view into a charged page in exactly the requested order, preserving duplicates and missing rows. The page and every decoded field payload retain the invoking allowance. Unsupported providers must not fall back to unbounded owned materialization.

fn with_field_ref_controlled( &self, id: DocId, field: &str, control: &StorageReadControl, visitor: &mut dyn FnMut(Option<&Value>) -> StorageBackendResult<()>, ) -> StorageBackendResult<()>

Borrow one selected field, preserving absence versus stored NULL. The visitor runs exactly once while the provider keeps the value and its decoding allowance alive. Immutable stores can lend an existing scalar without allocating a projection or presence page.

fn field_presence_controlled( &self, ids: &[DocId], fields: &[&str], control: &StorageReadControl, ) -> StorageBackendResult<BudgetedVec<bool>>

Read field existence on one selected view, in document-major and then field order. A stored NULL is present; an absent field or document is not. The returned boolean buffer retains the invoking allowance. The default uses controlled rows without invoking legacy owned materializers; stores can inspect their existing field layout without copying values.

fn put( &mut self, _doc_id: DocId, _document: Document, ) -> StorageBackendResult<()>

Replace public fields while preserving metadata already owned by the stored tuple. Engine code that creates a new tuple version must call DocumentStore::put_stored with the new metadata explicitly.

fn get(&self, doc_id: DocId) -> StorageBackendResult<Option<Document>>

fn get_stored_many( &self, doc_ids: &[DocId], ) -> StorageBackendResult<BTreeMap<DocId, StoredDocument>>

Bulk variant of DocumentStore::get_stored.

fn get_metadata( &self, doc_id: DocId, ) -> StorageBackendResult<Option<DocumentMetadata>>

Read one tuple’s storage metadata without exposing it as a field.

fn contains_doc_id(&self, doc_id: DocId) -> StorageBackendResult<bool>

fn delete(&mut self, _doc_id: DocId) -> StorageBackendResult<()>

fn clear(&mut self) -> StorageBackendResult<()>

fn get_field( &self, doc_id: DocId, field: &str, ) -> StorageBackendResult<Option<Value>>

Read a single field. Returns an owned Value so persistent backends (SQLite, …) can decode on demand without reaching for a reference into a transient row.

fn find_doc_id_by_field( &self, field: &str, value: &Value, ) -> StorageBackendResult<Option<DocId>>

Find the first document whose top-level field equals value. Persistent stores can override this with an indexed or JSON-path lookup so point updates do not have to materialise every row.

fn patch_fields( &mut self, _doc_id: DocId, _updates: &BTreeMap<String, Value>, ) -> StorageBackendResult<bool>

Apply top-level field updates without requiring callers to materialise the whole document. Value::Null matches put by removing the stored field. Ok(false) means the document does not exist; write failures surface as Err.

fn get_many( &self, doc_ids: &[DocId], ) -> StorageBackendResult<BTreeMap<DocId, Document>>

Bulk variant of DocumentStore::get. Ids without a stored document are absent from the result. The default implementation walks each id one at a time; persistent backends should override to batch the reads into few queries.

fn get_fields_multi( &self, doc_ids: &[DocId], fields: &[&str], ) -> StorageBackendResult<BTreeMap<DocId, Vec<Value>>>

Fetch several top-level fields for many documents. The result vector is aligned with fields; missing fields come back as Value::Null, ids without a document are absent. Persistent backends override this to extract all fields in one scan instead of materialising whole documents.

fn for_each_fields_multi( &self, doc_ids: &[DocId], fields: &[&str], visitor: &mut dyn FnMut(DocId, Vec<Value>) -> bool, ) -> StorageBackendResult<()>

Visit a column projection in the caller’s document-id order. The callback receives one owned row at a time, allowing scan and aggregate pipelines to avoid materialising a second doc-id map. Returning false stops the visit early. Missing documents yield a row of NULLs, matching row-evaluator semantics.

fn for_each_fields_multi_ref( &self, doc_ids: &[DocId], fields: &[&str], visitor: &mut dyn FnMut(DocId, &[&Value]) -> bool, ) -> StorageBackendResult<()>

Visit a column projection by reference when the backend can keep decoded values alive for the duration of the callback. The default adapter preserves the backend’s owned/batched projection path; in-memory stores override it to avoid cloning every projected value.

fn for_each_fields_multi_ref_with_presence( &self, doc_ids: &[DocId], fields: &[&str], visitor: &mut dyn FnMut(DocId, bool, &[&Value]) -> bool, ) -> StorageBackendResult<()>

Visit a projection together with whether each requested document actually exists. This avoids a separate contains_doc_id probe when a caller must distinguish a missing document from an existing document whose requested fields are all NULL.

fn get_shared_fields( &self, doc_ids: &[DocId], fields: &[&str], ) -> StorageBackendResult<Option<Vec<Option<SharedDocumentRow>>>>

Return rows aligned with doc_ids as shared positional projections when the backend owns stable decoded value vectors. None means the backend does not support zero-copy projection; entries inside the returned vector are None only for missing document ids.

fn get_fields_bulk( &self, doc_ids: &[DocId], field: &str, ) -> StorageBackendResult<BTreeMap<DocId, Value>>

Bulk variant of DocumentStore::get_field. The default implementation walks each id one at a time; persistent backends should override to run a single batched query.

fn has_value(&self, field: &str, value: &Value) -> StorageBackendResult<bool>

Return true if any document has field == value.

fn find_doc_id_by_fields( &self, fields: &[String], values: &[Value], ) -> StorageBackendResult<Option<DocId>>

Find the first document whose top-level fields match every requested value.

fn eval_path( &self, doc_id: DocId, path: &[PathSegment], ) -> StorageBackendResult<Option<Value>>

Evaluate a hierarchical path expression against a document.

fn doc_ids(&self) -> StorageBackendResult<Vec<DocId>>

fn next_doc_id( &self, after: Option<DocId>, ) -> StorageBackendResult<Option<DocId>>

Return the first stored document id strictly greater than after, or the first id when after is None. Scan operators use this cursor API so a full table scan does not need a cardinality-sized id vector before it can yield its first row.

fn next_doc_ids( &self, after: Option<DocId>, limit: usize, ) -> StorageBackendResult<Vec<DocId>>

Return up to limit document ids strictly greater than after, in ascending order. Scan operators use this bounded cursor instead of reacquiring their store lock and issuing one backend lookup per row.

fn next_doc_ids_controlled( &self, after: Option<DocId>, limit: usize, control: &StorageReadControl, ) -> StorageBackendResult<BudgetedVec<DocId>>

Read at most limit identities in strictly ascending order after after, retaining the supplied allowance with the output. Implementations reserve producer scratch and output before allocation, preserve this store’s selected view, and never read document payloads. The default rejects unsupported providers without calling an unbounded owned cursor; empty requests still honor cancellation. Controlled consumers use read_document_ids to validate the returned page and its allowance.

fn next_shared_fields( &self, after: Option<DocId>, limit: usize, fields: &[&str], ) -> StorageBackendResult<Option<Vec<(DocId, SharedDocumentRow)>>>

Return the next bounded id range and its shared positional projections in one storage traversal when stable decoded rows are available. None lets persistent backends use the ordinary id + projection path.

fn for_each_next_fields( &self, after: Option<DocId>, limit: usize, fields: &[&str], visitor: &mut dyn FnMut(DocId, &[&Value]) -> bool, ) -> StorageBackendResult<Option<usize>>

Visit the next bounded id range through a reusable borrowed projection of each backend-owned row. Missing fields are exposed as SQL NULL. Some(count) means the backend supports this borrowed cursor and reports how many rows it visited; None selects the ordinary cursor path without invoking visitor.

fn max_doc_id(&self) -> StorageBackendResult<DocId>

fn for_each_next_fields_borrowed( &self, after: Option<DocId>, limit: usize, fields: &[&str], visitor: &mut dyn FnMut(DocId, &[&Value]) -> bool, ) -> StorageBackendResult<Option<usize>>

Visit a bounded ascending projection while permitting the provider to retain a physical read borrow. The caller must not reenter storage, invoke host callbacks, or execute nested SQL from visitor. Missing fields are SQL NULL; stopping the visitor must not decode later rows. None must leave the visitor uncalled. Providers without a physical borrow reuse their ordinary projected cursor.

fn for_each_fields_multi_borrowed( &self, ids: &[DocId], fields: &[&str], visitor: &mut dyn FnMut(DocId, bool, &[&Value]) -> bool, ) -> StorageBackendResult<Option<usize>>

Visit requested point projections, including missing rows and duplicate IDs, in caller order while allowing a physical read borrow. Neither the visitor nor its callees may reenter storage, invoke host callbacks, or execute nested SQL. A stopped visitor must not read later IDs. Some(count) counts callbacks; None must leave the visitor uncalled and selects the ordinary projection path.

fn len(&self) -> StorageBackendResult<usize>

fn is_empty(&self) -> StorageBackendResult<bool>

fn iter_all( &self, ) -> StorageBackendResult<Box<dyn Iterator<Item = (DocId, Document)> + '_>>

Iterate over (doc_id, document) pairs in id order. The default implementation fetches each document individually; SQLite-backed stores override with a single query.

fn snapshot(&self) -> StorageBackendResult<Arc<dyn DocumentStore>>

Read-only handle suitable for an ExecutionContext. Persistent backends share their connection; memory backends deep-clone so the snapshot is isolated from later mutations.

fn retained_snapshot( &self, ) -> StorageBackendResult<Option<Arc<dyn DocumentStore>>>

Share an already immutable retained view, preserving its selected rows, allocation owners and cancellation boundary. This capability must not capture a new live view or copy row payloads. The default reports that controlled copying is required without invoking the legacy snapshot method, whose persistent implementations may share a mutable connection.

fn put_stored_unused( &mut self, doc_id: DocId, document: StoredDocument, namespace: DocumentIdNamespace, ) -> StorageBackendResult<()>

Persist a document whose identity no document of the table ever had, as the caller has established from the identity watermark of namespace. A provider that keys its records by that namespace may write them without reading what they would replace, and only while it stores the table under that namespace; a record that exists after all fails the commit. The default replaces as put_stored does.

fn writable_snapshot(&self) -> StorageBackendResult<Box<dyn DocumentStore>>

Independent writable copy used by the in-memory engine transaction rollback path. Persistent engines restore through their backend transaction and need not implement this operation.

impl InvertedIndex for ReadOnlySnapshot<dyn InvertedIndex>

fn source_rebuild_required(&self) -> StorageBackendResult<bool>

Whether persisted positional data must be rebuilt from original sources before this index can be read or mutated. The owning engine performs this after restoring exact analyzer revisions, in the same initial-open transaction.

fn analyzer(&self) -> &Analyzer

fn default_analyzer_binding(&self) -> StorageBackendResult<AnalyzerDefault>

Retain the exact default configuration, resource provider and already resolved revision without forcing deferred compilation. Controlled reconstruction requires this capability instead of copying and recompiling diagnostic configuration.

fn add_document( &mut self, _doc_id: DocId, _fields: BTreeMap<FieldName, String>, ) -> StorageBackendResult<()>

fn try_add_document( &mut self, _doc_id: DocId, _fields: BTreeMap<FieldName, String>, ) -> StorageBackendResult<()>

fn try_add_documents( &mut self, _documents: Vec<(DocId, BTreeMap<FieldName, String>)>, ) -> StorageBackendResult<()>

Add or replace several documents in input order. The default preserves the point-mutation contract for custom backends; transactional persistent backends can override this to make the call atomic and coalesce writes that share physical posting clusters.

fn try_add_documents_observed( &mut self, _documents: Vec<(DocId, BTreeMap<FieldName, String>)>, _visit: &mut InvertedIndexChangeVisitor<'_>, ) -> StorageBackendResult<()>

Capture logical changes from the same analysis and original reverse entries used by the atomic replacement. The visitor must not reenter this provider. A transaction owner discards captured changes on error and registers successful intents before completing its statement; private writes and intents must share savepoint undo.

fn try_remove_document_observed( &mut self, _doc_id: DocId, _visit: &mut InvertedIndexChangeVisitor<'_>, ) -> StorageBackendResult<()>

Deletion captures the original analyzed terms without reconstructing the document or rerunning its analyzer. An absent document produces no logical change.

fn remove_document(&mut self, _doc_id: DocId) -> StorageBackendResult<()>

fn try_remove_document(&mut self, _doc_id: DocId) -> StorageBackendResult<()>

fn clear(&mut self) -> StorageBackendResult<()>

fn try_clear(&mut self) -> StorageBackendResult<()>

fn try_rebuild_documents( &mut self, _documents: Vec<(DocId, BTreeMap<FieldName, String>)>, ) -> StorageBackendResult<()>

fn get_posting_list( &self, field: &str, term: &str, ) -> StorageBackendResult<PostingList>

fn get_posting_list_key( &self, field: &str, term: &TokenTermKey, ) -> StorageBackendResult<PostingList>

Unique-position compatibility projection for an exact term key. Legacy providers accept scalar keys and reject unpaired UTF-16 explicitly.

fn posting_cursor_key( &self, field: &str, term: &TokenTermKey, ) -> StorageBackendResult<Box<dyn PostingCursor>>

Score cursor with exact term identity and occurrence frequency independent of unique positions.

fn posting_read_cursor_key<'a>( &'a self, field: &'a str, term: &TokenTermKey, ) -> StorageBackendResult<Box<dyn PostingReadCursor + 'a>>

Traverse candidates while retaining this index read. Providers with borrowed posting maps can avoid copying the entire term support; owned persistent cursors keep their incremental reads.

fn posting_read_cursor_key_budgeted<'a>( &'a self, field: &'a str, term: &'a TokenTermKey, control: &StorageReadControl, ) -> StorageBackendResult<BudgetedPostingReadCursor<'a>>

Open a cursor that owns every query allocation under the supplied allowance. Providers must implement this capability without an unbounded materialization fallback.

fn visit_score_clusters( &self, field: &str, term: &TokenTermKey, after: Option<u64>, limit: usize, control: &StorageReadControl, visit: &mut ScoreClusterVisitor<'_>, ) -> StorageBackendResult<()>

Visit encoded score clusters in ascending order under the retained provider read. Temporary payloads must be reserved before fetching; callbacks must not reenter the provider.

fn get_occurrences_budgeted( &self, doc_id: DocId, field: &str, term: &TokenTermKey, control: &StorageReadControl, ) -> StorageBackendResult<Budgeted<Vec<TokenOccurrence>>>

Decode one document’s exact occurrences with provider-owned input and output reservations and cancellation checks.

fn get_occurrence_postings( &self, field: &str, term: &TokenTermKey, ) -> StorageBackendResult<Vec<OccurrencePosting>>

Complete graph edges in document order, preserving occurrence multiplicity and original source coordinates. Legacy positions cannot implement this contract without a source rebuild.

fn get_occurrences( &self, doc_id: DocId, field: &str, term: &TokenTermKey, ) -> StorageBackendResult<Vec<TokenOccurrence>>

Exact occurrences for one document and term; an absent document or term has no occurrences.

fn indexed_field_metadata( &self, doc_id: DocId, field: &str, ) -> StorageBackendResult<Option<IndexedFieldMetadata>>

Original stream-end state and revision metadata published with a document field, including fields that emitted no tokens.

fn doc_freq_key( &self, field: &str, term: &TokenTermKey, ) -> StorageBackendResult<u64>

fn get_term_freq_key( &self, doc_id: DocId, field: &str, term: &TokenTermKey, ) -> StorageBackendResult<u64>

fn vocabulary_keys( &self, field: &str, ) -> StorageBackendResult<Vec<TokenTermKey>>

Sorted canonical term keys, including unpaired units. String-only vocabulary APIs must return an error if projection would lose identity.

fn get_posting_lists_bulk( &self, field: &str, terms: &[String], ) -> StorageBackendResult<Vec<PostingList>>

fn posting_cursor( &self, field: &str, term: &str, ) -> StorageBackendResult<Box<dyn PostingCursor>>

Open a doc-id ordered score cursor for one term.

fn posting_cursors_bulk( &self, field: &str, terms: &[String], ) -> StorageBackendResult<Vec<Box<dyn PostingCursor>>>

fn posting_cursors_keys_bulk( &self, field: &str, terms: &[TokenTermKey], ) -> StorageBackendResult<Vec<Box<dyn PostingCursor>>>

Open exact-key cursors in input order, retaining repeated query terms. Scalar custom backends retain their optimized bulk implementation.

fn get_posting_lists_keys_bulk( &self, field: &str, terms: &[TokenTermKey], ) -> StorageBackendResult<Vec<PostingList>>

Read exact-key support without projecting UTF-16 term identity.

fn persisted_block_max_scores_keys_bulk( &self, field: &str, terms: &[TokenTermKey], scorer_fingerprint: &str, ) -> StorageBackendResult<Vec<Option<Vec<f64>>>>

Load exact-key scorer-versioned bounds. Custom scalar providers expose no raw-key materialization by default.

fn get_scoring_inputs_keys_bulk( &self, doc_ids: &[DocId], field: &str, terms: &[TokenTermKey], ) -> StorageBackendResult<Vec<(u64, Vec<u64>)>>

Exact-key scoring inputs aligned with both the document and query-term arrays, including repetitions.

fn rebuild_persisted_block_max( &mut self, _field: &str, _scorer: &dyn BlockMaxScorer, _scorer_fingerprint: &str, ) -> StorageBackendResult<bool>

Persist scorer-specific block maxima for every term in field.

fn persisted_block_max_scores( &self, field: &str, term: &str, scorer_fingerprint: &str, ) -> StorageBackendResult<Option<Vec<f64>>>

Load scorer-versioned block maxima for one posting list. None means the backend has no complete, valid materialization for this scorer.

fn persisted_block_max_scores_bulk( &self, field: &str, terms: &[String], scorer_fingerprint: &str, ) -> StorageBackendResult<Vec<Option<Vec<f64>>>>

Load scorer-versioned block maxima for several terms while preserving input order; persistent backends override this to avoid one storage round trip per term.

fn for_each_posting( &self, field: &str, term: &str, visit: &mut dyn FnMut(&PostingEntry), ) -> StorageBackendResult<()>

Visit every legacy unique-position projection for (field, term) in ascending doc-id order without handing out an owned list.

fn for_each_term_freq( &self, field: &str, term: &str, visit: &mut dyn FnMut(DocId, u64), ) -> StorageBackendResult<()>

Visit (doc_id, term_frequency) pairs without requiring callers to materialize or decode payload details they do not use. The default uses posting support and the authoritative frequency accessor; persistent backends can stream compact frequency projections.

fn doc_freq(&self, field: &str, term: &str) -> StorageBackendResult<u64>

fn get_doc_length( &self, doc_id: DocId, field: &str, ) -> StorageBackendResult<u64>

fn get_term_freq( &self, doc_id: DocId, field: &str, term: &str, ) -> StorageBackendResult<u64>

fn doc_count(&self) -> StorageBackendResult<u64>

fn total_field_length(&self, field: &str) -> StorageBackendResult<u64>

fn field_doc_count(&self, field: &str) -> StorageBackendResult<u64>

Number of documents that have indexed content for field.

fn field_stats(&self, field: &str) -> StorageBackendResult<IndexStats>

Field-specific statistics for BM25 scoring.

fn field_stats_scalar(&self, field: &str) -> StorageBackendResult<IndexStats>

InvertedIndex::field_stats without the vocabulary-wide document-frequency map.

fn field_stats_scalar_budgeted( &self, field: &str, control: &StorageReadControl, ) -> StorageBackendResult<IndexStats>

Read only field scoring scalars with producer-owned temporary reservations.

fn vocabulary_terms(&self, field: &str) -> StorageBackendResult<Vec<String>>

Sorted unique indexed terms for field.

fn stats(&self) -> StorageBackendResult<IndexStats>

Fully-populated IndexStats snapshot for the cost model and scoring layer. Implementations may cache this between mutations.

fn posting_count(&self, field: Option<&str>) -> StorageBackendResult<u64>

Number of posting rows. With field = Some(..), limits the count to one indexed field.

fn doc_length_count(&self, field: Option<&str>) -> StorageBackendResult<u64>

Number of (doc_id, field) length rows. With field = Some(..), this is the number of documents indexed for that field.

fn term_count(&self, field: Option<&str>) -> StorageBackendResult<u64>

Number of distinct indexed terms. With field = Some(..), limits the count to one indexed field.

fn snapshot(&self) -> StorageBackendResult<Arc<dyn InvertedIndex>>

Read-only handle suitable for an ExecutionContext.

fn snapshot_with_control( &self, control: &StorageReadControl, ) -> StorageBackendResult<Arc<dyn InvertedIndex>>

Capture the selected view with its caller’s retention allowance. Providers that already retain their own read boundary preserve it; memory owners override this hook to charge their shared state before publication.

fn field_names(&self) -> StorageBackendResult<Vec<FieldName>>

Names of every field with at least one indexed document. Default implementation walks the IndexStats snapshot’s total-length map. Backends with a richer schema can override.

fn get_posting_list_any_field( &self, term: &str, ) -> StorageBackendResult<PostingList>

Posting list for term across every indexed field, unioned together. Default implementation sums per-field posting lists via PostingList::merge_union.

fn doc_freq_any_field(&self, term: &str) -> StorageBackendResult<u64>

Document frequency of term across every indexed field.

fn get_total_doc_length(&self, doc_id: DocId) -> StorageBackendResult<u64>

Sum of all per-field token lengths for a single doc.

fn get_doc_lengths_bulk( &self, doc_ids: &[DocId], field: &str, ) -> StorageBackendResult<BTreeMap<DocId, u64>>

Bulk doc-length lookup. Default falls back to per-id calls.

fn get_term_freqs_bulk( &self, doc_ids: &[DocId], field: &str, term: &str, ) -> StorageBackendResult<BTreeMap<DocId, u64>>

Bulk term-frequency lookup. Default falls back to per-id calls.

fn get_scoring_inputs_bulk( &self, doc_ids: &[DocId], field: &str, terms: &[String], ) -> StorageBackendResult<Vec<(u64, Vec<u64>)>>

Fetch the document length and one term frequency per query term for every requested document. Results stay aligned with doc_ids. Persistent backends override this to collapse the scoring loop’s per-document point reads into a small number of set-oriented queries.

fn get_total_term_freq( &self, doc_id: DocId, term: &str, ) -> StorageBackendResult<u64>

Total term frequency for a doc summed across every indexed field.

fn set_field_analyzer( &mut self, _field: &str, _analyzer: Analyzer, _phase: AnalyzerPhase, ) -> Result<(), String>

Bind an analyzer to a single field for the given phase. Both writes to both the index-side and search-side maps; the default impl errors so backends that don’t support per-field analyzers fail loud rather than silently dropping the request.

fn remove_field_analyzers(&mut self, _field: &str) -> Result<(), String>

Remove every per-field analyzer override for field. This is the inverse of set_field_analyzer(..., Both) and is required when the final logical FTS index for a field is dropped. The default errors so a backend cannot silently retain stale analysis behavior.

fn get_field_analyzer(&self, field: &str) -> Analyzer

Index-time analyzer for field; falls back to InvertedIndex::analyzer when no override is set.

fn get_search_analyzer(&self, field: &str) -> Analyzer

Compatibility configuration for search. Built-in providers return their independent retained search revision’s inputs; this default preserves the index fallback for custom legacy providers. Use search_analyzer_revision for execution with exact resource ownership.

fn index_analyzer_revision( &self, field: &str, ) -> StorageBackendResult<Arc<CompiledAnalyzer>>

Retain the exact executable index revision. Built-in providers resolve their default once and keep field revisions immutable.

fn search_analyzer_revision( &self, field: &str, ) -> StorageBackendResult<Arc<CompiledAnalyzer>>

Retain the exact executable search revision independently of subsequent index assignments.

fn set_field_analyzer_revision( &mut self, _field: &str, _revision: Arc<CompiledAnalyzer>, _phase: AnalyzerPhase, ) -> Result<(), String>

Install a validated revision without reopening its resources. This does not rebuild existing documents; graph providers reject a different index revision on a populated field and require rebuild_with_analyzer_revision instead.

fn set_field_analyzer_revisions( &mut self, _field: &str, _index: Arc<CompiledAnalyzer>, _search: Arc<CompiledAnalyzer>, ) -> Result<(), String>

Install a complete retained pair atomically. Failure changes neither side; this does not rebuild existing postings.

fn rebuild_with_analyzer_revision( &mut self, _field: &str, _revision: Arc<CompiledAnalyzer>, _phase: AnalyzerPhase, _documents: Vec<(DocId, BTreeMap<FieldName, String>)>, ) -> StorageBackendResult<()>

Replace the complete indexed document set and selected analyzer sides together. Failure retains the previous postings and bindings; providers must implement their own atomic publication.

fn try_rebuild_documents_cancellable( &mut self, _documents: Vec<(DocId, BTreeMap<FieldName, String>)>, _cancellation: &CancellationToken, ) -> StorageBackendResult<()>

Rebuild under the caller’s cancellation token. Cancellation must retain the complete previous index; custom providers must implement atomic staging and cancellation.

fn rebuild_with_analyzer_revision_cancellable( &mut self, _field: &str, _revision: Arc<CompiledAnalyzer>, _phase: AnalyzerPhase, _documents: Vec<(DocId, BTreeMap<FieldName, String>)>, _cancellation: &CancellationToken, ) -> StorageBackendResult<()>

Replace postings and selected analyzer revisions together, retaining both on cancellation before publication.

fn writable_snapshot(&self) -> StorageBackendResult<Box<dyn InvertedIndex>>

Independent writable copy used to restore an in-memory engine transaction without reconstructing analyzer state from documents.

impl<T: VectorIndex + ?Sized + 'static> VectorIndex for ReadOnlySnapshot<T>

fn dimensions(&self) -> u32

fn index_kind(&self) -> &'static str

fn diskann_query_metadata( &self, control: &StorageReadControl, ) -> StorageBackendResult<Option<DiskANNQueryMetadata>>

Metadata from the actual selected physical/canonical view, without executing a logical vector query. Unsupported methods return None.

fn add(&mut self, _doc_id: DocId, _vector: Vec<f32>) -> StorageBackendResult<()>

fn add_many( &mut self, _doc_id: DocId, _vectors: Vec<Vec<f32>>, ) -> StorageBackendResult<()>

fn delete(&mut self, _doc_id: DocId) -> StorageBackendResult<()>

fn clear(&mut self) -> StorageBackendResult<()>

fn search_knn( &self, query: &[f32], k: usize, ) -> StorageBackendResult<PostingList>

fn search_threshold( &self, query: &[f32], threshold: f32, ) -> StorageBackendResult<PostingList>

fn search_knn_with_control( &self, query: &[f32], k: usize, control: &StorageReadControl, ) -> StorageBackendResult<PostingList>

Request a controlled search. The default checks cancellation and delegates to the provider’s existing read boundary; in-memory physical algorithms override it to charge query workspace to the supplied allowance.

fn search_threshold_with_control( &self, query: &[f32], threshold: f32, control: &StorageReadControl, ) -> StorageBackendResult<PostingList>

Controlled threshold search keeps the same result and caller-owned posting boundary as ordinary search.

fn search_knn_with_statistics( &self, query: &[f32], k: usize, control: Option<&StorageReadControl>, ) -> StorageBackendResult<VectorQueryResult>

Run one KNN invocation and retain its measured work when supported. An optional invoking control preserves the existing controlled-search boundary; absence preserves ordinary provider dispatch. Unsupported providers execute once and return no report.

fn search_threshold_with_statistics( &self, query: &[f32], threshold: f32, control: Option<&StorageReadControl>, ) -> StorageBackendResult<VectorQueryResult>

Return exact threshold results and optional work from their one invocation. Report support must not introduce an additional scan or weaken the original provider’s controls.

fn count(&self) -> StorageBackendResult<usize>

fn contains_document(&self, doc_id: DocId) -> StorageBackendResult<bool>

Test canonical membership at this handle’s visibility boundary without searching or materializing the corpus. Empty tensor replacements have no membership. This is a maintenance probe, not a logical query observation.

fn initialize(&mut self) -> StorageBackendResult<()>

Build any auxiliary physical metadata required by this index from its current vector contents. Brute-force indexes need no extra work; persistent IVF and HNSW implementations use this during explicit index creation, while restore paths deliberately skip it.

fn snapshot(&self) -> StorageBackendResult<Arc<dyn VectorIndex>>

Read-only handle suitable for an ExecutionContext.

fn vector_read_snapshot( &self, control: &StorageReadControl, ) -> StorageBackendResult<Option<VectorReadSnapshot>>

Retain the actual canonical values independently of physical mutation provenance. Capturing this source is metadata access, not a logical vector query.

fn snapshot_with_vector_read( &self, source: VectorReadSnapshot, control: &StorageReadControl, ) -> StorageBackendResult<Option<Arc<dyn VectorIndex>>>

Keep this selected physical DiskANN generation while reading a different fixed canonical field view. The query owner verifies raw coverage without inventing mutation origins.

fn diskann_read_snapshot( &self, control: &StorageReadControl, ) -> StorageBackendResult<Option<DiskANNReadSnapshot>>

Borrow an opaque retained DiskANN canonical source for evaluated document replacements. Capturing metadata does not execute or observe a vector query; other physical methods leave this capability absent.

fn snapshot_with_diskann_changes( &self, changes: &DiskANNReadChanges, control: &StorageReadControl, ) -> StorageBackendResult<Option<Arc<dyn VectorIndex>>>

Retain this physical DiskANN generation with the selected actual canonical replacements. Wrappers preserve their original read observation and retention boundary on the returned index. Unsupported methods return None without changing physical selection.

fn snapshot_with_control( &self, control: &StorageReadControl, ) -> StorageBackendResult<Arc<dyn VectorIndex>>

Capture using the caller’s retention allowance and cancellation. Owners that copy index data override this method to reserve construction before allocation. The default preserves the provider’s existing snapshot and its independently retained control.

fn writable_snapshot(&self) -> StorageBackendResult<Box<dyn VectorIndex>>

Independent writable copy used by in-memory engine rollback. The default keeps third-party and persistent implementations source compatible; only indexes hosted by a memory engine need to support it.

impl<T: VectorRead + ?Sized> VectorRead for ReadOnlySnapshot<T>

fn corpus_fingerprint( &self, control: &StorageReadControl, ) -> StorageBackendResult<Option<[u8; 32]>>

Trustworthy identity of this complete fixed field, obtained from retained metadata. None means fixed-model reuse cannot be verified; callers must not replace it with a user-supplied label.

fn check_control( &self, control: &StorageReadControl, ) -> StorageBackendResult<()>

fn dimensions(&self) -> u32

fn next_document_after( &self, after: Option<DocId>, control: &StorageReadControl, ) -> StorageBackendResult<Option<DocId>>

fn document_vector_count( &self, document: DocId, control: &StorageReadControl, ) -> StorageBackendResult<u64>

Validate contiguous ordinal keys and return their count. Missing and explicitly empty tensors both have zero vectors.

fn read_vector( &self, document: DocId, ordinal: u32, control: &StorageReadControl, ) -> StorageBackendResult<Option<BudgetedVec<f32>>>

Read one ordinal without invoking a caller while a provider read lock is held. Absent ordinals return None; malformed values fail.