Struct KeyValueInvertedIndex 

pub struct KeyValueInvertedIndex { /* private fields */ }

Inverted index implemented over KeyValueStore.

Implementations

impl KeyValueInvertedIndex

pub fn flush_skip_pointers(&self) -> StorageBackendResult<()>

pub fn skip_to( &self, field: &str, term: &str, target: DocId, ) -> StorageBackendResult<(DocId, usize)>

pub fn build_block_max_scores_key<S: BlockMaxScorer + ?Sized>( &self, field: &str, term: &TokenTermKey, scorer: &S, fingerprint: &str, ) -> StorageBackendResult<()>

pub fn build_all_block_max_scores<S: BlockMaxScorer + ?Sized>( &self, field: &str, scorer: &S, ) -> StorageBackendResult<()>

pub fn get_block_max_score( &self, field: &str, term: &str, block: usize, ) -> StorageBackendResult<f64>

pub fn get_all_block_max_scores_key( &self, field: &str, term: &TokenTermKey, ) -> StorageBackendResult<Vec<f64>>

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

pub fn load_block_max_into( &self, target: &mut BlockMaxIndex, ) -> StorageBackendResult<()>

impl KeyValueInvertedIndex

pub fn snapshot_from_read( read: &dyn KeyValueRead, table: &str, bindings: &AnalyzerBindings, ) -> StorageBackendResult<Arc<dyn InvertedIndex>>

Capture a provider’s selected occurrence view without first cloning its analyzer bindings or table metadata into an intermediate live index.

impl KeyValueInvertedIndex

pub fn new( store: Arc<dyn KeyValueStore>, table: impl Into<String>, analyzer: Analyzer, ) -> Self

pub fn from_storage( storage: Arc<dyn OccurrenceStorage>, table: impl Into<String>, bindings: AnalyzerBindings, ) -> Self

Bind the common occurrence algorithms to a provider’s native row projection while preserving the already compiled analyzer revisions.

pub fn analyzer_bindings(&self) -> &AnalyzerBindings

Compiled bindings used by this index, including successful native-provider binding changes.

Trait Implementations

impl Clone for KeyValueInvertedIndex

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl InvertedIndex for KeyValueInvertedIndex

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 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 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 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 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 field_stats_scalar_budgeted( &self, field: &str, control: &StorageReadControl, ) -> StorageBackendResult<IndexStats>

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

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 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 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 remove_document(&mut self, doc_id: DocId) -> StorageBackendResult<()>

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

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 clear(&mut self) -> 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( &self, field: &str, term: &str, ) -> StorageBackendResult<Box<dyn PostingCursor>>

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

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 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 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 doc_freq_key( &self, field: &str, term: &TokenTermKey, ) -> StorageBackendResult<u64>

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

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_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 get_term_freq( &self, doc_id: DocId, field: &str, term: &str, ) -> StorageBackendResult<u64>

fn get_term_freq_key( &self, doc_id: DocId, field: &str, term: &TokenTermKey, ) -> 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 vocabulary_terms(&self, field: &str) -> StorageBackendResult<Vec<String>>

Sorted unique indexed terms for field.

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 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 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 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 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 get_posting_lists_bulk( &self, field: &str, terms: &[String], ) -> StorageBackendResult<Vec<PostingList>>

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 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 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_total_term_freq( &self, doc_id: DocId, term: &str, ) -> StorageBackendResult<u64>

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

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 try_add_document( &mut self, doc_id: DocId, fields: BTreeMap<FieldName, String>, ) -> StorageBackendResult<()>

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 try_remove_document(&mut self, doc_id: DocId) -> StorageBackendResult<()>

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

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 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 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 writable_snapshot(&self) -> StorageBackendResult<Box<dyn InvertedIndex>>

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