Struct Store 

pub struct Store { /* private fields */ }

One explicitly closeable embedded-store handle.

Implementations

impl Store

pub fn self_check(&self, sample: usize, seed: u64) -> SelfCheckReport

Samples stored vectors deterministically and reports live-plan recall against a full-precision brute-force oracle.

pub fn health(&self) -> Result<Health, StoreError>

Returns current store health without changing engine behaviour.

impl Store

pub fn switch_epoch_alias( &self, target: EpochIdentity, ) -> Result<EpochAliasReport, EpochTransitionError>

Atomically publishes a registered epoch whose segments are retained.

pub fn drop_epoch( &self, target: EpochId, ) -> Result<DropEpochReport, EpochTransitionError>

Explicitly drops every immutable segment belonging to an old epoch.

impl Store

pub fn delete_matching( &self, predicate: &Predicate, ) -> Result<DeleteMatchingReport, DeleteMatchingError>

Deletes every live document whose current version matches predicate, atomically, and physically removes their bytes.

The whole call holds the maintenance, state, writer and WAL locks, so no other write lands between resolving the matches and deleting them. The order is: resolve the ids; durably record a purge intent for them; tombstone them all in one WAL record at one generation (readers see all of them or none of them); then run the physical purge, which rewrites every affected segment and the WAL. When this returns, no deleted byte remains in any store file. A crash before the intent is durable deletes nothing; after it, the next writable open completes the purge.

A cascade (ZE-225) extends the id set between resolution and delete_and_purge_locked, inside the same held locks.

impl Store

pub fn merge_sealed(&self) -> Result<u64, StoreError>

Merges small compatible sealed scan segments during host-selected idle time.

Each atomic batch admits at most 16 segments and 8 MiB of input files. Decoding and rebuilding require additional bounded working memory. Large segments and graph segments stay separate. Repeats while a batch fits; this synchronous call blocks writers and does not seal active writes. Open snapshot views defer input unlinking until later orphan cleanup. Returns the last publication generation, unchanged if no merge is due.

pub fn merge_sealed_with_cancel( &self, cancel: &CancelToken, ) -> Result<u64, StoreError>

Cancels between batches or before publication; completed batches remain.

impl Store

pub fn purge(&self, ids: &[DocId]) -> Result<PurgeToken, PurgeError>

Schedules a physical purge and returns before artifact rewriting begins.

pub fn await_physical_purge( &self, token: PurgeToken, ) -> Result<PurgeReport, PurgeError>

Resolves only after rewritten artifacts are committed and old paths are unlinked.

impl Store

pub fn drop_partition( &self, key_range: Range<i64>, ) -> Result<DropPartitionReport, StoreError>

Drops immutable segments wholly contained by the half-open timestamp range.

pub fn apply_retention( &self, policy: RetentionPolicy, now_ts: i64, ) -> Result<DropPartitionReport, StoreError>

Evaluates a retention policy now and explicitly invokes partition drop.

impl Store

pub fn seal(&self) -> Result<u64, StoreError>

Seals the current active segment into one appended immutable segment.

An empty active segment is an idempotent no-op that returns the current generation without publishing a manifest or segment.

pub fn seal_with_cancel(&self, cancel: &CancelToken) -> Result<u64, StoreError>

Seals explicitly unless caller cancellation wins before manifest commit.

Cancellation is checked before the empty-segment no-op.

impl Store

pub fn lexical_corpus_stats(&self) -> Result<CorpusStats, StoreLexicalError>

Returns exact live corpus statistics for store-backed lexical scoring.

Errors

Returns a store admission or segment error when the current lexical corpus cannot be read, or an index error when the corpus is empty.

pub fn ingest(&self, batch: IngestBatch) -> Result<IngestAck, IngestError>

Commits one active-segment upsert and returns its WAL/generation coordinates.

pub fn delete(&self, batch: DeleteBatch) -> Result<IngestAck, IngestError>

Durably tombstones documents across active and sealed state before acknowledging.

impl Store

pub fn close(&self) -> Result<(), StoreError>

Synchronously tears down this handle and releases writer ownership.

Concurrent callers wait for the one Open -> Closing -> Closed transition and observe the same completed close. Admitted reads may run through the configured bounded drain grace period. At that deadline their published snapshot is marked cancelled, and close waits for those cooperative reads to observe cancellation and release their Arc before it unmaps segments. Calling close after completion is successful and has no further effect.

impl Store

