Struct FtsIndex 

pub struct FtsIndex<B>
where
    B: FtsBackend,
{ /* private fields */ }

Full-text search index generic over storage backend.

Provides identical indexing, search, and highlighting logic for Origin (redb), Lite (in-memory), and WASM deployments.

Writes accumulate in an in-memory Memtable. When the memtable exceeds its threshold, it is flushed to an immutable segment stored via the backend. Queries merge the active memtable with all persisted segments.

An optional MemoryGovernor can be injected via FtsIndex::set_governor to enforce per-engine memory budgets on large allocations (compaction, segment merge, query term collection). When no governor is set, allocations proceed without budget enforcement — which is the correct behaviour for NodeDB-Lite and WASM deployments where nodedb-mem is not available.

Implementations

impl<B> FtsIndex<B>

where B: FtsBackend,

pub fn highlight( &self, text: &str, query: &str, prefix: &str, suffix: &str, ) -> String

Generate highlighted text with matched query terms wrapped in tags.

Returns the original text with each occurrence of a matched query term surrounded by prefix and suffix (e.g., <b> and </b>).

pub fn offsets(&self, text: &str, query: &str) -> Vec<MatchOffset>

Return byte offsets of matched query terms in the original text.

impl<B> FtsIndex<B>

where B: FtsBackend,

pub fn set_collection_analyzer( &self, tid: u64, collection: &str, analyzer_name: &str, ) -> Result<(), <B as FtsBackend>::Error>

Set the analyzer for a collection. Persists to backend metadata.

pub fn set_collection_language( &self, tid: u64, collection: &str, lang_code: &str, ) -> Result<(), <B as FtsBackend>::Error>

Set the language for a collection. Persists to backend metadata.

pub fn get_collection_analyzer( &self, tid: u64, collection: &str, ) -> Result<Option<String>, <B as FtsBackend>::Error>

Get the configured analyzer name for a collection.

pub fn get_collection_language( &self, tid: u64, collection: &str, ) -> Result<Option<String>, <B as FtsBackend>::Error>

Get the configured language for a collection.

pub fn analyze_for_collection( &self, tid: u64, collection: &str, text: &str, ) -> Result<Vec<String>, <B as FtsBackend>::Error>

Analyze text using the collection’s configured analyzer.

Falls back to the standard English analyzer if no analyzer is configured.

pub fn tokenize_raw_for_collection( &self, tid: u64, collection: &str, text: &str, ) -> Result<Vec<String>, <B as FtsBackend>::Error>

Tokenize text WITHOUT stemming for fuzzy matching.

impl<B> FtsIndex<B>

where B: FtsBackend,

pub fn read_fieldnorm( &self, tid: u64, collection: &str, doc_id: Surrogate, ) -> Result<Option<u32>, <B as FtsBackend>::Error>

Get the fieldnorm (SmallFloat-encoded doc length) for a doc.

Returns the decoded approximate u32 length, or None if not stored.

pub fn write_fieldnorm( &self, tid: u64, collection: &str, doc_id: Surrogate, doc_length: u32, ) -> Result<(), <B as FtsBackend>::Error>

Write a fieldnorm byte for a surrogate. Grows the array if needed.

impl<B> FtsIndex<B>

where B: FtsBackend,

pub fn index_stats( &self, tid: u64, collection: &str, ) -> Result<(u32, f32), <B as FtsBackend>::Error>

Get total document count and average document length for a collection.

Returns (total_docs, avg_doc_len). If the collection is empty, returns (0, 1.0) to avoid division by zero.

impl<B> FtsIndex<B>

where B: FtsBackend,

pub fn put_synonym_group( &self, tid: u64, record: &SynonymGroupRecord, ) -> Result<(), <B as FtsBackend>::Error>

Persist a synonym group. Overwrites any existing group with the same name.

pub fn delete_synonym_group( &self, tid: u64, name: &str, ) -> Result<bool, <B as FtsBackend>::Error>

Delete a synonym group. Returns true if it existed.

pub fn get_synonym_group( &self, tid: u64, name: &str, ) -> Result<Option<SynonymGroupRecord>, <B as FtsBackend>::Error>

