Trait StorageEngine

Source

pub trait StorageEngine:
    Send
    + Sync
    + 'static {
Show 18 methods    // Required methods
    fn get<'life0, 'life1, 'async_trait>(
        &'life0 self,
        ns: Namespace,
        key: &'life1 [u8],
    ) -> Pin<Box<dyn Future<Output = Result<Option<Vec<u8>>, LiteError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn put<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        ns: Namespace,
        key: &'life1 [u8],
        value: &'life2 [u8],
    ) -> Pin<Box<dyn Future<Output = Result<(), LiteError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait;
    fn delete<'life0, 'life1, 'async_trait>(
        &'life0 self,
        ns: Namespace,
        key: &'life1 [u8],
    ) -> Pin<Box<dyn Future<Output = Result<(), LiteError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn scan_prefix<'life0, 'life1, 'async_trait>(
        &'life0 self,
        ns: Namespace,
        prefix: &'life1 [u8],
    ) -> Pin<Box<dyn Future<Output = Result<Vec<KvPair>, LiteError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn batch_write<'life0, 'life1, 'async_trait>(
        &'life0 self,
        ops: &'life1 [WriteOp],
    ) -> Pin<Box<dyn Future<Output = Result<(), LiteError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn count<'life0, 'async_trait>(
        &'life0 self,
        ns: Namespace,
    ) -> Pin<Box<dyn Future<Output = Result<u64, LiteError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn scan_range<'life0, 'life1, 'async_trait>(
        &'life0 self,
        ns: Namespace,
        start: &'life1 [u8],
        limit: usize,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<KvPair>, LiteError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn scan_range_bounded<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        ns: Namespace,
        start: Option<&'life1 [u8]>,
        end: Option<&'life2 [u8]>,
        limit: Option<usize>,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<KvPair>, LiteError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait;

    // Provided methods
    fn scan_prefix_bounded<'life0, 'life1, 'async_trait>(
        &'life0 self,
        _ns: Namespace,
        _prefix: &'life1 [u8],
        limit: usize,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<KvPair>, LiteError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait { ... }
    fn scan_prefix_budgeted<'life0, 'life1, 'async_trait>(
        &'life0 self,
        _ns: Namespace,
        _prefix: &'life1 [u8],
        max_records: usize,
        _max_bytes: usize,
    ) -> Pin<Box<dyn Future<Output = Result<PrefixScan, LiteError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait { ... }
    fn scan_prefix_from_budgeted<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        _ns: Namespace,
        prefix: &'life1 [u8],
        after_key: Option<&'life2 [u8]>,
        max_records: usize,
        _max_bytes: usize,
    ) -> Pin<Box<dyn Future<Output = Result<PrefixScan, LiteError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait { ... }
    fn compact<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Result<CompactionOutcome, LiteError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait { ... }
    fn as_vector_segment_ext(&self) -> Option<&dyn VectorSegmentExt> { ... }
    fn as_array_segment_ext(&self) -> Option<&dyn ArraySegmentExt> { ... }
    fn as_fts_segment_ext(&self) -> Option<&dyn FtsSegmentExt> { ... }
    fn as_columnar_segment_ext(&self) -> Option<&dyn ColumnarSegmentExt> { ... }
    fn as_graph_segment_ext(&self) -> Option<&dyn GraphSegmentExt> { ... }
    fn as_spatial_segment_ext(&self) -> Option<&dyn SpatialSegmentExt> { ... }
}

Expand description

Async key-value blob storage backend.

Implementations must be Send + Sync + 'static to be shareable across async tasks and engine threads.

All operations are keyed by (Namespace, key). Values are opaque byte slices — the storage layer never interprets them.

Required Methods§

Source

fn get<'life0, 'life1, 'async_trait>( &'life0 self, ns: Namespace, key: &'life1 [u8], ) -> Pin<Box<dyn Future<Output = Result<Option<Vec<u8>>, LiteError>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Get a value by namespace and key.

Returns None if the key does not exist.

Source

fn put<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, ns: Namespace, key: &'life1 [u8], value: &'life2 [u8], ) -> Pin<Box<dyn Future<Output = Result<(), LiteError>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Put (insert or overwrite) a value.

Source

fn delete<'life0, 'life1, 'async_trait>( &'life0 self, ns: Namespace, key: &'life1 [u8], ) -> Pin<Box<dyn Future<Output = Result<(), LiteError>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Delete a key. No-op if the key does not exist.