pub fn count_documents_grouped( &self, predicate: Option<&Predicate>, timestamp_range: Option<(i64, i64)>, column: ColumnId, limit: usize, ) -> Result<DocumentGroupCounts, QueryError>

Counts live documents matching an optional predicate and timestamp range, grouped by the value of column.

column must be a U64, I64, DictionaryString or RawString schema attribute. Documents where it is null are counted in DocumentGroupCounts::missing, not as a group. More than limit distinct values fail the whole call with StoreError::GroupLimitExceeded; no group is ever dropped.

impl Store

pub fn search_hybrid_with_text_deferred<'vector, E, R>( &self, prepare_vector: impl FnOnce() -> Result<SearchRequest<'vector>, E>, lexical: &TermQuery, query: &HybridQuery, options: impl Into<SearchOptions>, control: QueryControl, finish: impl FnOnce(&StoreHybridSearchOutcome, &QueryMaterializer<'_>) -> R, ) -> Result<(StoreHybridSearchOutcome, R), HybridPreparationError<E>>

Starts lexical retrieval before obtaining a caller-owned query vector. Both legs and returned text use one admission pinned before the producer runs. All submitted lexical work is joined on producer failure or panic.

The returned vector borrow must remain valid for the complete query. Producer errors retain their original type; core failures are separate.

Errors

Returns the producer’s error or a typed admission/search failure.

pub fn search_hybrid_with_text<R>( &self, vector: SearchRequest<'_>, lexical: &TermQuery, query: &HybridQuery, options: impl Into<SearchOptions>, control: QueryControl, finish: impl FnOnce(&StoreHybridSearchOutcome, &QueryMaterializer<'_>) -> R, ) -> Result<(StoreHybridSearchOutcome, R), FusionError>

Runs hybrid fusion and constructs caller-owned results before releasing its snapshot.

pub fn search_lexical_with_snippets( &self, query: &TermQuery, k: usize, window: NonZeroUsize, control: QueryControl, ) -> Result<(StoreLexicalSearchOutcome, Vec<OwnedLexicalSnippet>), StoreLexicalError>

Runs a flat-term lexical query and returns one snippet per candidate, in rank order, cut from the text pinned for the query’s generation.

Highlights are the tokens the store’s own analyzer produces from that text whose analyzed term is one of the query’s terms, which is exactly what the lexical leg scored.

Errors

Returns the search failure, or crate::ingest::StoreLexicalError::MissingSnippetMatch when a ranked row’s stored text contains none of the query’s terms.

pub fn search_lexical_filtered_with_snippets( &self, query: &TermQuery, k: usize, window: NonZeroUsize, control: QueryControl, filter: Option<&QueryFilter>, ) -> Result<(StoreLexicalSearchOutcome, Vec<OwnedLexicalSnippet>), StoreLexicalError>

Searches eligible lexical rows and materializes snippets at the same generation.