Read a single synonym group by name. Returns None if not found or tombstoned.

pub fn list_synonym_groups( &self, tid: u64, ) -> Result<Vec<SynonymGroupRecord>, <B as FtsBackend>::Error>

List all synonym group records for a tenant.

pub fn build_synonym_map_for_tenant( &self, _tid: u64, all_groups: &[SynonymGroupRecord], ) -> SynonymMap

Build an in-memory SynonymMap from a slice of synonym group records.

Each term in every group maps to all other terms in that group (bidirectional OR-expansion). Terms are analyzed with the default analyzer so synonym keys match the stemmed tokens produced at query time by search_with_mode.

pub fn expand_query_with_synonyms( &self, tid: u64, tokens: Vec<String>, ) -> Result<Vec<String>, <B as FtsBackend>::Error>

Load all synonym groups for a tenant and build the expansion map.

Called at FTS query time inside search_with_mode to expand query tokens before BM25 scoring.

impl<B> FtsIndex<B>

where B: FtsBackend,

pub fn new(backend: B) -> FtsIndex<B>

Create a new FTS index with the given backend and default BM25 params.

pub fn with_params(backend: B, params: Bm25Params) -> FtsIndex<B>

Create a new FTS index with custom BM25 parameters.

pub fn set_governor(&mut self, governor: Arc<MemoryGovernor>)

Inject a MemoryGovernor to enforce per-engine memory budgets on large allocations (compaction, merge, query). When not set, all allocations proceed without budget enforcement.

This is the correct pattern for Origin deployments. NodeDB-Lite and WASM builds should leave the governor unset (no nodedb-mem dependency).

pub fn backend(&self) -> &B

Access the underlying backend.

pub fn backend_mut(&mut self) -> &mut B

Mutable access to the underlying backend.

pub fn memtable(&self) -> &Memtable

Access the active memtable (for LSM query merging).

pub fn index_document( &self, tid: u64, collection: &str, doc_id: Surrogate, text: &str, ) -> Result<(), FtsIndexError<<B as FtsBackend>::Error>>

Index a document’s text content.

Returns Err(FtsIndexError::SurrogateOutOfRange) if doc_id is Surrogate::ZERO (the unassigned sentinel) or exceeds MAX_INDEXABLE_SURROGATE. The FTS memtable uses the surrogate’s raw u32 value as a direct array index into per-doc fieldnorm storage; values near u32::MAX would cause multi-GiB allocations. Rejecting out-of-range surrogates at this boundary is the correct fix — not a debug_assert!, which would be a silent-wrap equivalent.

pub fn remove_document( &self, tid: u64, collection: &str, doc_id: Surrogate, ) -> Result<(), <B as FtsBackend>::Error>

Remove a document from the index.

pub fn purge_collection( &self, tid: u64, collection: &str, ) -> Result<usize, <B as FtsBackend>::Error>

Purge all entries for a collection. Returns count of removed entries.

pub fn purge_tenant(&self, tid: u64) -> Result<usize, <B as FtsBackend>::Error>

Purge all entries for a tenant across every collection.

impl<B> FtsIndex<B>

where B: FtsBackend,

pub fn search( &self, tid: u64, collection: &str, query: &str, top_k: usize, fuzzy_enabled: bool, prefilter: Option<&SurrogateBitmap>, ) -> Result<Vec<TextSearchResult>, FtsIndexError<<B as FtsBackend>::Error>>

Search the index using BM25 scoring.

Supports NOT <term> and -<term> negation in the query string. Returns Err(FtsIndexError::InvalidQuery) for ill-formed queries such as NOT-only queries or unsupported parenthesised groups.

pub fn search_with_mode( &self, tid: u64, collection: &str, query: &str, top_k: usize, fuzzy_enabled: bool, mode: QueryMode, prefilter: Option<&SurrogateBitmap>, ) -> Result<Vec<TextSearchResult>, FtsIndexError<<B as FtsBackend>::Error>>

Search with explicit boolean mode (AND or OR).

Supports NOT <term> and -<term> negation in the query string.