Add an optional Foyer-backed data-file cache

Cargo.toml

@@ -30,15 +30,19 @@ datafusion = { version = "54.0.0", default-features = false }
 arrow = { version = "58.0.0", features = ["prettyprint", "ffi"] }
 arrow-array = "58.0.0"
 arrow-schema = "58.0.0"
+async-trait = "0.1"
+bytes = "1"
 # Direct to name `chrono::TimeDelta` (the field type of lance's public
 # `AutoCleanupParams`) and `chrono::DateTime`/`Utc` (index metadata
 # timestamps); already in the graph transitively via lance.
 chrono = { version = "0.4", default-features = false }
 half = "2"
 tokio = { version = "1", features = ["rt-multi-thread", "sync"] }
 futures = "0.3"
+foyer = "=0.22.4"
 log = "0.4"
 libc = "0.2"
+object_store = "0.13.2"
 pin-project = "1.0"
 prost = "0.14"
 snafu = "0.9"

README.md

@@ -68,6 +68,7 @@ Based on the [liblance RFC](https://github.com/lance-format/lance/discussions/60
 | [x] | Async scan | Callback-based `lance_scanner_scan_async()` for non-blocking scans |
 | [x] | Dataset metadata | `lance_dataset_version()`, `lance_dataset_count_rows()`, `lance_dataset_latest_version()` |
 | [x] | Filter pushdown | `lance_scanner_set_substrait_filter()` accepts a serialized Substrait `ExtendedExpression`; `lance_scanner_additional_sql_filter()` adds SQL predicates with AND before scanning starts |
+| [x] | Data-file cache | Optional Foyer memory/disk cache for immutable `data/*.lance` reads |
 
 ## Building
 
@@ -197,6 +198,27 @@ auto ds = lance::Dataset::open_with_session(session, "data.lance");
 auto stats = session.cache_stats();
 ```
 
+To add a process-local memory/disk cache for remote Lance data-file reads,
+create the session with Foyer configuration. The cache is deliberately narrow:
+whole-object, single-range, and batched range reads of direct `data/*.lance`
+children are cached. Conditional and versioned reads, plus manifests, deletion
+files, and index files, keep using Lance's normal paths. Use one shared session
+for datasets that share the cache directory.
+
+```cpp
+lance::DataCacheOptions data_cache{
+    "/var/cache/my-service/lance",
+    512ULL * 1024 * 1024,       // memory tier
+    100ULL * 1024 * 1024 * 1024, // disk tier
+    1ULL * 1024 * 1024,         // range-cache block
+};
+lance::Session session(
+    6ULL * 1024 * 1024 * 1024,
+    1ULL * 1024 * 1024 * 1024,
+    data_cache);
+auto ds = lance::Dataset::open_with_session(session, "s3://bucket/data.lance");
+```
+
 ### Open at a specific version
 
 `lance_dataset_open` takes a `version` argument — `0` means the latest, any