pub fn search_hybrid_with_snippets( &self, vector: SearchRequest<'_>, lexical: &TermQuery, query: &HybridQuery, options: impl Into<SearchOptions>, control: QueryControl, window: NonZeroUsize, ) -> Result<(StoreHybridSearchOutcome, Result<Vec<Option<OwnedLexicalSnippet>>, MaterializationError>), FusionError>

Runs hybrid fusion over a flat-term lexical leg and returns one optional snippet per fused hit, in rank order, cut from the text pinned for the query’s generation. A hit gets no snippet when its row has no stored text or the text contains none of the query’s terms.

Errors

Returns the search failure; the inner result carries a failure to read a ranked row’s text.

pub fn search_hybrid_structured_with_snippets( &self, vector: SearchRequest<'_>, lexical: &LexicalQuery, query: &HybridQuery, options: impl Into<SearchOptions>, control: QueryControl, window: NonZeroUsize, ) -> Result<(StoreHybridSearchOutcome, Result<Vec<Option<OwnedLexicalSnippet>>, MaterializationError>), FusionError>

Self::search_hybrid_with_snippets for a structured lexical leg. Highlights mark the terms of the leg’s reported expansions, so a prefix marks every indexed term it expanded to.

Errors

As Self::search_hybrid_with_snippets.

pub fn search_lexical_with_text<R>( &self, query: &TermQuery, k: usize, control: QueryControl, finish: impl FnOnce(&StoreLexicalSearchOutcome, &QueryMaterializer<'_>) -> R, ) -> Result<(StoreLexicalSearchOutcome, R), StoreLexicalError>

Runs a lexical query and constructs caller-owned results before releasing its snapshot.

pub fn search_with_text<R>( &self, request: SearchRequest<'_>, k: usize, options: impl Into<SearchOptions>, control: QueryControl, finish: impl FnOnce(&SearchOutcome, &QueryMaterializer<'_>) -> R, ) -> Result<(SearchOutcome, R), QueryError>

Runs a dense query and constructs owned caller results through rank-addressed text access.

impl Store

pub fn reindex_text(&self) -> Result<u64, StoreError>

Rebuilds every sealed text index from stored text under the current tokenizer. Active text is already indexed; seal it first. Publication replaces every sealed segment in one manifest commit, preserving all non-postings regions.

impl Store

pub fn prepare_segment<'a>( &self, segment: InMemorySegment<'a>, ) -> Result<PreparedSegment<'a>, StoreError>

Adopts already-built vector buffers and charges their exact capacities.

No ingest, graph construction, scheduling, or background work occurs at this seam. The returned value must be consumed by Self::seal_snapshot.

pub fn seal_snapshot( &self, segment: PreparedSegment<'_>, ) -> Result<u64, StoreError>

Writes, commits, read-only remaps, and publishes one complete snapshot.

The prepared anonymous vector buffers are consumed only after the new SegmentReader snapshot is live. The committed manifest contains the one complete segment supplied here; this is snapshot replacement, not task 10’s future append/ingest behavior.

impl Store

pub fn write_snapshot( &self, target: impl AsRef<Path>, ) -> Result<u64, StoreError>

Writes a consistent snapshot of this store into target and returns the generation it captured.

target must not exist, or must be an empty directory; its parent must exist; and it must not be the store directory or lie inside it. A rejected target is StoreError::SnapshotTarget and nothing is written. The handle must be writable (StoreError::ReadOnly otherwise), because only the writer owns the WAL tail. While a physical purge is pending the call is refused with StoreError::SnapshotPurgePending.

Writers are blocked while the generation is pinned and any graph tail is checkpointed. Graph-free pinning is O(manifest + unsealed records) and copies no document bytes. Writes, seal and maintenance run during the copy and are absent from the snapshot. Close cancels an in-flight snapshot (StoreError::ReadCancelled); a failed snapshot removes its staging directory. A parent-directory sync failure may return an error after publishing a complete target.

A graph snapshot first checkpoints the graph tail and may advance the manifest generation. Unabsorbed namespace document writes must be sealed before export, since their transaction authority belongs to the source.

The snapshot directory is an ordinary store: opening it read-only or read-write restores exactly the state at the returned generation.

impl Store

pub fn open_snapshot(&self) -> Result<Self, StoreError>

Opens an in-place read-only view of one complete generation.

Requires a writable source. Active data and sealed mappings are shared; no store files are created or copied. The view remains valid after the source closes, and must itself be closed to release its retention pin. Physical purge is busy while any view is open. Retired segment paths are retained until ordinary orphan cleanup on the next writable open.

impl Store

pub fn stats(&self) -> Result<Stats, StoreError>

Returns exact accounting and kernel counters for this open handle.

This operation never estimates. Engine-owned counters are maintained at allocation/mapping boundaries, mapped residency comes from mincore, and phys_footprint comes from Darwin TASK_VM_INFO.

impl Store

pub fn open_for_inspection(path: impl AsRef<Path>) -> Result<Self, StoreError>

Opens an existing diagnostics copy read-only using its persisted identity. Tokenizer compatibility is still validated; this never repairs or writes.

pub fn open( path: impl AsRef<Path>, options: OpenOptions, ) -> Result<Self, StoreError>

Opens a store directory with the requested access and durability policy.

pub fn open_migrations(&self) -> OpenMigrations

Returns the immutable report of changes completed by this open.

pub fn epoch_identity(&self) -> Option<EpochIdentity>

Returns the published embedding and tokenizer identity, or None for a store that carries no stamped epoch.

pub const fn schema(&self) -> &Schema

Returns the immutable schema declared for this store.

pub fn state(&self) -> Result<StoreState, StoreError>

Returns the current explicit lifecycle state.

pub fn snapshot(&self) -> Result<SnapshotLease, StoreError>

Acquires the complete immutable snapshot admitted for one read.

pub fn top_k_with_options( &self, request: ScanRequest<'_>, k: usize, options: ScanOptions, control: QueryControl, ) -> Result<ScanOutcome, QueryError>

Runs one exact parallel scan admitted against this store’s snapshot.

The query holds one snapshot lease for its complete execution and uses the store’s lazily started persistent worker pool.

pub fn search( &self, request: SearchRequest<'_>, k: usize, options: impl Into<SearchOptions>, control: QueryControl, ) -> Result<SearchOutcome, QueryError>

Searches the active segment plus every immutable segment in one pinned store generation, then merges one global top-k.

Scan-tier segments use the persistent query pool. Explicit graph-tier segments traverse serially on the calling thread, while the active segment is still scanned. Both tiers share one cancellation state and (RowSource, local_row) addressing, so immutable row zero never collides across segments and manifest reordering cannot rename a sealed row.

pub fn warm_lexical( &self, control: QueryControl, ) -> Result<(), StoreLexicalError>

Prepares the current lexical assembly and prefix vocabulary without ranking.

Call after open to move lazy assembly preparation out of the first query. Mutations can invalidate both caches. Cancellation may retain a complete assembly, but never publishes a partial vocabulary.

pub fn search_lexical( &self, query: &TermQuery, k: usize, control: QueryControl, ) -> Result<StoreLexicalSearchOutcome, StoreLexicalError>

Runs an exact structured lexical query over active and sealed text.

pub fn search_lexical_filtered( &self, query: &TermQuery, k: usize, control: QueryControl, filter: Option<&QueryFilter>, ) -> Result<StoreLexicalSearchOutcome, StoreLexicalError>

Runs lexical ranking with scan-compatible eligibility constraints.

pub fn stored_text( &self, version: DocumentVersion, ) -> Result<Option<String>, StoreLexicalError>

Returns the stored UTF-8 body for one exact document revision.

Active memory and immutable region 14 are searched without adding a second text format. None means either that the exact revision is not present or that its text field was absent.

pub fn get_documents( &self, ids: &[DocId], fields: DocumentFields, ) -> Result<Vec<Option<StoredDocument>>, StoreError>

Reads live documents by stable id from one pinned generation.

The result preserves request order and length. Unknown and tombstoned ids produce None; duplicate requested ids produce duplicate results.

pub fn scan_documents( &self, request: DocumentScanRequest<'_>, ) -> Result<DocumentScanPage, QueryError>

Enumerates one deterministic, bounded page of live documents.

The complete call is pinned to one generation. A continuation from a different generation is rejected with StoreError::ScanStale.

pub fn count_documents( &self, predicate: Option<&Predicate>, timestamp_range: Option<(i64, i64)>, ) -> Result<DocumentCount, QueryError>

Counts live documents matching an optional predicate and timestamp range.

pub fn search_lexical_structured( &self, query: &LexicalQuery, k: usize, snippet_bytes: usize, control: QueryControl, ) -> Result<StoreStructuredLexicalSearchOutcome, StoreLexicalError>

Runs a structured lexical query and returns provenance plus snippets copied from the exact row text pinned for this generation.

pub fn search_lexical_structured_filtered( &self, query: &LexicalQuery, k: usize, snippet_bytes: usize, control: QueryControl, filter: Option<&QueryFilter>, ) -> Result<StoreStructuredLexicalSearchOutcome, StoreLexicalError>

Runs structured lexical ranking with scan-compatible eligibility constraints.

pub fn search_hybrid( &self, vector_query: SearchRequest<'_>, lexical_query: &TermQuery, hybrid_query: &HybridQuery, options: impl Into<SearchOptions>, control: QueryControl, ) -> Result<StoreHybridSearchOutcome, FusionError>

Runs the store vector engine and exact lexical leg against one pinned generation, then delegates every blend decision to crate::fusion.

pub fn search_hybrid_structured( &self, vector_query: SearchRequest<'_>, lexical_query: &LexicalQuery, hybrid_query: &HybridQuery, options: impl Into<SearchOptions>, control: QueryControl, ) -> Result<StoreHybridSearchOutcome, FusionError>

Runs vector work with any structured lexical operator against the same pinned snapshot and generation.

impl Store

pub fn search_filtered( &self, request: SearchRequest<'_>, predicate: &Predicate, k: usize, options: impl Into<SearchOptions>, control: QueryControl, ) -> Result<FilteredSearchOutcome, FilteredSearchError>

Plans and executes one exact filtered vector query.

Predicate/schema failures are returned before active or sealed rows are scored. Published graph segments use a reported exact-scan fallback until task 19-M6 adds filter-aware traversal.

impl Store

pub fn maintain(&self, budget: MaintenanceBudget) -> MaintenanceReport

Runs due tier transitions within a host-supplied work budget.

Trait Implementations

impl Drop for Store

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.