Module cache 

Lance cache system.

For cache users

Use LanceCache (or WeakLanceCache) to store and retrieve typed values. Define a CacheKey (or UnsizedCacheKey for trait objects) to describe what you’re caching and its type.

To make a value type serializable (so persistent backends can store it), implement CacheCodecImpl on the type, then override CacheKey::codec:

impl CacheCodecImpl for MyData {
    fn serialize(&self, w: &mut dyn Write) -> Result<()> { /* ... */ }
    fn deserialize(data: &Bytes) -> Result<Self> { /* ... */ }
}

impl CacheKey for MyDataKey {
    type ValueType = MyData;
    fn key(&self) -> Cow<'_, str> { /* ... */ }
    fn type_name() -> &'static str { "MyData" }
    fn codec() -> Option<CacheCodec> {
        Some(CacheCodec::from_impl::<MyData>())
    }
}

For backend implementors

Implement CacheBackend to provide a custom storage layer (disk, Redis, etc.). Backends receive InternalCacheKey keys and type-erased CacheEntry values — the typed wrapping is handled by LanceCache. See the backend module for details.

Serialization flow

When a CacheKey provides a codec via CacheKey::codec:

1. LanceCache wraps the CacheCodec and passes it to the backend alongside the entry on insert and get calls.
2. In-memory backends (like MokaCacheBackend) ignore the codec.
3. Persistent backends use codec.serialize(entry, writer) on insert and codec.deserialize(reader) on get to persist entries across restarts.

Modules

backend

Backend interface for cache implementors.

codec

Serialization codecs for cache entries.

Structs

CacheCodec

Type-erased codec for serializing and deserializing cache entries.

CacheEntryReader

Reads a cache entry body, tracking an offset into the input and exposing the entry’s type_version so implementors can branch for backward compat.

CacheEntryWriter

Writes a cache entry body: a header followed by sections, streaming directly to the underlying writer.

CacheStats

Context

InternalCacheKey

Structured cache key passed to CacheBackend methods.

LanceCache

Typed cache wrapper that handles key construction and type safety.

MokaCacheBackend

Default CacheBackend backed by a moka cache.

WeakLanceCache

A weak reference to a LanceCache, used by indices to avoid circular references. When the original cache is dropped, operations on this will gracefully no-op.

Enums

CacheDecode

Outcome of deserializing a cache entry.

CacheMissReason

Why a cache entry could not be decoded into the expected type.

Constants

MAGIC

Magic bytes that prefix every stabilized cache entry.

Traits

CacheBackend

Low-level pluggable cache backend.

CacheCodecImpl

Serialization trait for cache entries.

CacheKey

Typed cache key for sized value types.

DeepSizeOf

UnsizedCacheKey

Like CacheKey but for unsized value types (e.g. dyn Trait).

Functions

has_cache_envelope

Returns true if data begins with the cache-entry MAGIC.

Type Aliases

CacheEntry

A type-erased cache entry.

CacheKeyIterator

Iterator over cache keys currently known to a backend.

Derive Macros

DeepSizeOf

Derive macro for the DeepSizeOf trait.