perf(exec): cache datasets opened from serialized protos in resolve_dataset

[jmhsieh]

Problem

A distributed FilteredReadExec / ANN plan is serialized to proto and executed on remote workers. The serialized proto cannot carry a live Arc<Dataset>, so when a worker deserializes it, resolve_dataset() is called with dataset = None and falls through to open_dataset_from_table_identifier() → DatasetBuilder::from_uri(..).load() — a full cold open (ObjectStore init + manifest GET + Dataset construction), emitting one dataset_events event="loading" per plan.

There is no caching at this layer, so every distributed plan re-opens the dataset from scratch. On a many-fragment table that is thousands of redundant opens. In one production distributed backfill resume, a ~4,800-fragment table was cold-opened ~4,800 times (4,813 loading events), producing a ~3-hour planning wall in front of ~5 minutes of actual work — planning was ~36× longer than the work it gated, entirely from re-opens that carry no new information (the version is pinned and immutable).

Both the filtered-read path (io/exec/filtered_read_proto.rs) and the ANN paths (io/exec/ann_proto.rs) route through the same resolve_dataset, so both are affected.

Fix

Add a process-global, bounded moka cache in resolve_dataset, keyed by the immutable snapshot identity (uri, version, manifest_etag). Concurrent first-misses are coalesced into a single open via moka's single-flight try_get_with, so a wave of N plans collapses to one open per (uri, version, etag) per worker process.

A single change covers both the filtered-read and ANN paths since they share resolve_dataset.

Why this is safe

A pinned dataset version is an immutable snapshot, so reusing a cached Arc<Dataset> is always correct:

• Version pinning / time-travel — the version is part of the key, so a read pinned to version V only ever sees the dataset opened at V.
• Post-write invalidation — a write produces a new version (and a new manifest etag), i.e. a new key, rather than mutating an existing entry. The cache never serves stale data.
• Storage options are intentionally excluded from the key. Credentials may be re-vended per plan, but the bytes identified by the etag are the same; a cached entry reuses the ObjectStore configured at first open. time_to_idle (5 min) bounds how long those first-open credentials are retained before an idle entry is dropped and re-opened.

Configuration

• LANCE_PROTO_DATASET_CACHE_SIZE — max distinct (uri, version, etag) datasets cached per process (default 64). Set to 0 to disable caching entirely and restore the previous cold-open-per-plan behavior.
• An info! log is emitted at the open (cache-miss) site so a heavy distributed plan is greppable without enabling lance::events tracing.

Tests

• test_resolve_dataset_cached_returns_same_arc — a cache hit returns the same Arc, not a re-open.
• test_resolve_dataset_cached_single_flight — 16 concurrent first-misses collapse to exactly one cached entry.
• test_resolve_dataset_cached_distinct_versions — different versions never alias (version pinning preserved).
• test_resolve_dataset_some_returns_passed_arc — the Some arm still passes the supplied handle through unchanged.
• test_resolve_dataset_opens_once_across_plan_runs — deterministic, non-cloud repro: instruments the cache-miss opener (one opener call == one DatasetBuilder::load() == one manifest read) and asserts 50 sequential plans open the dataset once with the cache (and once under concurrency) vs 50 times without it.

Run with: cargo test -p lance --lib --features substrait io::exec::table_identifier

[github-actions]

ACTION NEEDED
Lance follows the Conventional Commits specification for release automation.

The PR title and description are used as the merge commit message. Please update your PR title and description to match the specification.

For details on the error please inspect the "PR Title Check" action.

[codecov]

Codecov Report

❌ Patch coverage is 89.57055% with 17 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
rust/lance/src/io/exec/table_identifier.rs	89.57%	16 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!