Implementation:Lance format Lance IndexCaches

Knowledge Sources	Lance
Domains	Core, Caching, Indexing
Last Updated	2026-02-08 19:33 GMT

Overview

Description

The IndexCaches module provides a hierarchical caching system for Lance index data, mirroring the structure of the metadata cache system. The hierarchy prevents key collisions across datasets and indices:

GlobalIndexCache
  |
  +-- DSIndexCache (prefixed by dataset URI)
       |
       +-- Index-specific cache (prefixed by index UUID and optional FRI UUID)

The module defines:

• GlobalIndexCache -- Top-level cache wrapper around LanceCache. Implements Deref<Target=LanceCache>, Clone, and DeepSizeOf. Provides for_dataset(uri) to create dataset-scoped sub-caches.
• DSIndexCache -- Dataset-scoped cache. Provides for_index(uuid, fri_uuid) to create index-specific sub-caches with optional FRI (Fragment Reuse Index) UUID namespacing.
• Type-safe cache keys:
  • FragReuseIndexKey -- Caches FragReuseIndex objects, keyed by UUID
  • IndexMetadataKey -- Caches Vec<IndexMetadata>, keyed by version
  • ScalarIndexDetailsKey -- Caches ProstAny (protobuf Any wrapper) for scalar index details inferred from legacy manifests
• ProstAny -- A DeepSizeOf-implementing wrapper around Arc<prost_types::Any>

Usage

The index cache is part of a Lance Session and shared across all index operations. It is particularly important for scalar index details from legacy manifests that require expensive inference.

Code Reference

Source Location

rust/lance/src/session/index_caches.rs

Signature

pub struct GlobalIndexCache(pub(super) LanceCache);

impl GlobalIndexCache {
    pub fn for_dataset(&self, uri: &str) -> DSIndexCache;
}

pub struct DSIndexCache(pub(crate) LanceCache);

impl DSIndexCache {
    pub fn for_index(&self, uuid: &str, fri_uuid: Option<&Uuid>) -> LanceCache;
}

pub struct FragReuseIndexKey<'a> { pub uuid: &'a str }
pub struct IndexMetadataKey { pub version: u64 }
pub struct ScalarIndexDetailsKey<'a> { pub uuid: &'a str }

pub struct ProstAny(pub Arc<prost_types::Any>);

Import

use lance::session::index_caches::{
    GlobalIndexCache, DSIndexCache,
    FragReuseIndexKey, IndexMetadataKey, ScalarIndexDetailsKey, ProstAny,
};

I/O Contract

Inputs

Parameter	Type	Description
uri	&str	Dataset URI used as key prefix for namespace isolation
uuid	&str	Index UUID used as key prefix for index-level scoping
fri_uuid	Option<&Uuid>	Optional Fragment Reuse Index UUID for more specific cache keys
version	u64	Dataset version number for index metadata cache keys

Outputs

Type	Description
DSIndexCache	A dataset-scoped sub-cache for index data
LanceCache	An index-specific sub-cache with UUID prefix

Usage Examples

use lance::session::index_caches::{GlobalIndexCache, IndexMetadataKey};
use lance_core::cache::LanceCache;

// Create and scope an index cache
let global_cache = GlobalIndexCache(LanceCache::new(64 * 1024 * 1024));
let ds_cache = global_cache.for_dataset("s3://bucket/dataset.lance");
let idx_cache = ds_cache.for_index("abc-123-uuid", None);

// Retrieve cached index metadata
let key = IndexMetadataKey { version: 5 };
// ds_cache.get(&key) -> Option<Arc<Vec<IndexMetadata>>>

Related Pages

• Lance_format_Lance_SessionCaches -- Parallel caching hierarchy for dataset metadata
• Lance_format_Lance_IndexExtension -- Index extension traits that use these caches
• Lance_format_Lance_MemWalIndex -- MemWAL index that stores metadata in index entries