lance-format / lance-format/lance
Refactor index cache to store data-only IndexData and rehydrate indices without IO
Open
@wjones127 is already working on this.
Since Mar 10, 2026.
A-index
chore
- Dominant language
- Rust
- Stars
- 7.1k
- Forks
- 852
- Avg merge
- 3d 18h
- Merged PRs (30d)
- 272
Description
Problem
The index cache currently stores full index structs that hold object store readers/connections. This is risky in multitenant scenarios and when credentials expire. It also makes cache sizing unreliable because cached entries share Arc state outside the cache.
Goal
Change the index cache to store data-only IndexData and rehydrate index instances using fresh object store connections. Rehydration must use minimal CPU and no IO.
Approach
- Introduce internal IndexData structs per index type. They must be data-only (no readers, stores, schedulers).
- Cache IndexData in the existing index cache (new keys like ScalarIndexDataKey, VectorIndexDataKey).
- Replace caching of
Arc<dyn Index>with cached IndexData and per-call rehydration. - Keep sub-index partition/page caches, but ensure their entries are also data-only.
Enforcement
- Create tests that assert rehydration performs zero object store IO. Use
io_stats()for this. - Create tests that assert memory size checks are exactly correct: https://github.com/lance-format/lance/pull/5152/changes#diff-664229ef83b65cc75050853551318f025542f7a2f03884c468b1f3f43e4cc37d
———
Example: BTree
Index Cache (data-only) Partition/Page Cache (data-only)
┌────────────────────────┐ ┌──────────────────────────────┐
│ BTreeIndexData │ │ BTreePageKey -> FlatIndex │
│ - page_lookup │ │ (page content only) │
│ - ranges_to_files │ └──────────────────────────────┘
│ - data_type, batch_size│
└────────────────────────┘
│
│ from_data (no IO)
▼
┌────────────────────────┐
│ BTreeIndex (runtime) │
│ - store (fresh) │
│ - index_cache (weak) │
│ - lazy readers │
└────────────────────────┘
│
│ on page request (IO)
▼
read page -> build FlatIndex -> cache FlatIndex data only
Example: IVF_PQ
Index Cache (data-only) Partition Cache (data-only)
┌────────────────────────┐ ┌────────────────────────────────────┐
│ IvfIndexData │ │ IVFPartitionKey -> PartitionEntry │
│ - ivf_model │ │ - subindex data (e.g. Flat/HNSW) │
│ - sub_index_metadata │ │ - partition storage data │
│ - distance_type │ └────────────────────────────────────┘
│ - pq codebook/metadata │
└────────────────────────┘
│
│ from_data (no IO)
▼
┌────────────────────────┐
│ IVFIndex (runtime) │
│ - lazy index reader │
│ - lazy storage reader │
│ - index_cache (weak) │
└────────────────────────┘
│
│ on partition load (IO)
▼
read partition -> build subindex -> cache PartitionEntry data only
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.