Struct Store 

pub struct Store { /* private fields */ }

The durable storage engine for one data directory.

Implementations

impl Store

pub fn open(dir: &Path) -> Result<Self>

Open (creating if absent) the store at dir with encryption-at-rest disabled (the plaintext codec). Runs full crash recovery.

pub fn open_with_codec(dir: &Path, codec: Box<dyn PageCodec>) -> Result<Self>

Open the store sealing every byte — catalog and all collections — with a single PageCodec. Used by quiver-crypto to enable encryption-at-rest under one root key (no per-collection envelope). Runs full crash recovery.

pub fn open_with_keyring(dir: &Path, keyring: Box<dyn KeyRing>) -> Result<Self>

Open the store with a KeyRing supplying a catalog codec (manifest and WAL) and a per-collection codec (segments and index artifacts). This is the seam quiver-crypto’s envelope key-ring uses to seal each collection under its own data-encryption key, enabling crypto-shredding. Runs full crash recovery.

pub fn set_commit_observer(&mut self, observer: CommitObserver)

Install a hook invoked with each committed WalEntry, in commit order (ADR-0030). Used by the server to drive a leader’s replication stream; replaces any previous observer.

pub fn replication_snapshot(&self) -> Result<Vec<WalOp>>

The operations that recreate the store’s current logical state, for a replication follower to bootstrap from (ADR-0030): a CreateCollection per collection, each followed by an Upsert per live point. Collections are emitted before their points so a follower can apply the stream in order.

pub fn apply_replicated(&mut self, op: WalOp) -> Result<()>

Apply a replicated operation received from a leader (ADR-0030). The op is persisted to this node’s WAL under a locally-assigned LSN — preserving the leader’s collection id so later ops resolve — then applied to in-memory state through the same path crash recovery uses. Checkpoint ops are a per-node concern and are ignored; followers checkpoint themselves.

pub fn create_collection( &mut self, name: &str, descriptor: Descriptor, ) -> Result<CollectionId>

Create a collection. Fails if the name is already taken.

pub fn drop_collection(&mut self, name: &str) -> Result<bool>

Drop a collection and all of its data. Its segment files are reclaimed at the next checkpoint or the next open. Returns whether it existed.

pub fn shred_collection(&mut self, name: &str) -> Result<bool>

Crypto-shred a collection: drop it, checkpoint so the manifest no longer references it and its files are reclaimed, then destroy its key material. After this its sealed segments and index are unrecoverable even to the master-key holder (ADR-0010); with a single-codec key-ring there is no per-collection key, so this is drop plus a checkpoint. Returns whether the collection existed.

pub fn upsert( &mut self, collection: CollectionId, external_id: &str, vector: &[f32], payload: &[u8], ) -> Result<Lsn>

Insert or replace a point. The vector length must equal the collection’s dimensionality; the payload is stored opaquely. Returns the assigned LSN once the write is durable.

pub fn upsert_batch( &mut self, collection: CollectionId, records: &[(&str, &[f32], &[u8])], ) -> Result<u64>

Upsert a batch of points with a single fdatasync instead of one per point. All records are acknowledged atomically — if the server crashes before the sync completes, none of the batch is durable (the caller, seeing no response, should retry the whole batch). This is the standard batch-commit pattern used by every production database.

records is (external_id, vector, payload_bytes) slices; the vectors must match the collection’s dimensionality or the call returns an error before writing anything.

pub fn delete( &mut self, collection: CollectionId, external_id: &str, ) -> Result<bool>

Delete a point by external id. Returns whether it existed.

pub fn prepare_create_collection( &self, name: &str, descriptor: &Descriptor, ) -> Result<WalOp>

Build the validated WalOp that Store::create_collection would log, without applying it. The per-shard Raft write path (ADR-0067) proposes this op through consensus so a quorum commits it before any member applies it (via Store::apply_replicated). The new collection’s id is assigned here, on the leader, and carried in the op exactly as a direct create would — so every member applies the same id; the caller serializes concurrent creates so two cannot claim the same next_collection_id.

pub fn prepare_upsert( &self, collection: CollectionId, external_id: &str, vector: &[f32], payload: &[u8], ) -> Result<WalOp>

Build the validated WalOp::Upsert that Store::upsert would log, without applying it (the Raft write path; see Store::prepare_create_collection). The vector is encoded identically to the direct path, so a member applying the proposed op reaches the same state a direct upsert would.