Source

fn scan_prefix<'life0, 'life1, 'async_trait>( &'life0 self, ns: Namespace, prefix: &'life1 [u8], ) -> Pin<Box<dyn Future<Output = Result<Vec<KvPair>, LiteError>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Scan all keys with a given prefix in a namespace.

Returns (key, value) pairs ordered by key. The prefix match is bytewise: key.starts_with(prefix).

If prefix is empty, returns all entries in the namespace.

Source

fn batch_write<'life0, 'life1, 'async_trait>( &'life0 self, ops: &'life1 [WriteOp], ) -> Pin<Box<dyn Future<Output = Result<(), LiteError>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Atomically apply a batch of writes.

All operations in the batch succeed or fail together (transaction). This is the primary write path for engines that need to persist multiple related blobs atomically (e.g., HNSW node + metadata).

Source

fn count<'life0, 'async_trait>( &'life0 self, ns: Namespace, ) -> Pin<Box<dyn Future<Output = Result<u64, LiteError>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

Count the number of entries in a namespace.

Useful for cold-start progress reporting and memory governor decisions.

Source

fn scan_range<'life0, 'life1, 'async_trait>( &'life0 self, ns: Namespace, start: &'life1 [u8], limit: usize, ) -> Pin<Box<dyn Future<Output = Result<Vec<KvPair>, LiteError>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Range scan: return up to limit entries where key >= start.

Results are ordered by key (lexicographic byte order).

Source

fn scan_range_bounded<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, ns: Namespace, start: Option<&'life1 [u8]>, end: Option<&'life2 [u8]>, limit: Option<usize>, ) -> Pin<Box<dyn Future<Output = Result<Vec<KvPair>, LiteError>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Bounded range scan: return entries where start <= key < end.

start = None means the beginning of the namespace.
end = None means the end of the namespace.
limit = None means no cap.

Results are ordered by key (lexicographic byte order).

Provided Methods§

Source

fn scan_prefix_bounded<'life0, 'life1, 'async_trait>( &'life0 self, _ns: Namespace, _prefix: &'life1 [u8], limit: usize, ) -> Pin<Box<dyn Future<Output = Result<Vec<KvPair>, LiteError>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Read at most limit prefix records, ordered by key.

Implementations stop inside storage before materializing additional records. Zero returns no records. Positive limits require backend support.

Source

fn scan_prefix_budgeted<'life0, 'life1, 'async_trait>( &'life0 self, _ns: Namespace, _prefix: &'life1 [u8], max_records: usize, _max_bytes: usize, ) -> Pin<Box<dyn Future<Output = Result<PrefixScan, LiteError>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Read prefix records within count and serialized key-plus-value budgets.

Limits report remaining records without returning oversized values. Budgets exclude allocation overhead and cached pages.

Source

fn scan_prefix_from_budgeted<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, _ns: Namespace, prefix: &'life1 [u8], after_key: Option<&'life2 [u8]>, max_records: usize, _max_bytes: usize, ) -> Pin<Box<dyn Future<Output = Result<PrefixScan, LiteError>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Read prefix rows after an exclusive, namespace-free cursor within both budgets.

The cursor must match prefix. Rows remain strictly increasing and prefix-confined. Resume from the last retained key. Continuation never advances past an excluded row. Empty byte-limited batches return an error when max_records is positive. Zero records returns an empty batch and ignores the cursor. Budgets count serialized keys plus values.

Source

fn compact<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<CompactionOutcome, LiteError>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

Compact the backing store, reclaiming dead pages and (when possible) truncating the file to bound on-disk growth.

The default implementation is a no-op returning a zero CompactionOutcome, so engines with nothing to compact (in-memory stores, test doubles) need not override it. The pagedb-backed engine overrides this to drain the deferred-free list, truncate main.db, AND delete tombstoned segment files.

Reclaiming tombstones belongs here because compaction is the only “reclaim disk” operation callers know to run, and tombstones are by far the largest reclaimable thing: a segment replacement retires its predecessor and nothing else ever deletes it.

Source

fn as_vector_segment_ext(&self) -> Option<&dyn VectorSegmentExt>

Return this engine’s vector segment operations interface if supported.

PagedbStorage returns Some(self). Test doubles return None, falling back to the legacy blob checkpoint path.

Only available on non-WASM targets (mmap is required).

Source