lance-format / lance-format/lance

Refactor index cache to store data-only IndexData and rehydrate indices without IO

Open
#6,029 0 comments 1 reaction 1 assignee View on GitHub

@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
  1. Introduce internal IndexData structs per index type. They must be data-only (no readers, stores, schedulers).
  2. Cache IndexData in the existing index cache (new keys like ScalarIndexDataKey, VectorIndexDataKey).
  3. Replace caching of Arc<dyn Index> with cached IndexData and per-call rehydration.
  4. Keep sub-index partition/page caches, but ensure their entries are also data-only.
Enforcement

———

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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.