pub fn prepare_delete( &self, collection: CollectionId, external_id: &str, ) -> Result<Option<WalOp>>

Build the WalOp::Delete that Store::delete would log, or None if the point does not exist, without applying it (the Raft write path).

pub fn get( &self, collection: CollectionId, external_id: &str, ) -> Result<Option<Record>>

Fetch a point by external id.

pub fn scan(&self, collection: CollectionId) -> Result<Vec<(String, Record)>>

Iterate every live (external_id, record) in a collection, in id order. Used to build the in-memory index and for brute-force scans.

pub fn collection_id(&self, name: &str) -> Option<CollectionId>

The id of a collection by name, if it exists.

pub fn descriptor(&self, collection: CollectionId) -> Option<&Descriptor>

The descriptor of a collection, if it exists.

pub fn collection_codec_clone( &self, collection: CollectionId, ) -> Result<Box<dyn PageCodec>>

A clone of a collection’s page codec, for a component that seals its own files with that collection’s key — e.g. a disk-resident index artifact (ADR-0019). The same owned handle can both write and mmap-open the artifact, so it shares the collection’s data-encryption key.

Errors

CoreError::NotFound if the collection is unknown.

pub fn dir(&self) -> &Path

The store’s root data directory.

pub fn manifest_version(&self) -> u64

The current manifest version — the catalog generation a snapshot of this store captures (ADR-0050).

pub fn index_dir(&self, collection: CollectionId) -> PathBuf

The directory that holds a collection’s index artifacts (<data_dir>/collections/<id>/index). Not created by this call.

pub fn read_index_snapshot( &self, collection: CollectionId, ) -> Result<Option<Vec<u8>>>

Read and decrypt the current durable index snapshot for a collection, if one is referenced by the manifest (ADR-0025). Returns the opaque blob the index layer wrote at the last checkpoint, or None if the index must be rebuilt (no snapshot, or a store written before v2).

Errors

CoreError::NotFound if the collection is unknown, or an I/O / decrypt / page-integrity error reading the snapshot file.

pub fn recovery_tail(&self, collection: CollectionId) -> Result<RecoveryTail>

The post-checkpoint mutations a restored index snapshot must replay to catch up to the current state (ADR-0025): the active-buffer upserts and the external ids whose checkpointed row died this window. Both are bounded by the checkpoint cadence, not the collection size.

Errors

CoreError::NotFound if the collection is unknown.

pub fn len(&self, collection: CollectionId) -> Result<usize>

The number of live rows in a collection.

pub fn is_empty(&self, collection: CollectionId) -> Result<bool>

Whether a collection has no live rows.

pub fn collection_names(&self) -> Vec<String>

Names of all collections, sorted.

pub fn matching_ids( &self, collection: CollectionId, predicate: &SecPredicate, ) -> Result<Vec<String>>

The live external ids whose payload satisfies an indexable predicate, resolved through the sealed segments’ secondary indexes (.sec) plus a scan of the active buffer. The result is sorted and de-duplicated. This is the pre-filter primitive the query planner builds hybrid search on.

Errors

CoreError::NotFound if the collection is unknown, or CoreError::InvalidArgument if the predicate’s field is not declared filterable in the collection schema.

pub fn checkpoint(&mut self) -> Result<()>

Seal everything changed since the last checkpoint into new immutable segments, install a new manifest atomically, rotate the WAL, and reclaim superseded files. A no-op if nothing has changed since the last checkpoint. Crash-safe at every step (see the module docs).

Equivalent to Store::checkpoint_with_index_snapshots with no index snapshots (any existing snapshot references are cleared).

pub fn checkpoint_with_index_snapshots( &mut self, index_snapshots: &HashMap<CollectionId, Vec<u8>>, ) -> Result<()>

Like Store::checkpoint, but also durably captures the supplied per-collection index snapshots (ADR-0025): each opaque blob is sealed with its collection’s codec, fsync’d, and referenced by the same atomic manifest swap that publishes the segments — so the (segments, index) pair is consistent at one LSN. The map is the complete set for this checkpoint; a collection absent from it has any existing snapshot cleared, so a referenced snapshot’s LSN always equals the new checkpoint’s LSN.

pub fn compact(&mut self) -> Result<()>

Compact every collection with reclaimable space: merge its sealed segments, dropping dead (deleted or shadowed) rows, into a single fresh segment. Each collection commits via its own atomic manifest swap and is crash-safe like a checkpoint — the old segments stay valid until the swap, so a crash before it leaves the pre-compaction state intact.