This is an automated email from the ASF dual-hosted git repository.

Gabriel39 pushed a commit to branch branch-4.2
in repository https://gitbox.apache.org/repos/asf/doris.git


The following commit(s) were added to refs/heads/branch-4.2 by this push:
     new 07fc08ab9ec [improvement](file-cache) adapt external cache reads to 
I/O latency (branch-4.2) (#69768)
07fc08ab9ec is described below

commit 07fc08ab9ec6cf5e1d125f25a84b81bc819b314f
Author: Gabriel <[email protected]>
AuthorDate: Fri Nov 20 09:25:04 2026 +0800

    [improvement](file-cache) adapt external cache reads to I/O latency 
(branch-4.2) (#69768)
    
    ### What problem does this PR solve?
    
    Warm external-table scans can stall on a congested file-cache disk even
    when object storage serves the same immutable range faster. This adds
    adaptive cache reads to `branch-4.2`.
    
    Related PR: #69779 (master).
    
    ### Implementation
    
    - Each `BlockFileCache` owns an independent controller shared by queries
    using that cache path. Compare actual local and remote service times in
    eight request-size buckets, with 50 real samples per source and bucket.
    Keep the 5 ms local preference and configurable skip factor; do not
    extrapolate small reads to full cache blocks.
    - Forward session variable `enable_file_cache_io_adaptor` (default
    `true`). Keep `file_cache_io_adaptor_skip_read_factor=1.0` as the sole
    BE tuning setting. Optional Thrift field **1007** is used consistently
    for this option, after checking all active release branches and master;
    an omitted field preserves old-FE behavior.
    - Keep HDFS on its established cache path. Apply adaptation to other
    complete downloaded disk-cache hits before synchronous/asynchronous
    write-mode dispatch. Preserve cached blocks and avoid duplicate
    writeback. Keep mixed misses, inflight memory, background/index/warmup
    and internal-table behavior.
    - After a remote error or short read, overwrite the complete range from
    local cache and disable optional remote reads for that reader's
    lifetime. Required misses still read remote storage; other readers
    retain independent eligibility. Cancellation propagates without
    disabling future adaptation.
    - Preserve asynchronous LRU recency on the full-hit path: collect
    eligible touches under the cache mutex and enqueue after unlocking. The
    capacity test warms A/B, repeatedly reads A through both write modes,
    inserts C and verifies that cold B is evicted.
    
    ### Adaptive sampling and recovery
    
    - Bucket limits are 4 KiB, 16 KiB, 64 KiB, 256 KiB, 1 MiB, 4 MiB and 16
    MiB, plus a final bucket for larger reads. A 4 KiB local read taking 100
    us remains a 100 us sample.
    - Sample each successful complete remote call at its actual size and
    latency, including ordinary misses. Cache writeback and other remote
    calls do not enter that sample. Peer reads and ineligible
    query/background paths do not train the controller.
    - Admit probes only after the request-size bucket has 50 local samples
    with average latency at least 5 ms. Below that floor, keep healthy cache
    hits local and skip those buckets during probe rotation so they do not
    reserve another bucket's turn.
    - Route occasional real requests through the unselected source for
    eligible buckets, including cold remote histories and local recovery
    with no previous fast local sample. There are no background or duplicate
    reads and no synthetic samples.
    - Probe admission is limited across all buckets of each cache path: at
    most one in-flight probe, at least one second between probe starts, and
    at least 64 eligible full-hit decisions between probes. All success,
    failure, short-read and cancellation exits release the permit. Recovery
    replaces the existing measured window through subsequent real
    observations.
    
    - Rotate probe opportunities among request-size buckets, retaining quota
    for the selected bucket. Learn the longest observed request gap while
    that bucket waits for a probe, so sparse or bursty traffic is not
    expired just before it returns. Reset that horizon after admission and
    expire buckets that remain absent beyond it. The shared time,
    request-count and in-flight limits remain unchanged.
    
    ### Observability
    
    All 12 counters participate in statistics merge, delta reporting and
    Profile aggregation:
    
    | Profile counters | Meaning |
    | --- | --- |
    | `IOAdaptorLookupCount`, `IOAdaptorLookupTime` | Full-coverage lookup
    attempts and cost |
    | `IOAdaptorLocalReadCount`, `IOAdaptorLocalReadTime` | Local attempts
    and service time, including fallback |
    | `IOAdaptorBypassCount`, `IOAdaptorBypassBytes` | Requested remote
    bypasses and bytes |
    | `IOAdaptorRemoteReadBytes`, `IOAdaptorRemoteReadTime` | Returned
    bypass bytes and remote cost |
    | `IOAdaptorLocalProbeCount`, `IOAdaptorRemoteProbeCount` | Real
    requests routed through the unselected local/remote source |
    | `IOAdaptorRemoteFailureCount`, `IOAdaptorFallbackLocalCount` |
    Failed/short bypasses and local fallbacks |
    
    Requested and returned remote bytes are tracked separately so short
    reads remain measurable.
    
    ### Review and CI fixes
    
    - Rebase onto the target branch while preserving its cache-loading API,
    asynchronous LRU behavior and write-mode dispatch.
    - Exclude HDFS from optional remote reads: HDFS read errors destroy the
    backing handle, so a successful local fallback could otherwise leave
    later ranges unusable. Repeated HDFS cache-hit tests verify the handle
    and size remain intact.
    - Account completed adaptor local hits in the six established per-disk
    read/hit counters and byte totals. Both write modes, remote bypasses,
    incomplete lookups and failed local-copy retries are covered without
    duplicate accounting.
    - Check full inflight memory coverage before acquiring disk-cache
    metadata locks, and let the existing memory-first planners own
    materialization and counters, including read-only queries with zero
    write budget after async writes are disabled.
    - Pin join order in `adjust_virtual_slot_nullable` so asynchronous
    statistics cannot commute the join and change its recorded shape.
    Preserve its result and virtual-slot nullability assertions.
    - Keep cache routing in focused helpers without changing cancellation,
    required-miss, repair or fallback order.
    
    ### Review follow-up
    
    - Isolate healthy and congested cache paths; remove the BE-wide
    singleton and remembered-minimum feedback.
    - Cover mixed read sizes, per-call remote sampling, remote-history
    bootstrap, recovery without a fast local history, probe rate/concurrency
    limits, and permit cleanup on failures, short reads and cancellation.
    - Preserve complete-range fallback, HDFS exclusion, per-reader
    optional-remote failure isolation, cache hit accounting, inflight reads
    and existing cache write policies.
    - Remove a legacy unmatched `NOLINTEND` from the type header so static
    checks can complete.
    - Bring master's complete-inflight lookup into the branch-4.2
    remote-only-on-miss planner. Accepted buffers remain readable after
    disabling async writes; partial memory coverage still reads the complete
    range remotely without cache writeback.
    
    ### Current validation
    
    - **63 focused BE test results passed under ASan**, including the two
    explicitly enabled latency-controlled benchmarks. The full suite was
    followed by a final rerun of the three probe-cleanup tests after
    updating their admission assertions; all latest results pass.
    - All **three new fast-local regression tests failed before the fix on
    both branches**. They cover 1,024 reads at 32 requests/s, fast buckets
    competing with a slow bucket across eight probe intervals, and the exact
    5 ms admission boundary.
    - The fast-local benchmark now requires zero remote reads, bypasses and
    probes during every steady-state phase. Failure, short-read and
    cancellation tests use a local-preferred history above the probe floor
    and verify both quota consumption and permit release.
    - Existing mixed-size and sparse/bursty recovery tests continue to pass.
    Once the local window drops below 5 ms, ordinary local reads complete
    recovery without further remote probes.
    - clang-format **16** passed on all **19** affected C++ source/header
    files. Changed-code clang-tidy passed for the production and test
    changes.
    - This update changes no FE code, setting or wire field; FE/session/wire
    validation remains the earlier validation.
    - Full TeamCity validation is pending on this revision; local focused
    tests do not replace those runs.
    
    ### Release note
    
    External-table scans can adaptively bypass slower disk-cache reads.
    Session variable `enable_file_cache_io_adaptor` controls this behavior
    and defaults to `true`.
    
    ### Check List (For Author)
    
    - Test: Unit tests and verification described above.
    - Behavior changed: Yes; eligible external cache hits may read remote
    storage.
    - Does this need documentation: Yes; session setting and Profile
    counters.
    
    ### Check List (For Reviewer who merge this PR)
    
    - [ ] Confirm the release note
    - [ ] Confirm test cases
    - [ ] Confirm document
    - [ ] Add branch pick label
---
 be/src/common/config.cpp                           |   5 +
 be/src/common/config.h                             |   2 +
 be/src/core/types.h                                |   1 -
 be/src/exec/scan/file_scan_io_context.h            |   4 +
 be/src/io/cache/block_file_cache.cpp               |  20 +-
 be/src/io/cache/block_file_cache.h                 |   8 +
 be/src/io/cache/block_file_cache_profile.cpp       |  48 ++
 be/src/io/cache/block_file_cache_profile.h         |  12 +
 be/src/io/cache/cached_remote_file_reader.cpp      | 350 +++++++--
 be/src/io/cache/cached_remote_file_reader.h        |  27 +-
 be/src/io/cache/file_block.cpp                     |   1 +
 be/src/io/cache/file_cache_common.h                |  12 +
 be/src/io/cache/file_cache_io_adaptor.cpp          | 140 ++++
 be/src/io/cache/file_cache_io_adaptor.h            |  82 ++
 be/src/io/io_common.h                              |  26 +
 be/test/exec/scan/file_scanner_v2_test.cpp         |  26 +
 .../block_file_cache_profile_reporter_test.cpp     |  48 ++
 .../io/cache/cached_remote_file_reader_test.cpp    | 871 ++++++++++++++++++++-
 be/test/io/cache/file_cache_io_adaptor_test.cpp    | 435 ++++++++++
 .../java/org/apache/doris/qe/SessionVariable.java  |   7 +
 .../qe/SessionVariableFileCacheIoAdaptorTest.java  |  85 ++
 gensrc/thrift/PaloInternalService.thrift           |   3 +
 .../adjust_virtual_slot_nullable.groovy            |   4 +-
 23 files changed, 2152 insertions(+), 65 deletions(-)

diff --git a/be/src/common/config.cpp b/be/src/common/config.cpp
index c7a7f7f43ff..917cbfafa3a 100644
--- a/be/src/common/config.cpp
+++ b/be/src/common/config.cpp
@@ -1348,6 +1348,11 @@ DEFINE_mBool(file_cache_enable_only_warm_up_idx, 
"false");
 DEFINE_Int32(file_cache_downloader_thread_num_min, "32");
 DEFINE_Int32(file_cache_downloader_thread_num_max, "32");
 
+// Larger values favor remote reads when a query enables the file-cache IO 
adaptor.
+DEFINE_mDouble(file_cache_io_adaptor_skip_read_factor, "1.0");
+DEFINE_Validator(file_cache_io_adaptor_skip_read_factor,
+                 [](double v) { return std::isfinite(v) && v > 0; });
+
 // async file cache write
 DEFINE_mBool(enable_async_file_cache_write, "false");
 DEFINE_mInt32(async_file_cache_write_workers_per_disk, "16");
diff --git a/be/src/common/config.h b/be/src/common/config.h
index 018b70d2bf9..579eedef489 100644
--- a/be/src/common/config.h
+++ b/be/src/common/config.h
@@ -1381,6 +1381,8 @@ DECLARE_mBool(enable_evaluate_shadow_queue_diff);
 
 DECLARE_mBool(file_cache_enable_only_warm_up_idx);
 
+DECLARE_mDouble(file_cache_io_adaptor_skip_read_factor);
+
 // async file cache write
 DECLARE_mBool(enable_async_file_cache_write);
 DECLARE_mInt32(async_file_cache_write_workers_per_disk);
diff --git a/be/src/core/types.h b/be/src/core/types.h
index 1872d9c4ba4..ca5761e0474 100644
--- a/be/src/core/types.h
+++ b/be/src/core/types.h
@@ -575,7 +575,6 @@ struct NativeType<Decimal256> {
     using Type = wide::Int256;
 };
 
-// NOLINTEND(readability-function-size)
 #include "common/compile_check_end.h"
 } // namespace doris
 
diff --git a/be/src/exec/scan/file_scan_io_context.h 
b/be/src/exec/scan/file_scan_io_context.h
index 85bd6ae1abd..8e91bbb9812 100644
--- a/be/src/exec/scan/file_scan_io_context.h
+++ b/be/src/exec/scan/file_scan_io_context.h
@@ -29,6 +29,10 @@ inline void init_file_scan_io_context(RuntimeState* state, 
io::IOContext* io_ctx
     io_ctx->query_id = &state->query_id();
     if (state->query_options().query_type == TQueryType::SELECT) {
         io_ctx->reader_type = ReaderType::READER_QUERY;
+        // Missing options from an older FE must not enable a new remote-read 
policy.
+        io_ctx->enable_file_cache_io_adaptor =
+                state->query_options().__isset.enable_file_cache_io_adaptor &&
+                state->query_options().enable_file_cache_io_adaptor;
         if (auto* query_ctx = state->get_query_ctx(); query_ctx != nullptr) {
             io_ctx->remote_scan_cache_write_limiter = 
query_ctx->remote_scan_cache_write_limiter();
         }
diff --git a/be/src/io/cache/block_file_cache.cpp 
b/be/src/io/cache/block_file_cache.cpp
index c17ac0438fd..4deb1695ced 100644
--- a/be/src/io/cache/block_file_cache.cpp
+++ b/be/src/io/cache/block_file_cache.cpp
@@ -49,6 +49,7 @@
 #include "io/cache/block_file_cache_ttl_mgr.h"
 #include "io/cache/file_block.h"
 #include "io/cache/file_cache_common.h"
+#include "io/cache/file_cache_io_adaptor.h"
 #include "io/cache/fs_file_cache_storage.h"
 #include "io/cache/inflight_write_buffer_index.h"
 #include "io/cache/mem_file_cache_storage.h"
@@ -194,7 +195,8 @@ int64_t steady_clock_seconds() {
 
 BlockFileCache::BlockFileCache(const std::string& cache_base_path,
                                const FileCacheSettings& cache_settings)
-        : _cache_base_path(cache_base_path),
+        : _io_adaptor(std::make_unique<FileCacheIOAdaptor>()),
+          _cache_base_path(cache_base_path),
           _capacity(cache_settings.capacity),
           _max_file_block_size(cache_settings.max_file_block_size) {
     _cur_cache_size_metrics = 
std::make_shared<bvar::Status<size_t>>(_cache_base_path.c_str(),
@@ -794,6 +796,22 @@ void 
BlockFileCache::add_need_update_lru_block(FileBlockSPtr block) {
     }
 }
 
+void BlockFileCache::record_query_cache_hit(const FileBlocks& blocks) {
+    // Adaptor hits skip get_or_set. Count only completed disk reads so remote 
bypasses and
+    // failed copies retried by the planner cannot inflate disk-cache hit 
ratios.
+    const size_t count = blocks.size();
+    size_t bytes = 0;
+    for (const auto& block : blocks) {
+        bytes += block->range().size();
+    }
+    *_num_read_blocks << count;
+    *_num_hit_blocks << count;
+    *_no_warmup_num_read_blocks << count;
+    *_no_warmup_num_hit_blocks << count;
+    *_total_read_size_metrics << bytes;
+    *_total_hit_size_metrics << bytes;
+}
+
 Status BlockFileCache::get_downloaded_blocks_if_fully_covered(const 
UInt128Wrapper& hash,
                                                               size_t offset, 
size_t size,
                                                               const 
CacheContext& context,
diff --git a/be/src/io/cache/block_file_cache.h 
b/be/src/io/cache/block_file_cache.h
index 6cb9513ff3b..fe792fbcbc5 100644
--- a/be/src/io/cache/block_file_cache.h
+++ b/be/src/io/cache/block_file_cache.h
@@ -83,6 +83,7 @@ private:
 class AsyncCacheWriteManager;
 class FSFileCacheStorage;
 class InflightWriteBufferIndex;
+class FileCacheIOAdaptor;
 
 struct FileBlocksProbeResult {
     explicit FileBlocksProbeResult(std::vector<FileBlockSPtr> file_blocks_)
@@ -259,6 +260,11 @@ public:
                                                   size_t size, const 
CacheContext& context,
                                                   FileBlocks* blocks, bool* 
fully_covered);
 
+    FileCacheIOAdaptor& io_adaptor() { return *_io_adaptor; }
+
+    /// Account a completed query disk hit that bypassed get_or_set, using 
complete block sizes.
+    void record_query_cache_hit(const FileBlocks& blocks);
+
     /**
      * record blocks read directly by CachedRemoteFileReader
      */
@@ -550,6 +556,8 @@ private:
     size_t recycle_deleting_blocks(size_t batch_limit);
 
     // info
+    // A congested cache path must not alter routing on other cache disks.
+    std::unique_ptr<FileCacheIOAdaptor> _io_adaptor;
     std::string _cache_base_path;
     size_t _capacity = 0;
     size_t _max_file_block_size = 0;
diff --git a/be/src/io/cache/block_file_cache_profile.cpp 
b/be/src/io/cache/block_file_cache_profile.cpp
index 6e4222dbc11..48184e3b58b 100644
--- a/be/src/io/cache/block_file_cache_profile.cpp
+++ b/be/src/io/cache/block_file_cache_profile.cpp
@@ -100,6 +100,18 @@ FileCacheStatistics diff_file_cache_statistics(const 
FileCacheStatistics& curren
     SUBTRACT_FIELD(lock_wait_timer);
     SUBTRACT_FIELD(get_timer);
     SUBTRACT_FIELD(set_timer);
+    SUBTRACT_FIELD(io_adaptor_lookup_count);
+    SUBTRACT_FIELD(io_adaptor_lookup_time_ns);
+    SUBTRACT_FIELD(io_adaptor_local_reads);
+    SUBTRACT_FIELD(io_adaptor_local_time_ns);
+    SUBTRACT_FIELD(io_adaptor_bypass_count);
+    SUBTRACT_FIELD(io_adaptor_bypass_bytes);
+    SUBTRACT_FIELD(io_adaptor_remote_bytes);
+    SUBTRACT_FIELD(io_adaptor_remote_time_ns);
+    SUBTRACT_FIELD(io_adaptor_local_probes);
+    SUBTRACT_FIELD(io_adaptor_remote_probes);
+    SUBTRACT_FIELD(io_adaptor_remote_failures);
+    SUBTRACT_FIELD(io_adaptor_fallback_local);
     SUBTRACT_FIELD(async_cache_write_submitted);
     SUBTRACT_FIELD(async_cache_write_rejected);
     SUBTRACT_FIELD(async_cache_write_buffer_alloc_fail);
@@ -193,6 +205,30 @@ 
FileCacheProfileReporter::FileCacheProfileReporter(RuntimeProfile* profile,
     lock_wait_timer = ADD_CHILD_TIMER_WITH_LEVEL(profile, "LockWaitTimer", 
cache_profile, 1);
     get_timer = ADD_CHILD_TIMER_WITH_LEVEL(profile, "GetTimer", cache_profile, 
1);
     set_timer = ADD_CHILD_TIMER_WITH_LEVEL(profile, "SetTimer", cache_profile, 
1);
+    io_adaptor_lookup_count = ADD_CHILD_COUNTER_WITH_LEVEL(profile, 
"IOAdaptorLookupCount",
+                                                           TUnit::UNIT, 
cache_profile, 1);
+    io_adaptor_lookup_time_ns = ADD_CHILD_COUNTER_WITH_LEVEL(profile, 
"IOAdaptorLookupTime",
+                                                             TUnit::TIME_NS, 
cache_profile, 1);
+    io_adaptor_local_reads = ADD_CHILD_COUNTER_WITH_LEVEL(profile, 
"IOAdaptorLocalReadCount",
+                                                          TUnit::UNIT, 
cache_profile, 1);
+    io_adaptor_local_time_ns = ADD_CHILD_COUNTER_WITH_LEVEL(profile, 
"IOAdaptorLocalReadTime",
+                                                            TUnit::TIME_NS, 
cache_profile, 1);
+    io_adaptor_bypass_count = ADD_CHILD_COUNTER_WITH_LEVEL(profile, 
"IOAdaptorBypassCount",
+                                                           TUnit::UNIT, 
cache_profile, 1);
+    io_adaptor_bypass_bytes = ADD_CHILD_COUNTER_WITH_LEVEL(profile, 
"IOAdaptorBypassBytes",
+                                                           TUnit::BYTES, 
cache_profile, 1);
+    io_adaptor_remote_bytes = ADD_CHILD_COUNTER_WITH_LEVEL(profile, 
"IOAdaptorRemoteReadBytes",
+                                                           TUnit::BYTES, 
cache_profile, 1);
+    io_adaptor_remote_time_ns = ADD_CHILD_COUNTER_WITH_LEVEL(profile, 
"IOAdaptorRemoteReadTime",
+                                                             TUnit::TIME_NS, 
cache_profile, 1);
+    io_adaptor_local_probes = ADD_CHILD_COUNTER_WITH_LEVEL(profile, 
"IOAdaptorLocalProbeCount",
+                                                           TUnit::UNIT, 
cache_profile, 1);
+    io_adaptor_remote_probes = ADD_CHILD_COUNTER_WITH_LEVEL(profile, 
"IOAdaptorRemoteProbeCount",
+                                                            TUnit::UNIT, 
cache_profile, 1);
+    io_adaptor_remote_failures = ADD_CHILD_COUNTER_WITH_LEVEL(
+            profile, "IOAdaptorRemoteFailureCount", TUnit::UNIT, 
cache_profile, 1);
+    io_adaptor_fallback_local = ADD_CHILD_COUNTER_WITH_LEVEL(profile, 
"IOAdaptorFallbackLocalCount",
+                                                             TUnit::UNIT, 
cache_profile, 1);
     async_cache_write_submitted = ADD_CHILD_COUNTER_WITH_LEVEL(
             profile, "AsyncCacheWriteSubmittedCount", TUnit::UNIT, 
cache_profile, 1);
     async_cache_write_rejected = ADD_CHILD_COUNTER_WITH_LEVEL(
@@ -325,6 +361,18 @@ void FileCacheProfileReporter::update(const 
FileCacheStatistics* statistics) con
     COUNTER_UPDATE(lock_wait_timer, statistics->lock_wait_timer);
     COUNTER_UPDATE(get_timer, statistics->get_timer);
     COUNTER_UPDATE(set_timer, statistics->set_timer);
+    COUNTER_UPDATE(io_adaptor_lookup_count, 
statistics->io_adaptor_lookup_count);
+    COUNTER_UPDATE(io_adaptor_lookup_time_ns, 
statistics->io_adaptor_lookup_time_ns);
+    COUNTER_UPDATE(io_adaptor_local_reads, statistics->io_adaptor_local_reads);
+    COUNTER_UPDATE(io_adaptor_local_time_ns, 
statistics->io_adaptor_local_time_ns);
+    COUNTER_UPDATE(io_adaptor_bypass_count, 
statistics->io_adaptor_bypass_count);
+    COUNTER_UPDATE(io_adaptor_bypass_bytes, 
statistics->io_adaptor_bypass_bytes);
+    COUNTER_UPDATE(io_adaptor_remote_bytes, 
statistics->io_adaptor_remote_bytes);
+    COUNTER_UPDATE(io_adaptor_remote_time_ns, 
statistics->io_adaptor_remote_time_ns);
+    COUNTER_UPDATE(io_adaptor_local_probes, 
statistics->io_adaptor_local_probes);
+    COUNTER_UPDATE(io_adaptor_remote_probes, 
statistics->io_adaptor_remote_probes);
+    COUNTER_UPDATE(io_adaptor_remote_failures, 
statistics->io_adaptor_remote_failures);
+    COUNTER_UPDATE(io_adaptor_fallback_local, 
statistics->io_adaptor_fallback_local);
     COUNTER_UPDATE(async_cache_write_submitted, 
statistics->async_cache_write_submitted);
     COUNTER_UPDATE(async_cache_write_rejected, 
statistics->async_cache_write_rejected);
     COUNTER_UPDATE(async_cache_write_buffer_alloc_fail,
diff --git a/be/src/io/cache/block_file_cache_profile.h 
b/be/src/io/cache/block_file_cache_profile.h
index 1aeb9a88554..dbaf92cadc4 100644
--- a/be/src/io/cache/block_file_cache_profile.h
+++ b/be/src/io/cache/block_file_cache_profile.h
@@ -90,6 +90,18 @@ struct FileCacheProfileReporter {
     RuntimeProfile::Counter* lock_wait_timer = nullptr;
     RuntimeProfile::Counter* get_timer = nullptr;
     RuntimeProfile::Counter* set_timer = nullptr;
+    RuntimeProfile::Counter* io_adaptor_lookup_count = nullptr;
+    RuntimeProfile::Counter* io_adaptor_lookup_time_ns = nullptr;
+    RuntimeProfile::Counter* io_adaptor_local_reads = nullptr;
+    RuntimeProfile::Counter* io_adaptor_local_time_ns = nullptr;
+    RuntimeProfile::Counter* io_adaptor_bypass_count = nullptr;
+    RuntimeProfile::Counter* io_adaptor_bypass_bytes = nullptr;
+    RuntimeProfile::Counter* io_adaptor_remote_bytes = nullptr;
+    RuntimeProfile::Counter* io_adaptor_remote_time_ns = nullptr;
+    RuntimeProfile::Counter* io_adaptor_local_probes = nullptr;
+    RuntimeProfile::Counter* io_adaptor_remote_probes = nullptr;
+    RuntimeProfile::Counter* io_adaptor_remote_failures = nullptr;
+    RuntimeProfile::Counter* io_adaptor_fallback_local = nullptr;
     RuntimeProfile::Counter* async_cache_write_submitted = nullptr;
     RuntimeProfile::Counter* async_cache_write_rejected = nullptr;
     RuntimeProfile::Counter* async_cache_write_buffer_alloc_fail = nullptr;
diff --git a/be/src/io/cache/cached_remote_file_reader.cpp 
b/be/src/io/cache/cached_remote_file_reader.cpp
index 6a2abb5c847..2b3f4159e7d 100644
--- a/be/src/io/cache/cached_remote_file_reader.cpp
+++ b/be/src/io/cache/cached_remote_file_reader.cpp
@@ -48,9 +48,12 @@
 #include "io/cache/block_file_cache_factory.h"
 #include "io/cache/block_file_cache_profile.h"
 #include "io/cache/file_block.h"
+#include "io/cache/file_cache_io_adaptor.h"
+#include "io/cache/inflight_write_buffer_index.h"
 #include "io/cache/peer_file_cache_reader.h"
 #include "io/cache/remote_scan_cache_write_limiter.h"
 #include "io/fs/file_reader.h"
+#include "io/fs/hdfs_file_reader.h"
 #include "io/fs/local_file_system.h"
 #include "io/io_common.h"
 #include "runtime/exec_env.h"
@@ -124,7 +127,11 @@ 
CachedRemoteFileReader::CachedRemoteFileReader(FileReaderSPtr remote_file_reader
           _cache_write_mode(opts.cache_write_mode),
           _tablet_id(opts.is_doris_table ? opts.tablet_id : 0),
           _storage_resource_id(opts.storage_resource_id),
-          _remote_file_reader(std::move(remote_file_reader)) {
+          _remote_file_reader(std::move(remote_file_reader)),
+          // HDFS destroys its handle after read errors. Even a successful 
cache fallback would
+          // leave size() and later required misses unusable, so never issue 
optional HDFS reads.
+          
_io_adaptor_supports_fallback(dynamic_cast<HdfsFileReader*>(_remote_file_reader.get())
 ==
+                                        nullptr) {
     DCHECK(!_is_doris_table || _tablet_id > 0);
     if (_is_doris_table) {
         _init_doris_table_cache();
@@ -322,20 +329,6 @@ Status execute_peer_read(const std::vector<FileBlockSPtr>& 
empty_blocks,
     return st;
 }
 
-// Execute S3 read
-Status execute_s3_read(size_t empty_start, size_t& size, 
std::unique_ptr<char[]>& buffer,
-                       ReadStatistics& stats, const IOContext* io_ctx,
-                       FileReaderSPtr remote_file_reader) {
-    s3_read_counter << 1;
-    SCOPED_RAW_TIMER(&stats.remote_read_timer);
-    stats.from_peer_cache = false;
-    auto st = remote_file_reader->read_at(empty_start, Slice(buffer.get(), 
size), &size, io_ctx);
-    if (st.ok()) {
-        stats.remote_physical_read_bytes += size;
-    }
-    return st;
-}
-
 CloudWarmUpManager& get_warm_up_manager() {
     return 
ExecEnv::GetInstance()->storage_engine().to_cloud().cloud_warm_up_manager();
 }
@@ -602,7 +595,7 @@ Status CachedRemoteFileReader::_execute_s3_fallback(size_t 
empty_start, size_t s
     }
     buffer.reset(new char[span_size]);
     size_t read_size = span_size;
-    return execute_s3_read(empty_start, read_size, buffer, stats, io_ctx, 
_remote_file_reader);
+    return _read_remote_at(empty_start, Slice(buffer.get(), span_size), 
&read_size, io_ctx, stats);
 }
 
 Status CachedRemoteFileReader::_execute_sequential_peer_read(
@@ -1060,15 +1053,11 @@ Status 
CachedRemoteFileReader::_read_remaining_blocks_from_cache(
             size_t remote_bytes_read {0};
             stats.hit_cache = false;
             stats.from_peer_cache = false;
-            s3_read_counter << 1;
-            SCOPED_RAW_TIMER(&stats.remote_read_timer);
-            RETURN_IF_ERROR(_remote_file_reader->read_at(
+            RETURN_IF_ERROR(_read_remote_at(
                     current_offset, Slice(result.data + (current_offset - 
offset), read_size),
-                    &remote_bytes_read, io_ctx));
+                    &remote_bytes_read, io_ctx, stats));
             indirect_read_bytes += read_size;
             source_read_breakdown.remote_bytes += remote_bytes_read;
-            // Self-heal fell back to a real storage GET; count it as physical 
remote IO.
-            stats.remote_physical_read_bytes += remote_bytes_read;
             DCHECK(remote_bytes_read == read_size);
         }
 
@@ -1121,6 +1110,53 @@ Status 
CachedRemoteFileReader::_read_from_indirect_cache(size_t offset, Slice re
     return Status::OK();
 }
 
+bool CachedRemoteFileReader::_try_read_from_inflight_buffers(size_t offset, 
Slice result,
+                                                             size_t bytes_req, 
bool is_dryrun,
+                                                             ReadStatistics& 
stats) {
+    if (!config::enable_async_file_cache_write_inflight_write_buffer_index) {
+        return false;
+    }
+    auto* inflight_index = _cache->inflight_write_buffer_index();
+    DORIS_CHECK(inflight_index != nullptr);
+    const auto block_size = 
static_cast<size_t>(config::file_cache_each_block_size);
+    DORIS_CHECK(block_size > 0);
+    const size_t request_end = offset + bytes_req;
+    std::vector<size_t> block_offsets;
+    for (size_t block_offset = offset / block_size * block_size; block_offset 
< request_end;
+         block_offset += block_size) {
+        block_offsets.emplace_back(block_offset);
+    }
+    auto entries = inflight_index->lookup_all(_cache_hash, block_offsets);
+    bool fully_covered = true;
+    for (const auto& item : entries) {
+        if (item.entry == nullptr) {
+            ++stats.inflight_write_buffer_index_miss;
+            fully_covered = false;
+        } else {
+            ++stats.inflight_write_buffer_index_hit;
+        }
+    }
+    if (!fully_covered) {
+        return false;
+    }
+    for (const auto& item : entries) {
+        const auto& entry = item.entry;
+        DORIS_CHECK(entry->buffer != nullptr);
+        DORIS_CHECK(entry->buffer_offset == item.block_offset);
+        const size_t copy_left = std::max(offset, item.block_offset);
+        const size_t copy_end = std::min(request_end, item.block_offset + 
block_size);
+        const size_t copy_size = copy_end - copy_left;
+        const size_t buffer_offset = copy_left - item.block_offset;
+        DORIS_CHECK(buffer_offset <= entry->buffer_size);
+        DORIS_CHECK(copy_size <= entry->buffer_size - buffer_offset);
+        if (!is_dryrun) [[likely]] {
+            std::memcpy(result.data + copy_left - offset, 
entry->buffer->data() + buffer_offset,
+                        copy_size);
+        }
+    }
+    return true;
+}
+
 Status CachedRemoteFileReader::_read_remote_only_on_cache_miss(
         size_t offset, Slice result, size_t bytes_req, bool is_dryrun, size_t* 
bytes_read,
         ReadStatistics& stats, SourceReadBreakdown& source_read_breakdown,
@@ -1129,8 +1165,8 @@ Status 
CachedRemoteFileReader::_read_remote_only_on_cache_miss(
         stats.hit_cache = false;
         stats.from_peer_cache = false;
         stats.skip_cache = true;
-        s3_read_counter << 1;
         if (is_dryrun) [[unlikely]] {
+            s3_read_counter << 1;
             *bytes_read = bytes_req;
             g_read_cache_indirect_bytes << 0;
             g_read_cache_indirect_total_bytes << bytes_req;
@@ -1138,22 +1174,31 @@ Status 
CachedRemoteFileReader::_read_remote_only_on_cache_miss(
         }
 
         size_t remote_bytes_read = bytes_req;
-        SCOPED_RAW_TIMER(&stats.remote_read_timer);
-        RETURN_IF_ERROR(_remote_file_reader->read_at(offset, 
Slice(result.data, bytes_req),
-                                                     &remote_bytes_read, 
io_ctx));
+        RETURN_IF_ERROR(_read_remote_at(offset, Slice(result.data, bytes_req), 
&remote_bytes_read,
+                                        io_ctx, stats));
         *bytes_read = remote_bytes_read;
         DCHECK_EQ(*bytes_read, bytes_req);
         source_read_breakdown.remote_bytes += remote_bytes_read;
-        // This is a real storage GET, so it must count as physical remote IO 
just like
-        // the block-download path; otherwise profiles show 
scanned-from-remote bytes
-        // with zero physical reads whenever remote-only-on-miss is active.
-        stats.remote_physical_read_bytes += remote_bytes_read;
         g_read_cache_indirect_bytes << remote_bytes_read;
         g_read_cache_indirect_total_bytes << remote_bytes_read;
         return Status::OK();
     };
 
     g_read_cache_indirect_num << 1;
+    // A zero write budget must not hide buffers accepted before async writes 
were disabled.
+    // Check full memory coverage before disk metadata, matching the 
memory-first async planner.
+    if (_try_read_from_inflight_buffers(offset, result, bytes_req, is_dryrun, 
stats)) {
+        const size_t local_read_bytes = is_dryrun ? 0 : bytes_req;
+        if (is_dryrun) [[unlikely]] {
+            g_skip_local_cache_io_sum_bytes << bytes_req;
+        }
+        *bytes_read = bytes_req;
+        stats.hit_cache = true;
+        source_read_breakdown.local_bytes += local_read_bytes;
+        g_read_cache_indirect_bytes << local_read_bytes;
+        g_read_cache_indirect_total_bytes << bytes_req;
+        return Status::OK();
+    }
     CacheContext cache_context(io_ctx);
     cache_context.stats = &stats;
     cache_context.tablet_id = _tablet_id;
@@ -1212,6 +1257,213 @@ Status 
CachedRemoteFileReader::_read_remote_only_on_cache_miss(
     return Status::OK();
 }
 
+namespace {
+
+// A partial cache copy cannot be published: the caller retries the complete 
range through
+// the normal planner when any block fails, preserving its cache-repair and 
remote fallback.
+bool read_adaptor_cached_blocks(BlockFileCache* cache, const UInt128Wrapper& 
hash,
+                                const FileBlocks& blocks, size_t offset, Slice 
result,
+                                ReadStatistics& stats) {
+    const auto bytes_req = result.size;
+    const auto local_start = MonotonicNanos();
+    ++stats.io_adaptor_local_reads;
+    Defer local_timer {[&] {
+        const auto elapsed = MonotonicNanos() - local_start;
+        stats.io_adaptor_local_time_ns += elapsed;
+        stats.local_read_timer += elapsed;
+    }};
+    for (const auto& block : blocks) {
+        const auto left = std::max(offset, block->range().left);
+        const auto right = std::min(offset + bytes_req - 1, 
block->range().right);
+        Status status = block->read(Slice(result.data + left - offset, right - 
left + 1),
+                                    left - block->range().left);
+        if (!status.ok()) {
+            // Concurrent eviction can remove a previously downloaded file. 
The ordinary path
+            // already handles self-healing and remote fallback, so retry the 
full request there.
+            if (status.is<ErrorCode::NOT_FOUND>()) {
+                cache->remove_if_cached_async(hash);
+            }
+            return false;
+        }
+    }
+    const auto elapsed = MonotonicNanos() - local_start;
+    cache->io_adaptor().record_local(bytes_req, elapsed / 1000);
+    return true;
+}
+
+// Inspect memory coverage without taking the disk-cache mutex. The ordinary 
memory-first planners
+// retain responsibility for copying data and counting inflight hits or misses 
exactly once.
+bool fully_covered_by_inflight_buffers(BlockFileCache* cache, const 
UInt128Wrapper& hash,
+                                       size_t offset, size_t bytes_req) {
+    const size_t block_size = config::file_cache_each_block_size;
+    std::vector<size_t> offsets;
+    for (size_t block_offset = offset / block_size * block_size; block_offset 
< offset + bytes_req;
+         block_offset += block_size) {
+        offsets.push_back(block_offset);
+    }
+    const auto entries = 
cache->inflight_write_buffer_index()->lookup_all(hash, offsets);
+    return std::ranges::all_of(entries, [](const auto& item) { return 
item.entry != nullptr; });
+}
+
+} // namespace
+
+Status CachedRemoteFileReader::_read_remote_at(size_t offset, Slice result, 
size_t* bytes_read,
+                                               const IOContext* io_ctx, 
ReadStatistics& stats) {
+    s3_read_counter << 1;
+    stats.from_peer_cache = false;
+    const auto start = MonotonicNanos();
+    auto status = _remote_file_reader->read_at(offset, result, bytes_read, 
io_ctx);
+    const auto elapsed = MonotonicNanos() - start;
+    stats.remote_read_timer += elapsed;
+    if (status.ok()) {
+        stats.remote_physical_read_bytes += *bytes_read;
+        // Misses can expand to full blocks or issue several GETs. Sample each 
complete call
+        // at its actual size; neither cache writeback nor a later GET belongs 
to this sample.
+        if (*bytes_read == result.size && _io_adaptor_eligible(result.size, 
io_ctx)) {
+            _cache->io_adaptor().record_remote(*bytes_read, elapsed / 1000);
+        }
+    }
+    return status;
+}
+
+bool CachedRemoteFileReader::_io_adaptor_eligible(size_t bytes, const 
IOContext* io_ctx) const {
+    // Only explicitly enabled external query reads may adapt. 
Background/index/warmup reads
+    // and memory-cache/inflight payloads retain their existing policies. 
After an optional
+    // remote read fails, keep later cache hits on the normal path for this 
reader's lifetime.
+    return io_ctx->enable_file_cache_io_adaptor && !_is_doris_table && 
!io_ctx->is_dryrun &&
+           !_io_adaptor_remote_failed.load(std::memory_order_acquire) && 
!io_ctx->is_warmup &&
+           !io_ctx->is_index_data && !io_ctx->is_inverted_index && 
!io_ctx->should_stop &&
+           io_ctx->read_file_cache && bytes > 0 && 
_io_adaptor_supports_fallback &&
+           _cache->get_storage()->get_type() == FileCacheStorageType::DISK;
+}
+
+Status CachedRemoteFileReader::_try_read_with_io_adaptor(
+        size_t offset, Slice result, size_t bytes_req, CacheWriteMode 
cache_write_mode,
+        size_t* bytes_read, const IOContext* io_ctx, ReadStatistics& stats,
+        SourceReadBreakdown& sources, bool* handled) {
+    *handled = false;
+    // Accepted async payloads remain readable after async writes are 
disabled. The
+    // remote-only-on-miss planner still checks memory first for a query with 
zero write budget,
+    // so it must not wait for unrelated disk eviction under _cache->_mutex 
either.
+    const bool memory_first = cache_write_mode == CacheWriteMode::ASYNC_WRITE 
||
+                              use_remote_only_on_cache_miss(io_ctx);
+    if (memory_first && 
config::enable_async_file_cache_write_inflight_write_buffer_index &&
+        fully_covered_by_inflight_buffers(_cache, _cache_hash, offset, 
bytes_req)) {
+        return Status::OK();
+    }
+    FileBlocks blocks;
+    bool fully_covered = false;
+    CacheContext context(io_ctx);
+    context.stats = &stats;
+    context.tablet_id = _tablet_id;
+    ++stats.io_adaptor_lookup_count;
+    {
+        SCOPED_RAW_TIMER(&stats.io_adaptor_lookup_time_ns);
+        RETURN_IF_ERROR(_cache->get_downloaded_blocks_if_fully_covered(
+                _cache_hash, offset, bytes_req, context, &blocks, 
&fully_covered));
+    }
+    if (!fully_covered) {
+        // A mixed hit/miss or inflight-buffer request follows the existing 
sync/async planner.
+        // In particular, a bypass must never acquire downloader ownership or 
cause writeback.
+        return Status::OK();
+    }
+    auto& adaptor = _cache->io_adaptor();
+    const auto decision = adaptor.select(bytes_req, 
config::file_cache_io_adaptor_skip_read_factor);
+    // Release the path-wide probe permit even on cancellation, short reads or 
local repair.
+    Defer probe_done {[&] {
+        if (decision.is_probe()) {
+            adaptor.finish_probe();
+        }
+    }};
+    stats.io_adaptor_local_probes += decision.local_probe;
+    stats.io_adaptor_remote_probes += decision.remote_probe;
+    if (decision.read_remote()) {
+        // Requested and returned bytes differ for failed/short reads 
recovered from local cache.
+        ++stats.io_adaptor_bypass_count;
+        stats.io_adaptor_bypass_bytes += bytes_req;
+        size_t remote_bytes = 0;
+        s3_read_counter << 1;
+        const auto start = MonotonicNanos();
+        Status status = _remote_file_reader->read_at(offset, 
Slice(result.data, bytes_req),
+                                                     &remote_bytes, io_ctx);
+        const auto elapsed = MonotonicNanos() - start;
+        stats.io_adaptor_remote_time_ns += elapsed;
+        stats.remote_read_timer += elapsed;
+        stats.io_adaptor_remote_bytes += remote_bytes;
+        if (status.ok() && remote_bytes == bytes_req) {
+            stats.remote_physical_read_bytes += remote_bytes;
+            adaptor.record_remote(remote_bytes, elapsed / 1000);
+            sources.remote_bytes += remote_bytes;
+            stats.hit_cache = false;
+            stats.skip_cache = true;
+            *bytes_read = remote_bytes;
+            *handled = true;
+            return Status::OK();
+        }
+        ++stats.io_adaptor_remote_failures;
+        if (io_ctx->should_stop || status.is<ErrorCode::CANCELLED>()) {
+            return status.ok() ? Status::Cancelled("Adaptive cache read 
cancelled") : status;
+        }
+        // Repeating an optional failing GET would delay every subsequent 
cached range. Keep
+        // required remote misses available without poisoning other readers' 
shared estimates.
+        _io_adaptor_remote_failed.store(true, std::memory_order_release);
+        // The same immutable range is still cached. Overwrite the complete 
caller range after
+        // an error/short remote read; never publish the partially overwritten 
buffer as success.
+        ++stats.io_adaptor_fallback_local;
+    }
+    if (read_adaptor_cached_blocks(_cache, _cache_hash, blocks, offset,
+                                   Slice(result.data, bytes_req), stats)) {
+        // Lookup alone must not count: a failed disk copy retries through the 
ordinary planner.
+        _cache->record_query_cache_hit(blocks);
+        sources.local_bytes += bytes_req;
+        *bytes_read = bytes_req;
+        *handled = true;
+    }
+    return Status::OK();
+}
+
+Status CachedRemoteFileReader::_read_with_cache_policy(size_t offset, Slice 
result,
+                                                       size_t bytes_req, 
size_t* bytes_read,
+                                                       const IOContext* io_ctx,
+                                                       ReadStatistics& stats,
+                                                       SourceReadBreakdown& 
source_read_breakdown) {
+    const bool is_dryrun = io_ctx->is_dryrun;
+    Status read_st = Status::OK();
+    const CacheWriteMode cache_write_mode = _resolve_cache_write_mode(io_ctx);
+    
TEST_SYNC_POINT("CachedRemoteFileReader::read_at_impl:after_resolve_cache_write_mode");
+    if (_io_adaptor_eligible(bytes_req, io_ctx)) {
+        bool handled = false;
+        read_st = _try_read_with_io_adaptor(offset, result, bytes_req, 
cache_write_mode, bytes_read,
+                                            io_ctx, stats, 
source_read_breakdown, &handled);
+        if (!read_st.ok() || handled) {
+            return read_st;
+        }
+    }
+    if (use_remote_only_on_cache_miss(io_ctx)) {
+        read_st = _read_remote_only_on_cache_miss(offset, result, bytes_req, 
is_dryrun, bytes_read,
+                                                  stats, 
source_read_breakdown, io_ctx);
+        return read_st;
+    }
+
+    size_t already_read = 0;
+    if (_try_read_from_cached_files_directly(offset, result, bytes_req, 
is_dryrun, stats,
+                                             source_read_breakdown, 
already_read, bytes_read)) {
+        return Status::OK();
+    }
+
+    DORIS_CHECK(_cache_align_mode == CacheAlignMode::ALIGN_TO_BLOCK);
+    DORIS_CHECK(cache_write_mode == CacheWriteMode::SYNC_WRITE ||
+                cache_write_mode == CacheWriteMode::ASYNC_WRITE);
+    if (cache_write_mode == CacheWriteMode::ASYNC_WRITE) {
+        read_st = _read_async_write_path(offset, result, bytes_req, 
already_read, bytes_read, stats,
+                                         source_read_breakdown, io_ctx);
+    } else {
+        read_st = _read_from_indirect_cache(offset, result, bytes_req, 
already_read, is_dryrun,
+                                            bytes_read, stats, 
source_read_breakdown, io_ctx);
+    }
+    return read_st;
+}
+
 Status CachedRemoteFileReader::read_at_impl(size_t offset, Slice result, 
size_t* bytes_read,
                                             const IOContext* io_ctx) {
     
SCOPED_CONCURRENCY_COUNT(ConcurrencyStatsManager::instance().cached_remote_reader_read_at);
@@ -1282,30 +1534,8 @@ Status CachedRemoteFileReader::read_at_impl(size_t 
offset, Slice result, size_t*
         }
     }};
 
-    if (use_remote_only_on_cache_miss(io_ctx)) {
-        read_st = _read_remote_only_on_cache_miss(offset, result, bytes_req, 
is_dryrun, bytes_read,
-                                                  stats, 
source_read_breakdown, io_ctx);
-        return read_st;
-    }
-
-    size_t already_read = 0;
-    if (_try_read_from_cached_files_directly(offset, result, bytes_req, 
is_dryrun, stats,
-                                             source_read_breakdown, 
already_read, bytes_read)) {
-        return Status::OK();
-    }
-
-    const CacheWriteMode cache_write_mode = _resolve_cache_write_mode(io_ctx);
-    
TEST_SYNC_POINT("CachedRemoteFileReader::read_at_impl:after_resolve_cache_write_mode");
-    DORIS_CHECK(_cache_align_mode == CacheAlignMode::ALIGN_TO_BLOCK);
-    DORIS_CHECK(cache_write_mode == CacheWriteMode::SYNC_WRITE ||
-                cache_write_mode == CacheWriteMode::ASYNC_WRITE);
-    if (cache_write_mode == CacheWriteMode::ASYNC_WRITE) {
-        read_st = _read_async_write_path(offset, result, bytes_req, 
already_read, bytes_read, stats,
-                                         source_read_breakdown, io_ctx);
-    } else {
-        read_st = _read_from_indirect_cache(offset, result, bytes_req, 
already_read, is_dryrun,
-                                            bytes_read, stats, 
source_read_breakdown, io_ctx);
-    }
+    read_st = _read_with_cache_policy(offset, result, bytes_req, bytes_read, 
io_ctx, stats,
+                                      source_read_breakdown);
     return read_st;
 }
 
@@ -1412,6 +1642,18 @@ void CachedRemoteFileReader::_update_stats(const 
ReadStatistics& read_stats,
     statis->lock_wait_timer += read_stats.lock_wait_timer;
     statis->get_timer += read_stats.get_timer;
     statis->set_timer += read_stats.set_timer;
+    statis->io_adaptor_lookup_count += read_stats.io_adaptor_lookup_count;
+    statis->io_adaptor_lookup_time_ns += read_stats.io_adaptor_lookup_time_ns;
+    statis->io_adaptor_local_reads += read_stats.io_adaptor_local_reads;
+    statis->io_adaptor_local_time_ns += read_stats.io_adaptor_local_time_ns;
+    statis->io_adaptor_bypass_count += read_stats.io_adaptor_bypass_count;
+    statis->io_adaptor_bypass_bytes += read_stats.io_adaptor_bypass_bytes;
+    statis->io_adaptor_remote_bytes += read_stats.io_adaptor_remote_bytes;
+    statis->io_adaptor_remote_time_ns += read_stats.io_adaptor_remote_time_ns;
+    statis->io_adaptor_local_probes += read_stats.io_adaptor_local_probes;
+    statis->io_adaptor_remote_probes += read_stats.io_adaptor_remote_probes;
+    statis->io_adaptor_remote_failures += 
read_stats.io_adaptor_remote_failures;
+    statis->io_adaptor_fallback_local += read_stats.io_adaptor_fallback_local;
     statis->async_cache_write_submitted += 
read_stats.async_cache_write_submitted;
     statis->async_cache_write_rejected += 
read_stats.async_cache_write_rejected;
     statis->async_cache_write_buffer_alloc_fail += 
read_stats.async_cache_write_buffer_alloc_fail;
diff --git a/be/src/io/cache/cached_remote_file_reader.h 
b/be/src/io/cache/cached_remote_file_reader.h
index 68b112d9ece..af50a87cae0 100644
--- a/be/src/io/cache/cached_remote_file_reader.h
+++ b/be/src/io/cache/cached_remote_file_reader.h
@@ -17,6 +17,7 @@
 
 #pragma once
 
+#include <atomic>
 #include <cstddef>
 #include <cstdint>
 #include <map>
@@ -335,8 +336,13 @@ private:
                                      SourceReadBreakdown& 
source_read_breakdown,
                                      const IOContext* io_ctx);
 
-    /// Read local cache only when downloaded blocks fully cover the request; 
otherwise read remote
-    /// data directly without writing file cache.
+    // Accepted async buffers outlive a write-policy change. Read-only queries 
can use them
+    // without taking the disk-cache mutex, but a partial memory hit must not 
modify result.
+    bool _try_read_from_inflight_buffers(size_t offset, Slice result, size_t 
bytes_req,
+                                         bool is_dryrun, ReadStatistics& 
stats);
+
+    /// Read in-flight buffers or downloaded blocks only when one source fully 
covers the request;
+    /// otherwise read remote data directly without writing file cache.
     /// @param[in] offset Original request offset.
     /// @param[out] result Destination buffer for the original request.
     /// @param[in] bytes_req Original request size.
@@ -426,12 +432,29 @@ private:
                        const SourceReadBreakdown& source_read_breakdown, 
FileCacheStatistics* state,
                        FileCacheReadType read_type) const;
 
+    /// Resolve the write mode once and dispatch adaptation, cache hits and 
required misses.
+    Status _read_with_cache_policy(size_t offset, Slice result, size_t 
bytes_req,
+                                   size_t* bytes_read, const IOContext* io_ctx,
+                                   ReadStatistics& stats, SourceReadBreakdown& 
sources);
+
+    // Time and sample each actual storage read, independently of cache writes 
or other GETs.
+    Status _read_remote_at(size_t offset, Slice result, size_t* bytes_read, 
const IOContext* io_ctx,
+                           ReadStatistics& stats);
+
+    bool _io_adaptor_eligible(size_t bytes, const IOContext* io_ctx) const;
+    Status _try_read_with_io_adaptor(size_t offset, Slice result, size_t 
bytes_req,
+                                     CacheWriteMode cache_write_mode, size_t* 
bytes_read,
+                                     const IOContext* io_ctx, ReadStatistics& 
stats,
+                                     SourceReadBreakdown& sources, bool* 
handled);
+
+    std::atomic<bool> _io_adaptor_remote_failed {false};
     bool _is_doris_table = false;
     CacheAlignMode _cache_align_mode {CacheAlignMode::ALIGN_TO_BLOCK};
     CacheWriteMode _cache_write_mode {CacheWriteMode::DEFAULT};
     int64_t _tablet_id = -1;
     std::string _storage_resource_id;
     FileReaderSPtr _remote_file_reader;
+    const bool _io_adaptor_supports_fallback;
     UInt128Wrapper _cache_hash;
     BlockFileCache* _cache = nullptr;
     std::shared_mutex _mtx;
diff --git a/be/src/io/cache/file_block.cpp b/be/src/io/cache/file_block.cpp
index d9d57b08bf9..f221d9eb932 100644
--- a/be/src/io/cache/file_block.cpp
+++ b/be/src/io/cache/file_block.cpp
@@ -230,6 +230,7 @@ Status FileBlock::finalize() {
 }
 
 Status FileBlock::read(Slice buffer, size_t read_offset) {
+    TEST_SYNC_POINT("FileBlock::adaptor_benchmark_read");
     return _mgr->_storage->read(_key, read_offset, buffer);
 }
 
diff --git a/be/src/io/cache/file_cache_common.h 
b/be/src/io/cache/file_cache_common.h
index 8a231cbfb30..be7614decf0 100644
--- a/be/src/io/cache/file_cache_common.h
+++ b/be/src/io/cache/file_cache_common.h
@@ -88,6 +88,18 @@ struct ReadStatistics {
     int64_t lock_wait_timer = 0;
     int64_t get_timer = 0;
     int64_t set_timer = 0;
+    int64_t io_adaptor_lookup_count = 0;
+    int64_t io_adaptor_lookup_time_ns = 0;
+    int64_t io_adaptor_local_reads = 0;
+    int64_t io_adaptor_local_time_ns = 0;
+    int64_t io_adaptor_bypass_count = 0;
+    int64_t io_adaptor_bypass_bytes = 0;
+    int64_t io_adaptor_remote_bytes = 0;
+    int64_t io_adaptor_remote_time_ns = 0;
+    int64_t io_adaptor_local_probes = 0;
+    int64_t io_adaptor_remote_probes = 0;
+    int64_t io_adaptor_remote_failures = 0;
+    int64_t io_adaptor_fallback_local = 0;
     int64_t async_cache_write_submitted = 0;
     int64_t async_cache_write_rejected = 0;
     int64_t async_cache_write_buffer_alloc_fail = 0;
diff --git a/be/src/io/cache/file_cache_io_adaptor.cpp 
b/be/src/io/cache/file_cache_io_adaptor.cpp
new file mode 100644
index 00000000000..503a7c91f39
--- /dev/null
+++ b/be/src/io/cache/file_cache_io_adaptor.cpp
@@ -0,0 +1,140 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+#include "io/cache/file_cache_io_adaptor.h"
+
+#include <algorithm>
+#include <limits>
+
+#include "cpp/sync_point.h"
+#include "util/time.h"
+
+namespace doris::io {
+
+size_t FileCacheIOAdaptor::bucket_index(size_t bytes) {
+    return static_cast<size_t>(std::ranges::lower_bound(SIZE_LIMITS, bytes) - 
SIZE_LIMITS.begin());
+}
+
+void FileCacheIOAdaptor::Window::record(int64_t latency_us) {
+    // Failed/invalid timings must not train the controller; a sub-microsecond 
read may be zero.
+    if (latency_us < 0) {
+        return;
+    }
+    if (count == WINDOW_SIZE) {
+        sum -= samples[next];
+    } else {
+        ++count;
+    }
+    samples[next] = latency_us;
+    sum += latency_us;
+    next = (next + 1) % WINDOW_SIZE;
+}
+
+int64_t FileCacheIOAdaptor::Window::average() const {
+    return count == 0 ? 0 : static_cast<int64_t>(sum / count);
+}
+
+FileCacheIOAdaptor::Decision FileCacheIOAdaptor::select(size_t bytes, double 
skip_read_factor) {
+    auto now_us = MonotonicMicros();
+    TEST_SYNC_POINT_CALLBACK("FileCacheIOAdaptor::select:now_us", &now_us);
+    return _select(bytes, skip_read_factor, now_us);
+}
+
+FileCacheIOAdaptor::Decision FileCacheIOAdaptor::_select(size_t bytes, double 
skip_read_factor,
+                                                         int64_t now_us) {
+    std::lock_guard lock(_mutex);
+    const auto index = bucket_index(bytes);
+    for (auto& candidate : _buckets) {
+        // Only seen buckets age; saturation prevents an idle bucket from 
wrapping into activity.
+        if (candidate.probe_wait_requests != 0 &&
+            candidate.idle_requests != std::numeric_limits<size_t>::max()) {
+            ++candidate.idle_requests;
+        }
+    }
+    auto& bucket = _buckets[index];
+    // With 64 small hits then one large hit, a fixed 64-hit expiry steals the 
large bucket's
+    // turn just before it returns. Retain its observed gap until it gets a 
probe; a short
+    // burst must not erase the longer wait either.
+    bucket.probe_wait_requests =
+            std::max({bucket.probe_wait_requests, bucket.idle_requests, 
PROBE_REQUEST_INTERVAL});
+    bucket.idle_requests = 0;
+    Decision decision;
+    decision.local_latency_us = bucket.local.average();
+    decision.remote_latency_us = bucket.remote.average();
+    // Compare actual service times only within a size bucket: a 4 KiB / 100 
us local read
+    // must not become a 12.8 ms full-block estimate and lose to an unrelated 
1 MiB GET.
+    if (bucket.local.count == WINDOW_SIZE && bucket.remote.count == 
WINDOW_SIZE &&
+        decision.local_latency_us >= MIN_LOCAL_LATENCY_US) {
+        decision.bypass = static_cast<double>(decision.local_latency_us) * 
skip_read_factor >
+                          static_cast<double>(decision.remote_latency_us);
+    }
+    _requests_since_probe = std::min(_requests_since_probe + 1, 
PROBE_REQUEST_INTERVAL);
+    // History cannot reveal an unobserved recovery (e.g. local 20 ms -> 100 
us). Route a real
+    // request through the other path, at most once per second and once per 64 
eligible hits.
+    // Keep one probe in flight across the entire cache path, including slow 
local disk reads.
+    // Below the 5 ms floor, remote observations cannot enable bypass. Probing 
a 100 us local
+    // hit through a 20 ms remote path would only increase healthy-cache tail 
latency.
+    if (bucket.local.count == WINDOW_SIZE && decision.local_latency_us >= 
MIN_LOCAL_LATENCY_US &&
+        !_probe_inflight && now_us >= _next_probe_us &&
+        _requests_since_probe == PROBE_REQUEST_INTERVAL) {
+        // With 63 small hits followed by one large hit, granting every 64th 
request would
+        // probe only the large bucket forever. Rotate among buckets within 
their observed
+        // request gaps, retaining quota for the selected bucket's next 
request. A bucket that
+        // stays absent beyond its gap expires without blocking the remaining 
traffic forever.
+        // Apply the same latency floor here: a fast 4 KiB bucket must not 
reserve a slow
+        // 1 MiB bucket's probe turn when it cannot use that turn itself.
+        auto probe_bucket = _next_probe_bucket;
+        for (size_t visited = 0; visited < BUCKET_COUNT; ++visited) {
+            const auto& candidate = _buckets[probe_bucket];
+            if (candidate.local.count == WINDOW_SIZE &&
+                candidate.local.average() >= MIN_LOCAL_LATENCY_US &&
+                candidate.idle_requests < candidate.probe_wait_requests) {
+                break;
+            }
+            probe_bucket = (probe_bucket + 1) % BUCKET_COUNT;
+        }
+        if (probe_bucket == index) {
+            decision.local_probe = decision.bypass;
+            decision.remote_probe = !decision.bypass;
+            decision.bypass = !decision.bypass;
+            _probe_inflight = true;
+            _requests_since_probe = 0;
+            _next_probe_us = now_us + PROBE_INTERVAL_US;
+            _next_probe_bucket = (index + 1) % BUCKET_COUNT;
+            // Reset after admission so an old sparse burst cannot pin later 
probe turns.
+            bucket.probe_wait_requests = PROBE_REQUEST_INTERVAL;
+        }
+    }
+    return decision;
+}
+
+void FileCacheIOAdaptor::finish_probe() {
+    std::lock_guard lock(_mutex);
+    _probe_inflight = false;
+}
+
+void FileCacheIOAdaptor::record_local(size_t bytes, int64_t latency_us) {
+    std::lock_guard lock(_mutex);
+    _buckets[bucket_index(bytes)].local.record(latency_us);
+}
+
+void FileCacheIOAdaptor::record_remote(size_t bytes, int64_t latency_us) {
+    std::lock_guard lock(_mutex);
+    _buckets[bucket_index(bytes)].remote.record(latency_us);
+}
+
+} // namespace doris::io
diff --git a/be/src/io/cache/file_cache_io_adaptor.h 
b/be/src/io/cache/file_cache_io_adaptor.h
new file mode 100644
index 00000000000..c631f64433a
--- /dev/null
+++ b/be/src/io/cache/file_cache_io_adaptor.h
@@ -0,0 +1,82 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+#pragma once
+
+#include <array>
+#include <cstddef>
+#include <cstdint>
+#include <mutex>
+
+namespace doris::io {
+
+// Queries using the same cache path share measured service times, grouped by 
request size.
+class FileCacheIOAdaptor {
+public:
+    struct Decision {
+        bool bypass = false;
+        bool local_probe = false;
+        bool remote_probe = false;
+        int64_t local_latency_us = 0;
+        int64_t remote_latency_us = 0;
+        bool read_remote() const { return bypass; }
+        bool is_probe() const { return local_probe || remote_probe; }
+    };
+
+    Decision select(size_t bytes, double skip_read_factor = 1.0);
+    void finish_probe();
+    void record_local(size_t bytes, int64_t latency_us);
+    void record_remote(size_t bytes, int64_t latency_us);
+
+private:
+    static constexpr size_t WINDOW_SIZE = 50;
+    static constexpr int64_t MIN_LOCAL_LATENCY_US = 5000;
+    static constexpr int64_t PROBE_INTERVAL_US = 1'000'000;
+    static constexpr size_t PROBE_REQUEST_INTERVAL = 64;
+    static constexpr std::array<size_t, 7> SIZE_LIMITS = {
+            4096, 16 * 1024, 64 * 1024, 256 * 1024, 1024 * 1024, 4 * 1024 * 
1024, 16 * 1024 * 1024};
+    static constexpr size_t BUCKET_COUNT = SIZE_LIMITS.size() + 1;
+
+    struct Window {
+        std::array<int64_t, WINDOW_SIZE> samples {};
+        size_t count = 0;
+        size_t next = 0;
+        // Wide accumulation preserves the average even for unusually long, 
valid IO durations.
+        __int128 sum = 0;
+        void record(int64_t latency_us);
+        int64_t average() const;
+    };
+    struct Bucket {
+        Window local;
+        Window remote;
+        size_t idle_requests = 0;
+        // Keep the longest observed gap until a probe is admitted. Zero means 
unseen.
+        size_t probe_wait_requests = 0;
+    };
+    static size_t bucket_index(size_t bytes);
+    Decision _select(size_t bytes, double skip_read_factor, int64_t now_us);
+
+    std::mutex _mutex;
+    std::array<Bucket, BUCKET_COUNT> _buckets;
+    // Probe limits span all size buckets: adding request sizes must not 
multiply disk pressure.
+    size_t _requests_since_probe = 0;
+    size_t _next_probe_bucket = 0;
+    int64_t _next_probe_us = 0;
+    bool _probe_inflight = false;
+};
+
+} // namespace doris::io
diff --git a/be/src/io/io_common.h b/be/src/io/io_common.h
index 4bcab929411..b9523dbb822 100644
--- a/be/src/io/io_common.h
+++ b/be/src/io/io_common.h
@@ -76,6 +76,18 @@ struct FileCacheStatistics {
     int64_t lock_wait_timer = 0;
     int64_t get_timer = 0;
     int64_t set_timer = 0;
+    int64_t io_adaptor_lookup_count = 0;
+    int64_t io_adaptor_lookup_time_ns = 0;
+    int64_t io_adaptor_local_reads = 0;
+    int64_t io_adaptor_local_time_ns = 0;
+    int64_t io_adaptor_bypass_count = 0;
+    int64_t io_adaptor_bypass_bytes = 0;
+    int64_t io_adaptor_remote_bytes = 0;
+    int64_t io_adaptor_remote_time_ns = 0;
+    int64_t io_adaptor_local_probes = 0;
+    int64_t io_adaptor_remote_probes = 0;
+    int64_t io_adaptor_remote_failures = 0;
+    int64_t io_adaptor_fallback_local = 0;
     int64_t async_cache_write_submitted = 0;
     int64_t async_cache_write_rejected = 0;
     int64_t async_cache_write_buffer_alloc_fail = 0;
@@ -153,6 +165,18 @@ struct FileCacheStatistics {
         lock_wait_timer += other.lock_wait_timer;
         get_timer += other.get_timer;
         set_timer += other.set_timer;
+        io_adaptor_lookup_count += other.io_adaptor_lookup_count;
+        io_adaptor_lookup_time_ns += other.io_adaptor_lookup_time_ns;
+        io_adaptor_local_reads += other.io_adaptor_local_reads;
+        io_adaptor_local_time_ns += other.io_adaptor_local_time_ns;
+        io_adaptor_bypass_count += other.io_adaptor_bypass_count;
+        io_adaptor_bypass_bytes += other.io_adaptor_bypass_bytes;
+        io_adaptor_remote_bytes += other.io_adaptor_remote_bytes;
+        io_adaptor_remote_time_ns += other.io_adaptor_remote_time_ns;
+        io_adaptor_local_probes += other.io_adaptor_local_probes;
+        io_adaptor_remote_probes += other.io_adaptor_remote_probes;
+        io_adaptor_remote_failures += other.io_adaptor_remote_failures;
+        io_adaptor_fallback_local += other.io_adaptor_fallback_local;
         async_cache_write_submitted += other.async_cache_write_submitted;
         async_cache_write_rejected += other.async_cache_write_rejected;
         async_cache_write_buffer_alloc_fail += 
other.async_cache_write_buffer_alloc_fail;
@@ -227,6 +251,8 @@ struct IOContext {
     bool is_disposable = false;
     bool is_index_data = false;
     bool read_file_cache = true;
+    // Only explicitly enabled query IO may use adaptation; warmup and 
background IO default off.
+    bool enable_file_cache_io_adaptor = false;
     // TODO(lightman): use following member variables to control file cache
     bool is_persistent = false;
     // stop reader when reading, used in some interrupted operations
diff --git a/be/test/exec/scan/file_scanner_v2_test.cpp 
b/be/test/exec/scan/file_scanner_v2_test.cpp
index 01817ac9c24..b5dd26c40c8 100644
--- a/be/test/exec/scan/file_scanner_v2_test.cpp
+++ b/be/test/exec/scan/file_scanner_v2_test.cpp
@@ -1168,6 +1168,32 @@ TEST(FileScannerV2Test, 
FileScanIoContextDoesNotMarkLoadAsQueryReader) {
     EXPECT_EQ(io_ctx->remote_scan_cache_write_limiter, nullptr);
 }
 
+// Both scanner generations use this helper, so query options must survive 
FE/BE version skew.
+TEST(FileScannerV2Test, FileScanIoContextUsesExplicitQueryAdaptorOption) {
+    MockRuntimeState state;
+    state._query_id = make_query_id();
+    state._query_ctx = nullptr;
+    TQueryOptions options;
+    options.__set_query_type(TQueryType::SELECT);
+    state.set_query_options(options);
+    
EXPECT_FALSE(create_file_scan_io_context(&state)->enable_file_cache_io_adaptor);
+
+    options.__set_enable_file_cache_io_adaptor(true);
+    state.set_query_options(options);
+    auto enabled = create_file_scan_io_context(&state);
+    EXPECT_TRUE(enabled->enable_file_cache_io_adaptor);
+
+    options.__set_enable_file_cache_io_adaptor(false);
+    state.set_query_options(options);
+    
EXPECT_FALSE(create_file_scan_io_context(&state)->enable_file_cache_io_adaptor);
+    EXPECT_TRUE(enabled->enable_file_cache_io_adaptor);
+
+    options.__set_query_type(TQueryType::LOAD);
+    options.__set_enable_file_cache_io_adaptor(true);
+    state.set_query_options(options);
+    
EXPECT_FALSE(create_file_scan_io_context(&state)->enable_file_cache_io_adaptor);
+}
+
 // Scenario: FileScannerV2 converts only the file formats implemented by 
format_v2 readers and
 // rejects everything else before TableReader::init sees an unsupported 
FileFormat.
 TEST(FileScannerV2Test, FileFormatConversionMatrix) {
diff --git a/be/test/io/cache/block_file_cache_profile_reporter_test.cpp 
b/be/test/io/cache/block_file_cache_profile_reporter_test.cpp
index 6a31082b95e..62981e033a6 100644
--- a/be/test/io/cache/block_file_cache_profile_reporter_test.cpp
+++ b/be/test/io/cache/block_file_cache_profile_reporter_test.cpp
@@ -54,6 +54,18 @@ io::FileCacheStatistics make_file_cache_stats(int64_t 
multiplier) {
     stats.inverted_index_io_timer = multiplier * 28;
     stats.remote_only_on_miss_triggered = multiplier * 29;
     stats.remote_only_on_miss_threshold_bytes = multiplier * 30;
+    stats.io_adaptor_lookup_count = multiplier * 60;
+    stats.io_adaptor_lookup_time_ns = multiplier * 61;
+    stats.io_adaptor_local_reads = multiplier * 62;
+    stats.io_adaptor_local_time_ns = multiplier * 63;
+    stats.io_adaptor_bypass_count = multiplier * 64;
+    stats.io_adaptor_bypass_bytes = multiplier * 65;
+    stats.io_adaptor_remote_bytes = multiplier * 66;
+    stats.io_adaptor_remote_time_ns = multiplier * 67;
+    stats.io_adaptor_local_probes = multiplier * 68;
+    stats.io_adaptor_remote_probes = multiplier * 69;
+    stats.io_adaptor_remote_failures = multiplier * 70;
+    stats.io_adaptor_fallback_local = multiplier * 71;
     stats.async_cache_write_submitted = multiplier * 45;
     stats.async_cache_write_rejected = multiplier * 46;
     stats.async_cache_write_buffer_alloc_fail = multiplier * 47;
@@ -84,6 +96,18 @@ io::FileCacheStatistics make_file_cache_stats(int64_t 
multiplier) {
 
 void expect_file_cache_stats_eq(const io::FileCacheStatistics& actual,
                                 const io::FileCacheStatistics& expected) {
+    EXPECT_EQ(actual.io_adaptor_lookup_count, 
expected.io_adaptor_lookup_count);
+    EXPECT_EQ(actual.io_adaptor_lookup_time_ns, 
expected.io_adaptor_lookup_time_ns);
+    EXPECT_EQ(actual.io_adaptor_local_reads, expected.io_adaptor_local_reads);
+    EXPECT_EQ(actual.io_adaptor_local_time_ns, 
expected.io_adaptor_local_time_ns);
+    EXPECT_EQ(actual.io_adaptor_bypass_count, 
expected.io_adaptor_bypass_count);
+    EXPECT_EQ(actual.io_adaptor_bypass_bytes, 
expected.io_adaptor_bypass_bytes);
+    EXPECT_EQ(actual.io_adaptor_remote_bytes, 
expected.io_adaptor_remote_bytes);
+    EXPECT_EQ(actual.io_adaptor_remote_time_ns, 
expected.io_adaptor_remote_time_ns);
+    EXPECT_EQ(actual.io_adaptor_local_probes, 
expected.io_adaptor_local_probes);
+    EXPECT_EQ(actual.io_adaptor_remote_probes, 
expected.io_adaptor_remote_probes);
+    EXPECT_EQ(actual.io_adaptor_remote_failures, 
expected.io_adaptor_remote_failures);
+    EXPECT_EQ(actual.io_adaptor_fallback_local, 
expected.io_adaptor_fallback_local);
     EXPECT_EQ(actual.num_local_io_total, expected.num_local_io_total);
     EXPECT_EQ(actual.num_remote_io_total, expected.num_remote_io_total);
     EXPECT_EQ(actual.num_peer_io_total, expected.num_peer_io_total);
@@ -193,6 +217,30 @@ TEST(FileCacheProfileReporterTest, 
ReporterAggregatesDeltaReportsToExactFinalTot
             io::diff_file_cache_statistics(after_second_report, 
after_first_report);
     reporter.update(&second_delta);
 
+    EXPECT_EQ(profile->get_counter("IOAdaptorLookupCount")->value(),
+              after_second_report.io_adaptor_lookup_count);
+    EXPECT_EQ(profile->get_counter("IOAdaptorLookupTime")->value(),
+              after_second_report.io_adaptor_lookup_time_ns);
+    EXPECT_EQ(profile->get_counter("IOAdaptorLocalReadCount")->value(),
+              after_second_report.io_adaptor_local_reads);
+    EXPECT_EQ(profile->get_counter("IOAdaptorLocalReadTime")->value(),
+              after_second_report.io_adaptor_local_time_ns);
+    EXPECT_EQ(profile->get_counter("IOAdaptorBypassCount")->value(),
+              after_second_report.io_adaptor_bypass_count);
+    EXPECT_EQ(profile->get_counter("IOAdaptorBypassBytes")->value(),
+              after_second_report.io_adaptor_bypass_bytes);
+    EXPECT_EQ(profile->get_counter("IOAdaptorRemoteReadBytes")->value(),
+              after_second_report.io_adaptor_remote_bytes);
+    EXPECT_EQ(profile->get_counter("IOAdaptorRemoteReadTime")->value(),
+              after_second_report.io_adaptor_remote_time_ns);
+    EXPECT_EQ(profile->get_counter("IOAdaptorLocalProbeCount")->value(),
+              after_second_report.io_adaptor_local_probes);
+    EXPECT_EQ(profile->get_counter("IOAdaptorRemoteProbeCount")->value(),
+              after_second_report.io_adaptor_remote_probes);
+    EXPECT_EQ(profile->get_counter("IOAdaptorRemoteFailureCount")->value(),
+              after_second_report.io_adaptor_remote_failures);
+    EXPECT_EQ(profile->get_counter("IOAdaptorFallbackLocalCount")->value(),
+              after_second_report.io_adaptor_fallback_local);
     EXPECT_EQ(profile->get_counter("BytesScannedFromCache")->value(),
               after_second_report.bytes_read_from_local);
     EXPECT_EQ(profile->get_counter("BytesScannedFromRemote")->value(),
diff --git a/be/test/io/cache/cached_remote_file_reader_test.cpp 
b/be/test/io/cache/cached_remote_file_reader_test.cpp
index 6fe9bac5d60..21fa28327d1 100644
--- a/be/test/io/cache/cached_remote_file_reader_test.cpp
+++ b/be/test/io/cache/cached_remote_file_reader_test.cpp
@@ -15,13 +15,21 @@
 // specific language governing permissions and limitations
 // under the License.
 
+#include <algorithm>
+#include <array>
+#include <chrono>
 #include <cstring>
 #include <future>
+#include <iostream>
+#include <thread>
 
 #include "block_file_cache_test_common.h"
 #include "cloud/config.h"
 #include "io/cache/async_cache_write_manager_metrics.h"
+#include "io/cache/file_cache_io_adaptor.h"
 #include "io/cache/inflight_write_buffer_index.h"
+#include "io/cache/remote_scan_cache_write_limiter.h"
+#include "io/fs/hdfs_file_reader.h"
 #include "util/time.h"
 
 namespace doris::io {
@@ -57,6 +65,10 @@ public:
     bool closed() const override { return _delegate->closed(); }
     int64_t mtime() const override { return _delegate->mtime(); }
 
+    int64_t delay_us = 0;
+    bool fail_reads = false;
+    bool cancel_reads = false;
+    size_t short_read_size = 0;
     size_t read_count() const { return _read_count; }
     size_t last_offset() const { return _last_offset; }
     size_t last_size() const { return _last_size; }
@@ -69,6 +81,18 @@ protected:
         _last_offset = offset;
         _last_size = result.size;
         _last_bypass_peer_read = io_ctx != nullptr && io_ctx->bypass_peer_read;
+        if (delay_us > 0) {
+            std::this_thread::sleep_for(std::chrono::microseconds(delay_us));
+        }
+        if (cancel_reads) {
+            return Status::Cancelled("Injected remote cancellation");
+        }
+        if (fail_reads) {
+            return Status::IOError("Injected remote read failure");
+        }
+        if (short_read_size != 0) {
+            result = Slice(result.data, std::min(result.size, 
short_read_size));
+        }
         return _delegate->read_at(offset, result, bytes_read, io_ctx);
     }
 
@@ -80,7 +104,7 @@ private:
     bool _last_bypass_peer_read {false};
 };
 
-// Provides one isolated cache disk with phase-one async-read settings for 
concise end-to-end
+// Provides isolated cache paths with phase-one async-read settings for 
concise end-to-end
 // reader tests. Every test gets a fresh FileCacheFactory entry and restores 
global knobs afterward.
 class AsyncCachedRemoteFileReaderTest : public BlockFileCacheTest {
 protected:
@@ -106,9 +130,10 @@ protected:
 
     void TearDown() override {
         reset_async_reader_cache_factory();
-        if (!_cache_path.empty()) {
+        // Stop every cache's background workers before removing any path used 
by this test.
+        for (const auto& path : _cache_paths) {
             std::error_code error;
-            fs::remove_all(_cache_path, error);
+            fs::remove_all(path, error);
         }
         config::enable_async_file_cache_write = _old_enable_async;
         config::enable_async_file_cache_write_inflight_write_buffer_index = 
_old_enable_inflight;
@@ -118,14 +143,16 @@ protected:
         config::block_cache_wait_timeout_ms = _old_wait_timeout_ms;
     }
 
-    // Create and initialize the single cache disk used by the current test.
-    void create_cache(std::string_view name) {
+    // Create, initialize and select a cache path used by the current test.
+    void create_cache(std::string_view name,
+                      const FileCacheSettings& settings = 
async_reader_cache_settings()) {
         _cache_path = caches_dir / name;
+        _cache_paths.push_back(_cache_path);
         std::error_code error;
         fs::remove_all(_cache_path, error);
         fs::create_directories(_cache_path);
         ASSERT_TRUE(FileCacheFactory::instance()
-                            ->create_file_cache(_cache_path.string(), 
async_reader_cache_settings())
+                            ->create_file_cache(_cache_path.string(), settings)
                             .ok());
         _cache = 
FileCacheFactory::instance()->_path_to_cache[_cache_path.string()];
         ASSERT_NE(_cache, nullptr);
@@ -167,6 +194,7 @@ protected:
 
 private:
     fs::path _cache_path;
+    std::vector<fs::path> _cache_paths;
     BlockFileCache* _cache = nullptr;
     bool _old_enable_async = false;
     bool _old_enable_inflight = false;
@@ -1661,4 +1689,835 @@ TEST_F(BlockFileCacheTest, 
cache_write_mode_is_resolved_for_each_read_context) {
     EXPECT_EQ(sync_reader->_resolve_cache_write_mode(&context), 
CacheWriteMode::ASYNC_WRITE);
 }
 
+// All-hit adaptation is shared by sync/async readers. Cold and mixed requests 
retain their
+// original downloader/inflight/writeback semantics rather than pretending a 
cache hit is EMPTY.
+class AdaptiveCachedRemoteFileReaderTest : public 
AsyncCachedRemoteFileReaderTest {
+protected:
+    void reset_adaptor() {
+        auto& adaptor = cache()->io_adaptor();
+        std::lock_guard lock(adaptor._mutex);
+        adaptor._buckets = {};
+        adaptor._requests_since_probe = 0;
+        adaptor._next_probe_bucket = 0;
+        adaptor._next_probe_us = 0;
+        adaptor._probe_inflight = false;
+    }
+    std::shared_ptr<CachedRemoteFileReader> external_reader(FileReaderSPtr 
remote) {
+        FileReaderOptions options;
+        options.cache_type = FileCachePolicy::FILE_BLOCK_CACHE;
+        options.cache_base_path = cache()->get_base_path();
+        return std::make_shared<CachedRemoteFileReader>(std::move(remote), 
options);
+    }
+    void seed_slow_disk() {
+        auto& adaptor = cache()->io_adaptor();
+        for (size_t bucket = 0; bucket < FileCacheIOAdaptor::BUCKET_COUNT; 
++bucket) {
+            const size_t bytes = size_t(4096) << (bucket * 2);
+            for (int i = 0; i < 50; ++i) {
+                adaptor.record_local(bytes, 20000);
+                adaptor.record_remote(bytes, 1000);
+            }
+        }
+    }
+    void verify_inflight_hit_without_disk(const 
std::shared_ptr<CachedRemoteFileReader>& reader,
+                                          const 
std::shared_ptr<CountingFileReader>& remote,
+                                          IOContext context, const 
std::string& expected) {
+        FileCacheStatistics stats;
+        context.enable_file_cache_io_adaptor = true;
+        context.file_cache_stats = &stats;
+        std::string actual(expected.size(), '\xff');
+        size_t count = 0;
+        std::future<Status> read;
+        {
+            // A complete memory hit must finish even while unrelated disk 
work holds this lock.
+            std::lock_guard cache_lock(cache()->_mutex);
+            read = std::async(std::launch::async, [&] {
+                
SCOPED_ATTACH_TASK(ExecEnv::GetInstance()->orphan_mem_tracker());
+                return reader->read_at(0, Slice(actual), &count, &context);
+            });
+            EXPECT_EQ(read.wait_for(std::chrono::seconds(2)), 
std::future_status::ready);
+        }
+        ASSERT_TRUE(read.get().ok());
+        EXPECT_EQ(actual, expected);
+        EXPECT_EQ(count, actual.size());
+        EXPECT_EQ(remote->read_count(), 0);
+        EXPECT_EQ(stats.io_adaptor_bypass_count, 0);
+        EXPECT_EQ(stats.io_adaptor_lookup_count, 0);
+        EXPECT_EQ(stats.inflight_write_buffer_index_hit, 1);
+        EXPECT_EQ(stats.async_cache_write_submitted, 0);
+    }
+    void verify_remote_probe_cleanup(int failure) {
+        create_cache("adaptive_probe_cleanup");
+        auto seed = external_reader(open_remote_file());
+        std::string expected(4096, '\0');
+        size_t count = 0;
+        IOContext context;
+        context.cache_write_mode_override = CacheWriteMode::SYNC_WRITE;
+        ASSERT_TRUE(seed->read_at(0, Slice(expected), &count, &context).ok());
+        context.enable_file_cache_io_adaptor = true;
+        reset_adaptor();
+        auto& adaptor = cache()->io_adaptor();
+        // Keep local preferred but above the floor so these failure exits own 
a probe permit.
+        for (int i = 0; i < 50; ++i) {
+            adaptor.record_local(expected.size(), 6000);
+            adaptor.record_remote(expected.size(), 10000);
+        }
+        adaptor._requests_since_probe = 63;
+        auto remote = std::make_shared<CountingFileReader>(open_remote_file());
+        remote->fail_reads = failure == 0;
+        remote->short_read_size = failure == 1 ? 17 : 0;
+        remote->cancel_reads = failure == 2;
+        auto reader = external_reader(remote);
+        std::string actual(expected.size(), '\xff');
+        const auto status = reader->read_at(0, Slice(actual), &count, 
&context);
+        EXPECT_EQ(remote->read_count(), 1);
+        // Admission consumes the quota even on cancellation before statistics 
are merged.
+        EXPECT_EQ(adaptor._requests_since_probe, 0);
+        EXPECT_FALSE(adaptor._probe_inflight);
+        EXPECT_EQ(reader->_io_adaptor_remote_failed.load(), failure != 2);
+        if (failure == 2) {
+            EXPECT_TRUE(status.is<ErrorCode::CANCELLED>());
+        } else {
+            ASSERT_TRUE(status.ok());
+            EXPECT_EQ(actual, expected);
+            EXPECT_EQ(count, expected.size());
+        }
+    }
+    void warm_adaptor_with_real_reads(const 
std::shared_ptr<CachedRemoteFileReader>& reader,
+                                      const 
std::shared_ptr<CountingFileReader>& remote,
+                                      size_t bytes) {
+        // Each benchmark group starts with measured service times in the 
shared controller.
+        // Calibration is excluded from the timed steady-state phase in both 
configurations.
+        reset_adaptor();
+        IOContext context;
+        context.cache_write_mode_override = CacheWriteMode::SYNC_WRITE;
+        context.enable_file_cache_io_adaptor = true;
+        std::string buffer(bytes, '\0');
+        size_t count = 0;
+        for (int sample = 0; sample < 50; ++sample) {
+            const auto start = MonotonicNanos();
+            ASSERT_TRUE(remote->read_at(0, Slice(buffer), &count, 
&context).ok());
+            ASSERT_EQ(count, bytes);
+            cache()->io_adaptor().record_remote(bytes, (MonotonicNanos() - 
start) / 1000);
+        }
+        for (int sample = 0; sample < 50; ++sample) {
+            ASSERT_TRUE(reader->read_at(0, Slice(buffer), &count, 
&context).ok());
+            ASSERT_EQ(count, bytes);
+        }
+    }
+};
+
+TEST_F(AdaptiveCachedRemoteFileReaderTest, 
remote_calls_are_sampled_individually_at_actual_sizes) {
+    create_cache("adaptive_remote_call_samples");
+    auto remote = std::make_shared<CountingFileReader>(open_remote_file());
+    auto reader = external_reader(remote);
+    IOContext context;
+    context.enable_file_cache_io_adaptor = true;
+    ReadStatistics stats;
+    std::string small(4096, '\0');
+    std::string large(1_mb, '\0');
+    size_t count = 0;
+    ASSERT_TRUE(reader->_read_remote_at(0, Slice(small), &count, &context, 
stats).ok());
+    ASSERT_TRUE(reader->_read_remote_at(1_mb, Slice(large), &count, &context, 
stats).ok());
+    ASSERT_TRUE(reader->_read_remote_at(2_mb, Slice(small), &count, &context, 
stats).ok());
+    auto& adaptor = cache()->io_adaptor();
+    
EXPECT_EQ(adaptor._buckets[FileCacheIOAdaptor::bucket_index(small.size())].remote.count,
 2);
+    
EXPECT_EQ(adaptor._buckets[FileCacheIOAdaptor::bucket_index(large.size())].remote.count,
 1);
+    EXPECT_EQ(remote->read_count(), 3);
+    EXPECT_EQ(stats.remote_physical_read_bytes, large.size() + 2 * 
small.size());
+    EXPECT_EQ(stats.local_write_timer, 0);
+    EXPECT_EQ(stats.bytes_write_into_file_cache, 0);
+}
+
+TEST_F(AdaptiveCachedRemoteFileReaderTest, 
failed_remote_probe_releases_permit) {
+    verify_remote_probe_cleanup(0);
+}
+
+TEST_F(AdaptiveCachedRemoteFileReaderTest, short_remote_probe_releases_permit) 
{
+    verify_remote_probe_cleanup(1);
+}
+
+TEST_F(AdaptiveCachedRemoteFileReaderTest, 
cancelled_remote_probe_releases_permit) {
+    verify_remote_probe_cleanup(2);
+}
+
+TEST_F(AdaptiveCachedRemoteFileReaderTest, 
congested_path_does_not_bypass_healthy_path) {
+    create_cache("adaptive_healthy_path");
+    auto remote = std::make_shared<CountingFileReader>(open_remote_file());
+    auto healthy = external_reader(remote);
+    std::string buffer(4096, '\0');
+    size_t count = 0;
+    IOContext context;
+    context.cache_write_mode_override = CacheWriteMode::SYNC_WRITE;
+    ASSERT_TRUE(healthy->read_at(0, Slice(buffer), &count, &context).ok());
+    create_cache("adaptive_congested_path");
+    seed_slow_disk();
+    context.enable_file_cache_io_adaptor = true;
+    const auto previous_reads = remote->read_count();
+    ASSERT_TRUE(healthy->read_at(0, Slice(buffer), &count, &context).ok());
+    EXPECT_EQ(remote->read_count(), previous_reads);
+}
+
+TEST_F(AdaptiveCachedRemoteFileReaderTest, 
recovery_without_fast_history_uses_real_local_reads) {
+    create_cache("adaptive_recovery_probe");
+    auto remote = std::make_shared<CountingFileReader>(open_remote_file());
+    auto reader = external_reader(remote);
+    std::string expected(4096, '\0');
+    size_t count = 0;
+    IOContext context;
+    context.cache_write_mode_override = CacheWriteMode::SYNC_WRITE;
+    ASSERT_TRUE(reader->read_at(0, Slice(expected), &count, &context).ok());
+    seed_slow_disk();
+    int64_t now_us = 0;
+    auto* sync = SyncPoint::get_instance();
+    sync->set_call_back("FileCacheIOAdaptor::select:now_us", [&](auto&& 
values) {
+        now_us += 2'000'000;
+        *try_any_cast<int64_t*>(values.back()) = now_us;
+    });
+    sync->enable_processing();
+    Defer cleanup {[&] {
+        sync->disable_processing();
+        sync->clear_all_call_backs();
+    }};
+    FileCacheStatistics stats;
+    context.file_cache_stats = &stats;
+    context.enable_file_cache_io_adaptor = true;
+    std::string actual(expected.size(), '\0');
+    for (int i = 0; i < 4096; ++i) {
+        ASSERT_TRUE(reader->read_at(0, Slice(actual), &count, &context).ok());
+        ASSERT_EQ(actual, expected);
+    }
+    EXPECT_GT(stats.io_adaptor_bypass_count, 0);
+    EXPECT_GT(stats.io_adaptor_local_reads, 50);
+}
+
+TEST_F(AdaptiveCachedRemoteFileReaderTest, 
hdfs_full_hits_never_attempt_optional_remote_reads) {
+    create_cache("adaptive_hdfs");
+    auto source = open_remote_file();
+    auto seed = external_reader(source);
+    std::string expected(4096, '\0');
+    size_t count = 0;
+    IOContext context;
+    context.cache_write_mode_override = CacheWriteMode::SYNC_WRITE;
+    ASSERT_TRUE(seed->read_at(0, Slice(expected), &count, &context).ok());
+
+    // Known-size handles need no live HDFS connection. A bypass would try to 
open this handle;
+    // excluding it must preserve both the cached bytes and its metadata for 
subsequent ranges.
+    FileHandleCache handles(8, 1, 0);
+    FileHandleCache::Accessor accessor;
+    bool cache_hit = false;
+    ASSERT_TRUE(handles.get_file_handle(nullptr, source->path().native(), 0, 
source->size(), false,
+                                        &accessor, &cache_hit)
+                        .ok());
+    auto hdfs = std::make_shared<HdfsFileReader>(source->path(), "", 
std::move(accessor));
+    auto reader = external_reader(hdfs);
+    seed_slow_disk();
+    context.enable_file_cache_io_adaptor = true;
+    ASSERT_FALSE(reader->_io_adaptor_eligible(expected.size(), &context));
+    for (int attempt = 0; attempt < 2; ++attempt) {
+        std::string actual(expected.size(), '\0');
+        ASSERT_TRUE(reader->read_at(0, Slice(actual), &count, &context).ok());
+        EXPECT_EQ(actual, expected);
+        EXPECT_EQ(count, actual.size());
+        ASSERT_NE(hdfs->_handle, nullptr);
+        EXPECT_EQ(hdfs->size(), source->size());
+        EXPECT_EQ(hdfs->_handle->file(), nullptr);
+    }
+}
+
+TEST_F(AdaptiveCachedRemoteFileReaderTest, 
local_full_hits_update_disk_cache_metrics_once) {
+    create_cache("adaptive_hit_metrics");
+    auto remote = std::make_shared<CountingFileReader>(open_remote_file());
+    auto reader = external_reader(remote);
+    std::string buffer(4096, '\0');
+    size_t count = 0;
+    IOContext context;
+    context.cache_write_mode_override = CacheWriteMode::SYNC_WRITE;
+    ASSERT_TRUE(reader->read_at(0, Slice(buffer), &count, &context).ok());
+    const auto reads = cache()->_num_read_blocks->get_value();
+    const auto hits = cache()->_num_hit_blocks->get_value();
+    const auto read_bytes = cache()->_total_read_size_metrics->get_value();
+    const auto hit_bytes = cache()->_total_hit_size_metrics->get_value();
+    const auto no_warmup_reads = 
cache()->_no_warmup_num_read_blocks->get_value();
+    const auto no_warmup_hits = 
cache()->_no_warmup_num_hit_blocks->get_value();
+    context.enable_file_cache_io_adaptor = true;
+    for (auto mode : {CacheWriteMode::SYNC_WRITE, 
CacheWriteMode::ASYNC_WRITE}) {
+        context.cache_write_mode_override = mode;
+        ASSERT_TRUE(reader->read_at(0, Slice(buffer), &count, &context).ok());
+    }
+    EXPECT_EQ(cache()->_num_read_blocks->get_value(), reads + 2);
+    EXPECT_EQ(cache()->_num_hit_blocks->get_value(), hits + 2);
+    EXPECT_EQ(cache()->_total_read_size_metrics->get_value(), read_bytes + 2 * 
1_mb);
+    EXPECT_EQ(cache()->_total_hit_size_metrics->get_value(), hit_bytes + 2 * 
1_mb);
+    EXPECT_EQ(cache()->_no_warmup_num_read_blocks->get_value(), 
no_warmup_reads + 2);
+    EXPECT_EQ(cache()->_no_warmup_num_hit_blocks->get_value(), no_warmup_hits 
+ 2);
+    EXPECT_EQ(remote->read_count(), 1);
+
+    seed_slow_disk();
+    ASSERT_TRUE(reader->read_at(0, Slice(buffer), &count, &context).ok());
+    EXPECT_EQ(cache()->_num_read_blocks->get_value(), reads + 2);
+    EXPECT_EQ(cache()->_num_hit_blocks->get_value(), hits + 2);
+    EXPECT_EQ(remote->read_count(), 2);
+
+    // An incomplete adaptor lookup falls through to get_or_set, which owns 
miss accounting.
+    context.cache_write_mode_override = CacheWriteMode::SYNC_WRITE;
+    ASSERT_TRUE(reader->read_at(1_mb, Slice(buffer), &count, &context).ok());
+    EXPECT_EQ(cache()->_num_read_blocks->get_value(), reads + 3);
+    EXPECT_EQ(cache()->_num_hit_blocks->get_value(), hits + 2);
+    EXPECT_EQ(remote->read_count(), 3);
+}
+
+TEST_F(AdaptiveCachedRemoteFileReaderTest, 
full_hit_bypass_preserves_cache_in_both_write_modes) {
+    create_cache("adaptive_full_hit");
+    auto remote = std::make_shared<CountingFileReader>(open_remote_file());
+    auto reader = external_reader(remote);
+    std::string expected(64 * 1024, '\0');
+    size_t count = 0;
+    IOContext context;
+    context.cache_write_mode_override = CacheWriteMode::SYNC_WRITE;
+    ASSERT_TRUE(reader->read_at(17, Slice(expected), &count, &context).ok());
+    ASSERT_EQ(count, expected.size());
+    seed_slow_disk();
+    context.enable_file_cache_io_adaptor = true;
+    const auto cached_blocks = 
cache()->get_blocks_by_key(reader->_cache_hash).size();
+    for (auto mode : {CacheWriteMode::SYNC_WRITE, 
CacheWriteMode::ASYNC_WRITE}) {
+        FileCacheStatistics stats;
+        context.file_cache_stats = &stats;
+        context.cache_write_mode_override = mode;
+        const auto previous_reads = remote->read_count();
+        std::string actual(expected.size(), '\0');
+        ASSERT_TRUE(reader->read_at(17, Slice(actual), &count, &context).ok());
+        EXPECT_EQ(actual, expected);
+        EXPECT_EQ(remote->read_count(), previous_reads + 1);
+        EXPECT_EQ(remote->last_offset(), 17);
+        EXPECT_EQ(remote->last_size(), actual.size());
+        EXPECT_EQ(stats.io_adaptor_bypass_count, 1);
+        EXPECT_EQ(stats.io_adaptor_bypass_bytes, actual.size());
+        EXPECT_EQ(stats.io_adaptor_remote_bytes, actual.size());
+        EXPECT_EQ(stats.bytes_read_from_remote, actual.size());
+        EXPECT_EQ(stats.bytes_write_into_cache, 0);
+        EXPECT_EQ(stats.async_cache_write_submitted, 0);
+        EXPECT_EQ(cache()->get_blocks_by_key(reader->_cache_hash).size(), 
cached_blocks);
+    }
+}
+
+TEST_F(AdaptiveCachedRemoteFileReaderTest, 
cross_block_and_eof_ranges_match_on_both_routes) {
+    create_cache("adaptive_read_ranges");
+    auto remote = std::make_shared<CountingFileReader>(open_remote_file());
+    auto reader = external_reader(remote);
+    for (size_t offset : {size_t(1_mb - 17), reader->size() - 31}) {
+        reset_adaptor();
+        IOContext context;
+        context.cache_write_mode_override = CacheWriteMode::SYNC_WRITE;
+        std::string expected(64 * 1024, '\0');
+        size_t count = 0;
+        ASSERT_TRUE(reader->read_at(offset, Slice(expected), &count, 
&context).ok());
+        expected.resize(count);
+        context.enable_file_cache_io_adaptor = true;
+        for (bool bypass : {false, true}) {
+            if (bypass) {
+                seed_slow_disk();
+            }
+            const auto previous_reads = remote->read_count();
+            FileCacheStatistics stats;
+            context.file_cache_stats = &stats;
+            std::string actual(64 * 1024, '\xff');
+            ASSERT_TRUE(reader->read_at(offset, Slice(actual), &count, 
&context).ok());
+            EXPECT_EQ(count, expected.size());
+            EXPECT_EQ(actual.substr(0, count), expected);
+            EXPECT_EQ(actual.substr(count), std::string(actual.size() - count, 
'\xff'));
+            EXPECT_EQ(remote->read_count(), previous_reads + size_t(bypass));
+            EXPECT_EQ(stats.io_adaptor_bypass_count, int64_t(bypass));
+            EXPECT_EQ(stats.io_adaptor_local_reads, int64_t(!bypass));
+            EXPECT_EQ(stats.bytes_write_into_cache, 0);
+        }
+    }
+}
+
+TEST_F(AdaptiveCachedRemoteFileReaderTest, 
disabled_and_metadata_reads_preserve_local_path) {
+    create_cache("adaptive_disabled");
+    auto remote = std::make_shared<CountingFileReader>(open_remote_file());
+    auto reader = external_reader(remote);
+    std::string buffer(64 * 1024, '\0');
+    size_t count = 0;
+    IOContext context;
+    context.cache_write_mode_override = CacheWriteMode::SYNC_WRITE;
+    ASSERT_TRUE(reader->read_at(0, Slice(buffer), &count, &context).ok());
+    seed_slow_disk();
+    const auto previous_reads = remote->read_count();
+    ASSERT_TRUE(reader->read_at(0, Slice(buffer), &count, &context).ok());
+    EXPECT_EQ(remote->read_count(), previous_reads);
+    context.enable_file_cache_io_adaptor = true;
+    context.is_index_data = true;
+    EXPECT_FALSE(reader->_io_adaptor_eligible(buffer.size(), &context));
+    ASSERT_TRUE(reader->read_at(0, Slice(buffer), &count, &context).ok());
+    EXPECT_EQ(remote->read_count(), previous_reads);
+    context.is_index_data = false;
+    context.is_warmup = true;
+    EXPECT_FALSE(reader->_io_adaptor_eligible(buffer.size(), &context));
+    context.is_warmup = false;
+    context.is_dryrun = true;
+    EXPECT_FALSE(reader->_io_adaptor_eligible(buffer.size(), &context));
+    context.is_dryrun = false;
+    context.should_stop = true;
+    EXPECT_FALSE(reader->_io_adaptor_eligible(buffer.size(), &context));
+    context.should_stop = false;
+    context.read_file_cache = false;
+    EXPECT_FALSE(reader->_io_adaptor_eligible(buffer.size(), &context));
+    context.read_file_cache = true;
+    context.is_inverted_index = true;
+    EXPECT_FALSE(reader->_io_adaptor_eligible(buffer.size(), &context));
+    context.is_inverted_index = false;
+    EXPECT_FALSE(reader->_io_adaptor_eligible(0, &context));
+}
+
+TEST_F(AdaptiveCachedRemoteFileReaderTest, 
query_override_does_not_change_other_readers) {
+    create_cache("adaptive_query_override");
+    auto remote = std::make_shared<CountingFileReader>(open_remote_file());
+    auto reader = external_reader(remote);
+    std::string buffer(64 * 1024, '\0');
+    size_t count = 0;
+    IOContext enabled;
+    enabled.cache_write_mode_override = CacheWriteMode::SYNC_WRITE;
+    ASSERT_TRUE(reader->read_at(0, Slice(buffer), &count, &enabled).ok());
+    seed_slow_disk();
+    enabled.enable_file_cache_io_adaptor = true;
+    IOContext disabled;
+    disabled.cache_write_mode_override = CacheWriteMode::SYNC_WRITE;
+    const auto before = remote->read_count();
+    ASSERT_TRUE(reader->read_at(0, Slice(buffer), &count, &enabled).ok());
+    EXPECT_EQ(remote->read_count(), before + 1);
+    ASSERT_TRUE(reader->read_at(0, Slice(buffer), &count, &disabled).ok());
+    EXPECT_EQ(remote->read_count(), before + 1);
+    // An internal-table reader cannot opt into the external-query policy 
accidentally.
+    FileReaderOptions options;
+    options.cache_type = FileCachePolicy::FILE_BLOCK_CACHE;
+    options.is_doris_table = true;
+    // A valid tablet identity is required before reaching the policy 
exclusion check.
+    options.tablet_id = 1;
+    auto internal = std::make_shared<CachedRemoteFileReader>(remote, options);
+    EXPECT_FALSE(internal->_io_adaptor_eligible(buffer.size(), &enabled));
+}
+
+TEST_F(AdaptiveCachedRemoteFileReaderTest, 
real_remote_misses_train_only_enabled_queries) {
+    create_cache("adaptive_remote_history");
+    auto remote = std::make_shared<CountingFileReader>(open_remote_file());
+    auto reader = external_reader(remote);
+    std::string buffer(64 * 1024, '\0');
+    size_t count = 0;
+    IOContext context;
+    context.cache_write_mode_override = CacheWriteMode::SYNC_WRITE;
+    auto& adaptor = cache()->io_adaptor();
+    ASSERT_TRUE(reader->read_at(0, Slice(buffer), &count, &context).ok());
+    
EXPECT_EQ(adaptor._buckets[FileCacheIOAdaptor::bucket_index(1_mb)].remote.count,
 0);
+    context.enable_file_cache_io_adaptor = true;
+    size_t offset = 0;
+    for (auto mode : {CacheWriteMode::SYNC_WRITE, 
CacheWriteMode::ASYNC_WRITE}) {
+        offset += 1_mb;
+        reset_adaptor();
+        context.cache_write_mode_override = mode;
+        ASSERT_TRUE(reader->read_at(offset, Slice(buffer), &count, 
&context).ok());
+        
EXPECT_EQ(adaptor._buckets[FileCacheIOAdaptor::bucket_index(1_mb)].remote.count,
 1);
+        
EXPECT_EQ(adaptor._buckets[FileCacheIOAdaptor::bucket_index(buffer.size())].local.count,
 0);
+        wait_for_async_writes();
+        const auto reads = remote->read_count();
+        ASSERT_TRUE(reader->read_at(offset, Slice(buffer), &count, 
&context).ok());
+        EXPECT_EQ(remote->read_count(), reads);
+        
EXPECT_EQ(adaptor._buckets[FileCacheIOAdaptor::bucket_index(1_mb)].remote.count,
 1);
+        
EXPECT_EQ(adaptor._buckets[FileCacheIOAdaptor::bucket_index(buffer.size())].local.count,
 1);
+    }
+}
+
+TEST_F(AdaptiveCachedRemoteFileReaderTest,
+       remote_failure_disables_only_optional_reads_on_that_reader) {
+    create_cache("adaptive_remote_failure");
+    auto seed_reader = external_reader(open_remote_file());
+    std::string expected(64 * 1024, '\0');
+    size_t count = 0;
+    IOContext context;
+    context.cache_write_mode_override = CacheWriteMode::SYNC_WRITE;
+    ASSERT_TRUE(seed_reader->read_at(7, Slice(expected), &count, 
&context).ok());
+    context.enable_file_cache_io_adaptor = true;
+    for (bool short_read : {false, true}) {
+        auto remote = std::make_shared<CountingFileReader>(open_remote_file());
+        reset_adaptor();
+        seed_slow_disk();
+        auto reader = external_reader(remote);
+        FileCacheStatistics stats;
+        context.file_cache_stats = &stats;
+        remote->short_read_size = short_read ? 7 : 0;
+        remote->fail_reads = !short_read;
+        std::string actual(expected.size(), '\xff');
+        const auto previous_reads = remote->read_count();
+        ASSERT_TRUE(reader->read_at(7, Slice(actual), &count, &context).ok());
+        EXPECT_EQ(actual, expected);
+        EXPECT_EQ(count, expected.size());
+        EXPECT_EQ(remote->read_count(), previous_reads + 1);
+        EXPECT_EQ(stats.io_adaptor_fallback_local, 1);
+        EXPECT_EQ(stats.io_adaptor_remote_bytes, short_read ? 7 : 0);
+        EXPECT_EQ(stats.bytes_read_from_local, expected.size());
+        EXPECT_EQ(stats.bytes_write_into_cache, 0);
+        EXPECT_EQ(stats.io_adaptor_remote_failures, 1);
+        for (auto mode : {CacheWriteMode::SYNC_WRITE, 
CacheWriteMode::ASYNC_WRITE}) {
+            context.cache_write_mode_override = mode;
+            ASSERT_TRUE(reader->read_at(7, Slice(actual), &count, 
&context).ok());
+            EXPECT_EQ(actual, expected);
+            EXPECT_EQ(remote->read_count(), previous_reads + 1);
+        }
+        EXPECT_EQ(stats.io_adaptor_fallback_local, 1);
+        EXPECT_EQ(stats.io_adaptor_remote_failures, 1);
+        // Optional bypass failures must not suppress the remote reads needed 
for cold ranges.
+        context.cache_write_mode_override = CacheWriteMode::SYNC_WRITE;
+        remote->short_read_size = 0;
+        remote->fail_reads = false;
+        ASSERT_TRUE(
+                reader->read_at(short_read ? 2_mb : 1_mb, Slice(actual), 
&count, &context).ok());
+        EXPECT_EQ(remote->read_count(), previous_reads + 2);
+        EXPECT_EQ(actual, std::string(actual.size(), short_read ? '2' : '1'));
+        // File-specific errors do not poison the shared controller or a fresh 
reader.
+        auto healthy = external_reader(remote);
+        ASSERT_TRUE(healthy->read_at(7, Slice(actual), &count, &context).ok());
+        EXPECT_EQ(remote->read_count(), previous_reads + 3);
+        EXPECT_EQ(actual, expected);
+    }
+}
+
+TEST_F(AdaptiveCachedRemoteFileReaderTest, 
full_hits_keep_hot_blocks_recent_with_async_lru_touch) {
+    const auto old_async_touch = 
config::enable_file_cache_async_touch_on_get_or_set;
+    const auto old_qps = 
config::file_cache_background_block_lru_update_qps_limit;
+    config::enable_file_cache_async_touch_on_get_or_set = true;
+    // Drain explicitly so eviction order does not depend on a 
background-thread wakeup.
+    config::file_cache_background_block_lru_update_qps_limit = 0;
+    Defer restore_config {[&] {
+        config::enable_file_cache_async_touch_on_get_or_set = old_async_touch;
+        config::file_cache_background_block_lru_update_qps_limit = old_qps;
+    }};
+    auto settings = async_reader_cache_settings();
+    settings.capacity = settings.query_queue_size = 2_mb;
+    settings.index_queue_size = settings.disposable_queue_size = 0;
+    create_cache("adaptive_lru_touch", settings);
+    auto remote = std::make_shared<CountingFileReader>(open_remote_file());
+    auto reader = external_reader(remote);
+    IOContext context;
+    context.cache_write_mode_override = CacheWriteMode::SYNC_WRITE;
+    std::string buffer(1_mb, '\0');
+    size_t count = 0;
+    ASSERT_TRUE(reader->read_at(0, Slice(buffer), &count, &context).ok());
+    ASSERT_TRUE(reader->read_at(1_mb, Slice(buffer), &count, &context).ok());
+    cache()->clear_need_update_lru_blocks();
+    FileCacheStatistics stats;
+    context.file_cache_stats = &stats;
+    context.enable_file_cache_io_adaptor = true;
+    for (auto mode : {CacheWriteMode::SYNC_WRITE, 
CacheWriteMode::ASYNC_WRITE}) {
+        context.cache_write_mode_override = mode;
+        ASSERT_TRUE(reader->read_at(0, Slice(buffer), &count, &context).ok());
+        EXPECT_EQ(buffer, std::string(buffer.size(), '0'));
+    }
+    EXPECT_EQ(stats.io_adaptor_local_reads, 2);
+    EXPECT_EQ(remote->read_count(), 2);
+    std::vector<FileBlockSPtr> touched;
+    ASSERT_EQ(cache()->_need_update_lru_blocks.drain(10, &touched), 1);
+    {
+        std::lock_guard lock(cache()->_mutex);
+        for (auto& block : touched) {
+            cache()->update_block_lru(block, lock);
+        }
+    }
+    // Release the queue's references before checking eviction, so a hot block 
is not pinned.
+    touched.clear();
+    context.cache_write_mode_override = CacheWriteMode::SYNC_WRITE;
+    ASSERT_TRUE(reader->read_at(2_mb, Slice(buffer), &count, &context).ok());
+    const auto blocks = cache()->get_blocks_by_key(reader->_cache_hash);
+    ASSERT_EQ(blocks.size(), 2);
+    EXPECT_TRUE(blocks.contains(0));
+    EXPECT_FALSE(blocks.contains(1_mb));
+    EXPECT_TRUE(blocks.contains(2_mb));
+}
+
+TEST_F(AdaptiveCachedRemoteFileReaderTest, 
cancellation_does_not_fall_back_or_rewrite_cache) {
+    create_cache("adaptive_cancelled");
+    auto remote = std::make_shared<CountingFileReader>(open_remote_file());
+    auto reader = external_reader(remote);
+    std::string buffer(64 * 1024, '\0');
+    size_t count = 0;
+    IOContext context;
+    context.cache_write_mode_override = CacheWriteMode::SYNC_WRITE;
+    ASSERT_TRUE(reader->read_at(0, Slice(buffer), &count, &context).ok());
+    seed_slow_disk();
+    context.enable_file_cache_io_adaptor = true;
+    remote->cancel_reads = true;
+    const auto previous_reads = remote->read_count();
+    auto status = reader->read_at(0, Slice(buffer), &count, &context);
+    EXPECT_TRUE(status.is<ErrorCode::CANCELLED>());
+    EXPECT_EQ(remote->read_count(), previous_reads + 1);
+    // Cancellation is propagated, while a subsequent query can still use the 
intact cache.
+    remote->cancel_reads = false;
+    ASSERT_TRUE(reader->read_at(0, Slice(buffer), &count, &context).ok());
+    EXPECT_EQ(remote->read_count(), previous_reads + 2);
+    context.enable_file_cache_io_adaptor = false;
+    const auto reads_after_cancel = remote->read_count();
+    ASSERT_TRUE(reader->read_at(0, Slice(buffer), &count, &context).ok());
+    EXPECT_EQ(remote->read_count(), reads_after_cancel);
+    EXPECT_EQ(count, buffer.size());
+}
+
+TEST_F(AdaptiveCachedRemoteFileReaderTest, 
mixed_hit_miss_and_eof_keep_existing_async_semantics) {
+    create_cache("adaptive_mixed_range");
+    auto remote = std::make_shared<CountingFileReader>(open_remote_file());
+    auto reader = external_reader(remote);
+    std::string first(1_mb, '\0');
+    size_t count = 0;
+    IOContext context;
+    context.cache_write_mode_override = CacheWriteMode::SYNC_WRITE;
+    ASSERT_TRUE(reader->read_at(0, Slice(first), &count, &context).ok());
+    seed_slow_disk();
+    context.enable_file_cache_io_adaptor = true;
+    context.cache_write_mode_override = CacheWriteMode::ASYNC_WRITE;
+    FileCacheStatistics stats;
+    context.file_cache_stats = &stats;
+    std::string actual(2_mb, '\0');
+    ASSERT_TRUE(reader->read_at(0, Slice(actual), &count, &context).ok());
+    EXPECT_EQ(count, actual.size());
+    EXPECT_EQ(actual.substr(0, first.size()), first);
+    EXPECT_EQ(stats.io_adaptor_bypass_count, 0);
+    EXPECT_GT(stats.async_cache_write_submitted, 0);
+    wait_for_async_writes();
+    ASSERT_TRUE(reader->read_at(reader->size(), Slice(actual), &count, 
&context).ok());
+    EXPECT_EQ(count, 0);
+}
+
+TEST_F(AdaptiveCachedRemoteFileReaderTest, 
missing_cache_file_retries_the_complete_range) {
+    create_cache("adaptive_missing_file");
+    auto remote = std::make_shared<CountingFileReader>(open_remote_file());
+    auto reader = external_reader(remote);
+    std::string expected(64 * 1024, '\0');
+    size_t count = 0;
+    IOContext context;
+    context.cache_write_mode_override = CacheWriteMode::SYNC_WRITE;
+    ASSERT_TRUE(reader->read_at(0, Slice(expected), &count, &context).ok());
+    auto blocks = cache()->get_blocks_by_key(reader->_cache_hash);
+    ASSERT_FALSE(blocks.empty());
+    std::error_code error;
+    ASSERT_TRUE(fs::remove(blocks.begin()->second->get_cache_file(), error));
+    ASSERT_FALSE(error);
+    blocks.clear();
+    context.enable_file_cache_io_adaptor = true;
+    FileCacheStatistics stats;
+    context.file_cache_stats = &stats;
+    const auto previous_reads = remote->read_count();
+    const auto disk_reads = cache()->_num_read_blocks->get_value();
+    std::string actual(expected.size(), '\xff');
+    ASSERT_TRUE(reader->read_at(0, Slice(actual), &count, &context).ok());
+    EXPECT_EQ(actual, expected);
+    EXPECT_EQ(count, actual.size());
+    EXPECT_EQ(remote->read_count(), previous_reads + 1);
+    EXPECT_EQ(stats.io_adaptor_local_reads, 1);
+    EXPECT_GT(stats.io_adaptor_local_time_ns, 0);
+    EXPECT_EQ(stats.io_adaptor_bypass_count, 0);
+    EXPECT_EQ(cache()->_num_read_blocks->get_value(), disk_reads + 1);
+}
+
+TEST_F(AdaptiveCachedRemoteFileReaderTest, 
inflight_payload_still_avoids_remote_reads) {
+    create_cache("adaptive_inflight");
+    auto remote = std::make_shared<CountingFileReader>(open_remote_file());
+    auto reader = external_reader(remote);
+    auto* index = cache()->inflight_write_buffer_index();
+    AsyncCacheWriteBufferPtr payload;
+    ASSERT_TRUE(cache()->async_write_manager()->allocate_tracked_buffer(1_mb, 
&payload).ok());
+    const std::string expected(1_mb, '0');
+    memcpy(payload->data(), expected.data(), expected.size());
+    auto entry = std::make_shared<InflightWriteBufferEntry>(payload, 0, 
expected.size(),
+                                                            MonotonicMicros());
+    ASSERT_EQ(index->insert_if_absent(reader->_cache_hash, 0, entry), nullptr);
+    Defer remove_entry {
+            [&] { static_cast<void>(index->remove_if(reader->_cache_hash, 0, 
entry)); }};
+    seed_slow_disk();
+    IOContext context;
+    context.cache_write_mode_override = CacheWriteMode::ASYNC_WRITE;
+    verify_inflight_hit_without_disk(reader, remote, context, expected);
+}
+
+TEST_F(AdaptiveCachedRemoteFileReaderTest,
+       read_only_inflight_hit_avoids_disk_after_disabling_async) {
+    create_cache("adaptive_read_only_inflight");
+    auto remote = std::make_shared<CountingFileReader>(open_remote_file());
+    auto reader = external_reader(remote);
+    auto* index = cache()->inflight_write_buffer_index();
+    AsyncCacheWriteBufferPtr payload;
+    ASSERT_TRUE(cache()->async_write_manager()->allocate_tracked_buffer(1_mb, 
&payload).ok());
+    const std::string expected(1_mb, '0');
+    memcpy(payload->data(), expected.data(), expected.size());
+    auto entry = std::make_shared<InflightWriteBufferEntry>(payload, 0, 
expected.size(),
+                                                            MonotonicMicros());
+    ASSERT_EQ(index->insert_if_absent(reader->_cache_hash, 0, entry), nullptr);
+    Defer remove_entry {
+            [&] { static_cast<void>(index->remove_if(reader->_cache_hash, 0, 
entry)); }};
+    // Disabling new async writes does not invalidate already accepted 
payloads. A zero query
+    // write budget still selects the memory-first remote-only-on-miss planner 
in this state.
+    config::enable_async_file_cache_write = false;
+    RemoteScanCacheWriteLimiter limiter(TUniqueId(), 0);
+    for (const auto mode : {CacheWriteMode::SYNC_WRITE, 
CacheWriteMode::DEFAULT}) {
+        IOContext context;
+        if (mode == CacheWriteMode::DEFAULT) {
+            context.remote_scan_cache_write_limiter = &limiter;
+            EXPECT_EQ(reader->_resolve_cache_write_mode(&context), 
CacheWriteMode::SYNC_WRITE);
+        } else {
+            context.cache_write_mode_override = mode;
+            context.file_cache_miss_policy = 
FileCacheMissPolicy::REMOTE_ONLY_ON_MISS;
+        }
+        ASSERT_NO_FATAL_FAILURE(
+                verify_inflight_hit_without_disk(reader, remote, context, 
expected));
+    }
+}
+
+TEST_F(AdaptiveCachedRemoteFileReaderTest,
+       read_only_partial_inflight_hit_reads_complete_remote_range) {
+    create_cache("adaptive_read_only_partial_inflight");
+    auto remote = std::make_shared<CountingFileReader>(open_remote_file());
+    auto reader = external_reader(remote);
+    auto* index = cache()->inflight_write_buffer_index();
+    AsyncCacheWriteBufferPtr payload;
+    ASSERT_TRUE(cache()->async_write_manager()->allocate_tracked_buffer(1_mb, 
&payload).ok());
+    memset(payload->data(), '0', 1_mb);
+    auto entry = std::make_shared<InflightWriteBufferEntry>(payload, 0, 1_mb, 
MonotonicMicros());
+    ASSERT_EQ(index->insert_if_absent(reader->_cache_hash, 0, entry), nullptr);
+    Defer remove_entry {
+            [&] { static_cast<void>(index->remove_if(reader->_cache_hash, 0, 
entry)); }};
+    config::enable_async_file_cache_write = false;
+    RemoteScanCacheWriteLimiter limiter(TUniqueId(), 0);
+    FileCacheStatistics stats;
+    IOContext context;
+    context.enable_file_cache_io_adaptor = true;
+    context.remote_scan_cache_write_limiter = &limiter;
+    context.file_cache_stats = &stats;
+    std::string actual(2_mb, '\xff');
+    ReadStatistics partial_stats;
+    EXPECT_FALSE(reader->_try_read_from_inflight_buffers(0, Slice(actual), 
actual.size(), false,
+                                                         partial_stats));
+    EXPECT_EQ(actual, std::string(actual.size(), '\xff'));
+    size_t count = 0;
+    ASSERT_TRUE(reader->read_at(0, Slice(actual), &count, &context).ok());
+    EXPECT_EQ(actual, std::string(1_mb, '0') + std::string(1_mb, '1'));
+    EXPECT_EQ(count, actual.size());
+    const std::array<size_t, 3> remote_read {remote->read_count(), 
remote->last_offset(),
+                                             remote->last_size()};
+    const std::array<size_t, 3> expected_read {1, 0, actual.size()};
+    EXPECT_EQ(remote_read, expected_read);
+    EXPECT_EQ(stats.inflight_write_buffer_index_hit, 1);
+    EXPECT_EQ(stats.inflight_write_buffer_index_miss, 1);
+    EXPECT_EQ(stats.bytes_write_into_cache, 0);
+    EXPECT_EQ(stats.async_cache_write_submitted, 0);
+}
+
+// Opt-in end-to-end cache-path benchmark. Injected service times model a 
congested cache disk;
+// the measured wall times are a controlled local experiment, not a production 
query forecast.
+TEST_F(AdaptiveCachedRemoteFileReaderTest, 
DISABLED_latency_controlled_benchmark) {
+    create_cache("adaptive_latency_benchmark");
+    auto remote = std::make_shared<CountingFileReader>(open_remote_file());
+    auto reader = external_reader(remote);
+    std::string expected(64 * 1024, '\0');
+    size_t count = 0;
+    IOContext context;
+    context.cache_write_mode_override = CacheWriteMode::SYNC_WRITE;
+    ASSERT_TRUE(reader->read_at(0, Slice(expected), &count, &context).ok());
+    remote->delay_us = 1000;
+    auto* sync_point = SyncPoint::get_instance();
+    SyncPoint::CallbackGuard guard;
+    sync_point->set_call_back(
+            "FileBlock::adaptor_benchmark_read",
+            [](auto&&) { 
std::this_thread::sleep_for(std::chrono::microseconds(8000)); }, &guard);
+    sync_point->enable_processing();
+    Defer cleanup {[&] { sync_point->disable_processing(); }};
+    std::vector<int64_t> off_times;
+    std::vector<int64_t> on_times;
+    for (int round = 0; round < 5; ++round) {
+        for (int phase = 0; phase < 2; ++phase) {
+            const bool enabled = (round + phase) % 2 == 1;
+            ASSERT_NO_FATAL_FAILURE(warm_adaptor_with_real_reads(reader, 
remote, expected.size()));
+            context.enable_file_cache_io_adaptor = enabled;
+            FileCacheStatistics stats;
+            context.file_cache_stats = &stats;
+            std::string actual(expected.size(), '\0');
+            const auto start = MonotonicNanos();
+            for (int request = 0; request < 200; ++request) {
+                ASSERT_TRUE(reader->read_at(0, Slice(actual), &count, 
&context).ok());
+                ASSERT_EQ(actual, expected);
+                ASSERT_EQ(count, expected.size());
+            }
+            const auto elapsed = MonotonicNanos() - start;
+            (enabled ? on_times : off_times).push_back(elapsed);
+            std::cout << "IO_ADAPTOR_BENCH round=" << round << " enabled=" << 
enabled
+                      << " requests=200 request_bytes=" << expected.size()
+                      << " local_service_us=8000 remote_service_us=1000 
wall_ns=" << elapsed
+                      << " bypass_count=" << stats.io_adaptor_bypass_count
+                      << " bypass_bytes=" << stats.io_adaptor_bypass_bytes
+                      << " local_probe_count=" << 
stats.io_adaptor_local_probes << std::endl;
+            EXPECT_EQ(stats.bytes_write_into_cache, 0);
+            if (enabled) {
+                EXPECT_GT(stats.io_adaptor_bypass_count, 180);
+            } else {
+                EXPECT_EQ(stats.io_adaptor_bypass_count, 0);
+            }
+        }
+    }
+    std::sort(off_times.begin(), off_times.end());
+    std::sort(on_times.begin(), on_times.end());
+    std::cout << "IO_ADAPTOR_BENCH_MEDIAN off_ns=" << off_times[2] << " 
on_ns=" << on_times[2]
+              << std::endl;
+}
+
+TEST_F(AdaptiveCachedRemoteFileReaderTest, 
DISABLED_fast_local_latency_controlled_benchmark) {
+    create_cache("adaptive_fast_local_benchmark");
+    auto remote = std::make_shared<CountingFileReader>(open_remote_file());
+    auto reader = external_reader(remote);
+    std::string expected(64 * 1024, '\0');
+    size_t count = 0;
+    IOContext context;
+    context.cache_write_mode_override = CacheWriteMode::SYNC_WRITE;
+    ASSERT_TRUE(reader->read_at(0, Slice(expected), &count, &context).ok());
+    remote->delay_us = 8000;
+    auto* sync_point = SyncPoint::get_instance();
+    SyncPoint::CallbackGuard guard;
+    sync_point->set_call_back(
+            "FileBlock::adaptor_benchmark_read",
+            [](auto&&) { 
std::this_thread::sleep_for(std::chrono::microseconds(1000)); }, &guard);
+    sync_point->enable_processing();
+    Defer cleanup {[&] { sync_point->disable_processing(); }};
+    std::vector<int64_t> off_times;
+    std::vector<int64_t> on_times;
+    for (int round = 0; round < 5; ++round) {
+        for (int phase = 0; phase < 2; ++phase) {
+            const bool enabled = (round + phase) % 2 == 1;
+            ASSERT_NO_FATAL_FAILURE(warm_adaptor_with_real_reads(reader, 
remote, expected.size()));
+            context.enable_file_cache_io_adaptor = enabled;
+            FileCacheStatistics stats;
+            context.file_cache_stats = &stats;
+            std::string actual(expected.size(), '\0');
+            const auto previous_reads = remote->read_count();
+            const auto start = MonotonicNanos();
+            for (int request = 0; request < 200; ++request) {
+                ASSERT_TRUE(reader->read_at(0, Slice(actual), &count, 
&context).ok());
+                ASSERT_EQ(actual, expected);
+                ASSERT_EQ(count, expected.size());
+            }
+            const auto elapsed = MonotonicNanos() - start;
+            (enabled ? on_times : off_times).push_back(elapsed);
+            std::cout << "IO_ADAPTOR_FAST_LOCAL_BENCH round=" << round << " 
enabled=" << enabled
+                      << " requests=200 request_bytes=" << expected.size()
+                      << " local_service_us=1000 remote_service_us=8000 
wall_ns=" << elapsed
+                      << " bypass_count=" << stats.io_adaptor_bypass_count << 
std::endl;
+            // Local service stays below 5 ms, so sampling the slower remote 
path cannot
+            // enable bypass and must not add latency to these healthy-cache 
reads.
+            EXPECT_EQ(remote->read_count(), previous_reads);
+            EXPECT_EQ(stats.io_adaptor_bypass_count, 0);
+            EXPECT_EQ(stats.io_adaptor_local_probes, 0);
+            EXPECT_EQ(stats.io_adaptor_remote_probes, 0);
+            EXPECT_EQ(stats.bytes_write_into_cache, 0);
+        }
+    }
+    std::sort(off_times.begin(), off_times.end());
+    std::sort(on_times.begin(), on_times.end());
+    std::cout << "IO_ADAPTOR_FAST_LOCAL_BENCH_MEDIAN off_ns=" << off_times[2]
+              << " on_ns=" << on_times[2] << std::endl;
+}
+
 } // namespace doris::io
diff --git a/be/test/io/cache/file_cache_io_adaptor_test.cpp 
b/be/test/io/cache/file_cache_io_adaptor_test.cpp
new file mode 100644
index 00000000000..f8fc3001a40
--- /dev/null
+++ b/be/test/io/cache/file_cache_io_adaptor_test.cpp
@@ -0,0 +1,435 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+#include "io/cache/file_cache_io_adaptor.h"
+
+#include <gtest/gtest.h>
+
+#include <atomic>
+#include <limits>
+#include <thread>
+#include <utility>
+#include <vector>
+
+namespace doris::io {
+
+class FileCacheIOAdaptorTest : public testing::Test {
+protected:
+    static constexpr size_t READ_SIZE = 4096;
+    void seed(size_t count, int64_t local_us = 20000, int64_t remote_us = 1000,
+              size_t bytes = READ_SIZE) {
+        for (size_t i = 0; i < count; ++i) {
+            adaptor.record_local(bytes, local_us);
+            adaptor.record_remote(bytes, remote_us);
+        }
+    }
+    FileCacheIOAdaptor adaptor;
+};
+
+TEST_F(FileCacheIOAdaptorTest, RequiresFiftyRealSamplesOnBothPaths) {
+    seed(49);
+    EXPECT_FALSE(adaptor._select(READ_SIZE, 1.0, 0).read_remote());
+    adaptor.record_local(READ_SIZE, 20000);
+    EXPECT_FALSE(adaptor._select(READ_SIZE, 1.0, 0).read_remote());
+    adaptor.record_remote(READ_SIZE, 1000);
+    EXPECT_TRUE(adaptor._select(READ_SIZE, 1.0, 0).read_remote());
+}
+
+TEST_F(FileCacheIOAdaptorTest, SmallReadsKeepTheirActualLatency) {
+    seed(50, 100, 1000);
+    const auto decision = adaptor.select(READ_SIZE);
+    EXPECT_EQ(decision.local_latency_us, 100);
+    EXPECT_FALSE(decision.read_remote());
+}
+
+TEST_F(FileCacheIOAdaptorTest, FastLocalNeverReadsRemoteAcrossProbeIntervals) {
+    seed(50, 100, 20000);
+    size_t remote_reads = 0;
+    // At 32 requests/s, every 64th request also satisfies the one-second 
probe limit.
+    // A healthy 100 us cache must not send any of these real reads to the 20 
ms remote path.
+    for (int64_t request = 0; request < 1024; ++request) {
+        const auto decision = adaptor._select(READ_SIZE, 1.0, request * 
31'250);
+        remote_reads += decision.read_remote();
+        if (decision.read_remote()) {
+            adaptor.record_remote(READ_SIZE, 20000);
+        } else {
+            adaptor.record_local(READ_SIZE, 100);
+        }
+        if (decision.is_probe()) {
+            adaptor.finish_probe();
+        }
+    }
+    EXPECT_EQ(remote_reads, 0);
+}
+
+TEST_F(FileCacheIOAdaptorTest, FastLocalBucketsDoNotReserveProbeTurns) {
+    seed(50, 100, 20000);
+    seed(50, 20000, 1000, 1 << 20);
+    std::array<size_t, 2> probes {};
+    // Keep the fast bucket active at every quota boundary. It must neither 
probe remote
+    // storage itself nor reserve the slow bucket's opportunity to discover a 
faster path.
+    for (int64_t request = 0; request < 8 * 64; ++request) {
+        const bool large = request % 64 == 63;
+        const auto decision =
+                adaptor._select(large ? 1 << 20 : READ_SIZE, 1.0, (request / 
64) * 2'000'000);
+        if (decision.is_probe()) {
+            ++probes[large];
+            adaptor.finish_probe();
+        }
+    }
+    EXPECT_EQ(probes[0], 0);
+    EXPECT_EQ(probes[1], 8);
+}
+
+TEST_F(FileCacheIOAdaptorTest, RemoteProbeRespectsFiveMillisecondBoundary) {
+    seed(50, 4999, 20000);
+    size_t probes_below_floor = 0;
+    for (int64_t request = 0; request < 64; ++request) {
+        const auto decision = adaptor._select(READ_SIZE, 1.0, request * 
31'250);
+        probes_below_floor += decision.remote_probe;
+        if (decision.is_probe()) {
+            adaptor.finish_probe();
+        }
+    }
+    EXPECT_EQ(probes_below_floor, 0);
+    // Local observations can reach the floor even without any remote probes 
beforehand.
+    seed(50, 5000, 20000);
+    const auto decision = adaptor._select(READ_SIZE, 1.0, 5'000'000);
+    EXPECT_TRUE(decision.remote_probe);
+    if (decision.is_probe()) {
+        adaptor.finish_probe();
+    }
+}
+
+TEST_F(FileCacheIOAdaptorTest, MixedSizesDoNotShareHistory) {
+    seed(50, 100, 1000);
+    seed(50, 20000, 1000, 1 << 20);
+    EXPECT_FALSE(adaptor.select(4096).read_remote());
+    EXPECT_TRUE(adaptor.select(1 << 20).read_remote());
+    // Large remote misses cannot bootstrap the unrelated small-read remote 
window.
+    FileCacheIOAdaptor other;
+    for (int i = 0; i < 50; ++i) {
+        other.record_local(4096, 20000);
+        other.record_remote(1 << 20, 1000);
+    }
+    EXPECT_EQ(other.select(4096).remote_latency_us, 0);
+    EXPECT_FALSE(other.select(4096).read_remote());
+}
+
+TEST_F(FileCacheIOAdaptorTest, SizeBucketBoundaries) {
+    for (size_t i = 0; i < FileCacheIOAdaptor::SIZE_LIMITS.size(); ++i) {
+        const auto limit = FileCacheIOAdaptor::SIZE_LIMITS[i];
+        EXPECT_EQ(FileCacheIOAdaptor::bucket_index(limit), i);
+        EXPECT_EQ(FileCacheIOAdaptor::bucket_index(limit + 1), i + 1);
+    }
+    
EXPECT_EQ(FileCacheIOAdaptor::bucket_index(std::numeric_limits<size_t>::max()),
+              FileCacheIOAdaptor::BUCKET_COUNT - 1);
+}
+
+TEST_F(FileCacheIOAdaptorTest, FiveMillisecondFloorAndExactBoundary) {
+    seed(50, 4999);
+    EXPECT_FALSE(adaptor.select(READ_SIZE).read_remote());
+    seed(50, 5000);
+    EXPECT_TRUE(adaptor.select(READ_SIZE).read_remote());
+}
+
+TEST_F(FileCacheIOAdaptorTest, 
EqualityPrefersLocalAndFractionalFactorIsPreserved) {
+    seed(50, 8000, 8000);
+    EXPECT_FALSE(adaptor.select(READ_SIZE).read_remote());
+    seed(50, 8000, 10000);
+    EXPECT_FALSE(adaptor.select(READ_SIZE).read_remote());
+    EXPECT_TRUE(adaptor.select(READ_SIZE, 1.5).read_remote());
+    EXPECT_FALSE(adaptor.select(READ_SIZE, 0.5).read_remote());
+}
+
+TEST_F(FileCacheIOAdaptorTest, SlidingWindowReplacesOldSamples) {
+    seed(50);
+    EXPECT_TRUE(adaptor.select(READ_SIZE).read_remote());
+    seed(50, 100, 1000);
+    EXPECT_FALSE(adaptor.select(READ_SIZE).read_remote());
+    EXPECT_EQ(adaptor.select(READ_SIZE).local_latency_us, 100);
+}
+
+TEST_F(FileCacheIOAdaptorTest, 
RevisitLocalWithoutPreviouslyObservedFastSamples) {
+    seed(50);
+    size_t local_probes = 0;
+    for (int64_t i = 0; i < 4096; ++i) {
+        const auto decision = adaptor._select(READ_SIZE, 1.0, i * 2'000'000);
+        local_probes += decision.local_probe;
+        if (decision.read_remote()) {
+            adaptor.record_remote(READ_SIZE, 1000);
+        } else {
+            adaptor.record_local(READ_SIZE, 100);
+        }
+        if (decision.is_probe()) {
+            adaptor.finish_probe();
+        }
+    }
+    EXPECT_GT(local_probes, 0);
+    EXPECT_EQ(adaptor._buckets[0].local.average(), 100);
+    EXPECT_FALSE(adaptor._select(READ_SIZE, 1.0, 0).read_remote());
+}
+
+TEST_F(FileCacheIOAdaptorTest, 
MissingRemoteHistoryIsPopulatedByLimitedRealProbes) {
+    for (int i = 0; i < 50; ++i) {
+        adaptor.record_local(READ_SIZE, 20000);
+    }
+    size_t remote_probes = 0;
+    for (int64_t i = 0; i < 50 * 64; ++i) {
+        const auto decision = adaptor._select(READ_SIZE, 1.0, i * 2'000'000);
+        if (decision.remote_probe) {
+            ++remote_probes;
+            adaptor.record_remote(READ_SIZE, 1000);
+            adaptor.finish_probe();
+        }
+    }
+    EXPECT_EQ(remote_probes, 50);
+    EXPECT_TRUE(adaptor._select(READ_SIZE, 1.0, 0).read_remote());
+}
+
+TEST_F(FileCacheIOAdaptorTest, SelectionNeverCreatesSyntheticSamples) {
+    seed(50);
+    for (int64_t i = 0; i < 1000; ++i) {
+        const auto decision = adaptor._select(READ_SIZE, 1.0, i * 2'000'000);
+        if (decision.is_probe()) {
+            adaptor.finish_probe();
+        }
+    }
+    EXPECT_EQ(adaptor._buckets[0].local.average(), 20000);
+    EXPECT_EQ(adaptor._buckets[0].remote.average(), 1000);
+    EXPECT_EQ(adaptor._buckets[0].local.next, 0);
+    EXPECT_EQ(adaptor._buckets[0].remote.next, 0);
+}
+
+TEST_F(FileCacheIOAdaptorTest, ProbeLimitsSpanAllSizeBuckets) {
+    seed(50);
+    seed(50, 20000, 1000, 1 << 20);
+    for (int i = 0; i < 63; ++i) {
+        EXPECT_FALSE(adaptor._select(READ_SIZE, 1.0, 0).is_probe());
+    }
+    EXPECT_TRUE(adaptor._select(READ_SIZE, 1.0, 0).local_probe);
+    for (int i = 0; i < 128; ++i) {
+        EXPECT_FALSE(adaptor._select(1 << 20, 1.0, 2'000'000).is_probe());
+    }
+    adaptor.finish_probe();
+    EXPECT_FALSE(adaptor._select(1 << 20, 1.0, 999999).is_probe());
+    EXPECT_TRUE(adaptor._select(1 << 20, 1.0, 1'000'000).local_probe);
+    adaptor.finish_probe();
+    for (int i = 0; i < 63; ++i) {
+        EXPECT_FALSE(adaptor._select(READ_SIZE, 1.0, 2'000'000).is_probe());
+    }
+    EXPECT_TRUE(adaptor._select(READ_SIZE, 1.0, 2'000'000).local_probe);
+    adaptor.finish_probe();
+}
+
+TEST_F(FileCacheIOAdaptorTest, MixedSizeRecoveryCannotStarveAtProbeBoundary) {
+    seed(50);
+    seed(50, 20000, 1000, 1 << 20);
+    std::array<size_t, 2> probes {};
+    size_t requests_since_probe = 0;
+    int64_t last_probe_us = -2'000'000;
+    // The large request always lands on the global quota boundary. Both sizes 
must still
+    // discover a recovered disk, rather than letting that request consume 
every probe.
+    for (int64_t request = 0; request < 192 * 64; ++request) {
+        const bool large = request % 64 == 63;
+        const size_t bytes = large ? 1 << 20 : READ_SIZE;
+        const auto now_us = (request / 64) * 2'000'000;
+        const auto decision = adaptor._select(bytes, 1.0, now_us);
+        ++requests_since_probe;
+        if (decision.read_remote()) {
+            adaptor.record_remote(bytes, 1000);
+        } else {
+            adaptor.record_local(bytes, 100);
+        }
+        if (decision.is_probe()) {
+            EXPECT_GE(requests_since_probe, 64);
+            EXPECT_GE(now_us - last_probe_us, 1'000'000);
+            ++probes[large];
+            requests_since_probe = 0;
+            last_probe_us = now_us;
+            adaptor.finish_probe();
+        }
+    }
+    // After crossing below the floor, ordinary local reads finish replacing 
the slow window.
+    EXPECT_GT(probes[0], 0);
+    EXPECT_GT(probes[1], 0);
+    
EXPECT_EQ(adaptor._buckets[FileCacheIOAdaptor::bucket_index(READ_SIZE)].local.average(),
 100);
+    EXPECT_EQ(adaptor._buckets[FileCacheIOAdaptor::bucket_index(1 << 
20)].local.average(), 100);
+    const auto decision = adaptor._select(READ_SIZE, 1.0, 384'000'000);
+    EXPECT_FALSE(decision.read_remote());
+    if (decision.is_probe()) {
+        adaptor.finish_probe();
+    }
+}
+
+TEST_F(FileCacheIOAdaptorTest, AllActiveBucketsShareProbeSlots) {
+    std::array<size_t, FileCacheIOAdaptor::BUCKET_COUNT> probes {};
+    for (size_t bucket = 0; bucket < probes.size(); ++bucket) {
+        seed(50, 20000, 1000, READ_SIZE << (bucket * 2));
+    }
+    for (size_t request = 0; request < probes.size() * 64 * 3; ++request) {
+        const size_t bucket = request % probes.size();
+        const auto decision = adaptor._select(READ_SIZE << (bucket * 2), 1.0, 
request * 2'000'000);
+        if (decision.is_probe()) {
+            ++probes[bucket];
+            adaptor.finish_probe();
+        }
+    }
+    for (const auto count : probes) {
+        EXPECT_GT(count, 0);
+    }
+}
+
+using SparseTraffic = std::pair<size_t, size_t>;
+
+class FileCacheIOAdaptorSparseTrafficTest : public FileCacheIOAdaptorTest,
+                                            public 
testing::WithParamInterface<SparseTraffic> {};
+
+TEST_P(FileCacheIOAdaptorSparseTrafficTest, 
SparseBucketsRecoverDespiteInterveningSmallHits) {
+    const auto [small_requests, large_requests] = GetParam();
+    const auto period = small_requests + large_requests;
+    seed(50, 100, 1000);
+    seed(50, 20000, 1000, 1 << 20);
+    std::array<size_t, 2> probes {};
+    size_t requests_since_probe = 0;
+    int64_t last_probe_us = -2'000'000;
+    // A fixed 64-hit activity window expires the large bucket immediately 
before its
+    // next request. Bursts must not erase the long gap that its pending probe 
must cover.
+    for (size_t request = 0; request < 128 * period; ++request) {
+        const bool large = request % period >= small_requests;
+        const size_t bytes = large ? 1 << 20 : READ_SIZE;
+        const auto now_us = static_cast<int64_t>(request / period) * 2'000'000;
+        const auto decision = adaptor._select(bytes, 1.0, now_us);
+        ++requests_since_probe;
+        if (decision.read_remote()) {
+            adaptor.record_remote(bytes, 1000);
+        } else {
+            adaptor.record_local(bytes, 100);
+        }
+        if (decision.is_probe()) {
+            EXPECT_GE(requests_since_probe, 64);
+            EXPECT_GE(now_us - last_probe_us, 1'000'000);
+            ++probes[large];
+            requests_since_probe = 0;
+            last_probe_us = now_us;
+            adaptor.finish_probe();
+        }
+    }
+    EXPECT_EQ(probes[0], 0);
+    EXPECT_GT(probes[1], 0);
+    const auto decision = adaptor._select(1 << 20, 1.0, 256'000'000);
+    EXPECT_EQ(decision.local_latency_us, 100);
+    EXPECT_FALSE(decision.read_remote());
+    if (decision.is_probe()) {
+        adaptor.finish_probe();
+    }
+}
+
+INSTANTIATE_TEST_SUITE_P(SparseTraffic, FileCacheIOAdaptorSparseTrafficTest,
+                         testing::Values(SparseTraffic {64, 1}, SparseTraffic 
{128, 1},
+                                         SparseTraffic {256, 1}, SparseTraffic 
{1024, 1},
+                                         SparseTraffic {64, 2}, SparseTraffic 
{256, 2}));
+
+TEST_F(FileCacheIOAdaptorTest, SparseBucketStopsReservingAfterItsProbe) {
+    seed(50, 20000, 1000);
+    seed(50, 20000, 1000, 1 << 20);
+    bool large_probed = false;
+    int64_t now_us = 0;
+    // Learn a sparse cadence and grant its probe, then stop sending that size 
entirely.
+    for (size_t request = 0; request < 8 * 257 && !large_probed; ++request) {
+        const bool large = request % 257 == 256;
+        now_us = static_cast<int64_t>(request / 257) * 2'000'000;
+        const auto decision = adaptor._select(large ? 1 << 20 : READ_SIZE, 
1.0, now_us);
+        if (decision.is_probe()) {
+            large_probed = large;
+            adaptor.finish_probe();
+        }
+    }
+    ASSERT_TRUE(large_probed);
+    size_t small_probes = 0;
+    for (int64_t request = 1; request <= 512; ++request) {
+        const auto decision = adaptor._select(READ_SIZE, 1.0, now_us + request 
* 2'000'000);
+        if (decision.is_probe()) {
+            ++small_probes;
+            adaptor.finish_probe();
+        }
+    }
+    EXPECT_GE(small_probes, 6);
+}
+
+TEST_F(FileCacheIOAdaptorTest, InactiveBucketDoesNotBlockRemainingTraffic) {
+    seed(50);
+    seed(50, 20000, 1000, 1 << 20);
+    static_cast<void>(adaptor._select(1 << 20, 1.0, 0));
+    size_t probes = 0;
+    for (int64_t request = 1; request <= 512; ++request) {
+        const auto decision = adaptor._select(READ_SIZE, 1.0, request * 
2'000'000);
+        if (decision.is_probe()) {
+            ++probes;
+            adaptor.finish_probe();
+        }
+    }
+    EXPECT_GE(probes, 6);
+}
+
+TEST_F(FileCacheIOAdaptorTest, NegativeObservationsAreIgnoredAndZeroIsValid) {
+    adaptor.record_local(READ_SIZE, -1);
+    adaptor.record_remote(READ_SIZE, -1);
+    EXPECT_EQ(adaptor._buckets[0].local.count, 0);
+    EXPECT_EQ(adaptor._buckets[0].remote.count, 0);
+    seed(50, 0, 0);
+    EXPECT_EQ(adaptor._buckets[0].local.count, 50);
+    EXPECT_EQ(adaptor._buckets[0].local.average(), 0);
+    EXPECT_FALSE(adaptor.select(READ_SIZE).read_remote());
+}
+
+TEST_F(FileCacheIOAdaptorTest, VeryLargeLatenciesDoNotOverflowWindow) {
+    const auto maximum = std::numeric_limits<int64_t>::max();
+    seed(100, maximum, maximum);
+    EXPECT_EQ(adaptor.select(READ_SIZE).local_latency_us, maximum);
+    EXPECT_EQ(adaptor.select(READ_SIZE).remote_latency_us, maximum);
+    EXPECT_FALSE(adaptor.select(READ_SIZE).read_remote());
+}
+
+TEST_F(FileCacheIOAdaptorTest, 
ConcurrentQueriesShareBoundedHistoryAndOneProbe) {
+    seed(50);
+    std::atomic<int> inflight = 0;
+    std::vector<std::thread> threads;
+    for (int i = 0; i < 8; ++i) {
+        threads.emplace_back([&] {
+            for (int sample = 0; sample < 10000; ++sample) {
+                const auto decision = adaptor.select(READ_SIZE);
+                if (decision.is_probe()) {
+                    EXPECT_EQ(inflight.fetch_add(1), 0);
+                    inflight.fetch_sub(1);
+                    adaptor.finish_probe();
+                }
+                adaptor.record_local(READ_SIZE, 20000);
+                adaptor.record_remote(READ_SIZE, 1000);
+            }
+        });
+    }
+    for (auto& thread : threads) {
+        thread.join();
+    }
+    EXPECT_FALSE(adaptor._probe_inflight);
+    EXPECT_EQ(adaptor._buckets[0].local.count, 50);
+    EXPECT_EQ(adaptor._buckets[0].remote.count, 50);
+    EXPECT_EQ(adaptor._buckets[0].local.average(), 20000);
+}
+
+} // namespace doris::io
diff --git a/fe/fe-core/src/main/java/org/apache/doris/qe/SessionVariable.java 
b/fe/fe-core/src/main/java/org/apache/doris/qe/SessionVariable.java
index ff315d8674f..aa3c7c8102d 100644
--- a/fe/fe-core/src/main/java/org/apache/doris/qe/SessionVariable.java
+++ b/fe/fe-core/src/main/java/org/apache/doris/qe/SessionVariable.java
@@ -535,6 +535,7 @@ public class SessionVariable implements Serializable, 
Writable {
     public static final String ENABLE_SNAPSHOT_POINT_QUERY = 
"enable_snapshot_point_query";
 
     public static final String ENABLE_FILE_CACHE = "enable_file_cache";
+    public static final String ENABLE_FILE_CACHE_IO_ADAPTOR = 
"enable_file_cache_io_adaptor";
 
     public static final String DISABLE_FILE_CACHE = "disable_file_cache";
 
@@ -2480,6 +2481,11 @@ public class SessionVariable implements Serializable, 
Writable {
                     + "The cache is not used when BE config 
enable_file_cache=false."})
     public boolean enableFileCache = true;
 
+    @VariableMgr.VarAttr(name = ENABLE_FILE_CACHE_IO_ADAPTOR, needForward = 
true, description = {
+            "允许外表查询在本地缓存读取较慢时自适应读取远端数据。",
+            "Allow external queries to adaptively read remote data when local 
file-cache reads are slower."})
+    public boolean enableFileCacheIoAdaptor = true;
+
     // Specify base path for file cache, or chose a random path.
     @VariableMgr.VarAttr(name = FILE_CACHE_BASE_PATH, needForward = true, 
description = {
             "指定 block file cache 在 BE 上的存储路径,默认 'random',随机选择 BE 配置的存储路径。",
@@ -5979,6 +5985,7 @@ public class SessionVariable implements Serializable, 
Writable {
         tResult.setSkipDeleteBitmap(skipDeleteBitmap);
 
         tResult.setEnableFileCache(enableFileCache);
+        tResult.setEnableFileCacheIoAdaptor(enableFileCacheIoAdaptor);
 
         tResult.setEnablePageCache(enablePageCache);
 
diff --git 
a/fe/fe-core/src/test/java/org/apache/doris/qe/SessionVariableFileCacheIoAdaptorTest.java
 
b/fe/fe-core/src/test/java/org/apache/doris/qe/SessionVariableFileCacheIoAdaptorTest.java
new file mode 100644
index 00000000000..d7f28ab79de
--- /dev/null
+++ 
b/fe/fe-core/src/test/java/org/apache/doris/qe/SessionVariableFileCacheIoAdaptorTest.java
@@ -0,0 +1,85 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+package org.apache.doris.qe;
+
+import org.apache.doris.analysis.SetType;
+import org.apache.doris.analysis.SetVar;
+import org.apache.doris.analysis.StringLiteral;
+import org.apache.doris.thrift.TQueryOptions;
+
+import org.apache.thrift.protocol.TBinaryProtocol;
+import org.apache.thrift.protocol.TField;
+import org.apache.thrift.protocol.TStruct;
+import org.apache.thrift.protocol.TType;
+import org.apache.thrift.transport.TMemoryBuffer;
+import org.junit.jupiter.api.Assertions;
+import org.junit.jupiter.api.Test;
+
+public class SessionVariableFileCacheIoAdaptorTest {
+    private TQueryOptions readWireBoolean(short fieldId, boolean value) throws 
Exception {
+        TMemoryBuffer buffer = new TMemoryBuffer(64);
+        TBinaryProtocol protocol = new TBinaryProtocol(buffer);
+        protocol.writeStructBegin(new TStruct("TQueryOptions"));
+        protocol.writeFieldBegin(new TField("query_option", TType.BOOL, 
fieldId));
+        protocol.writeBool(value);
+        protocol.writeFieldEnd();
+        protocol.writeFieldStop();
+        protocol.writeStructEnd();
+        TQueryOptions options = new TQueryOptions();
+        options.read(protocol);
+        return options;
+    }
+
+    @Test
+    public void testUnrelatedFieldDoesNotEnableAdaptor() throws Exception {
+        // A boolean from a newer frontend must not silently enable a 
different backend option.
+        Assertions.assertFalse(readWireBoolean((short) 232, 
true).isSetEnableFileCacheIoAdaptor());
+    }
+
+    @Test
+    public void testAdaptorWireFieldPreservesExplicitValues() throws Exception 
{
+        for (boolean enabled : new boolean[] {true, false}) {
+            TQueryOptions options = readWireBoolean((short) 1007, enabled);
+            Assertions.assertTrue(options.isSetEnableFileCacheIoAdaptor());
+            Assertions.assertEquals(enabled, 
options.isEnableFileCacheIoAdaptor());
+        }
+    }
+
+    @Test
+    public void testDefaultIsExplicitlySentToBackend() {
+        TQueryOptions options = new SessionVariable().toThrift();
+        Assertions.assertTrue(options.isSetEnableFileCacheIoAdaptor());
+        Assertions.assertTrue(options.isEnableFileCacheIoAdaptor());
+    }
+
+    @Test
+    public void testSessionOverrideAndForwardingAreIsolated() throws Exception 
{
+        SessionVariable disabled = new SessionVariable();
+        VariableMgr.setVar(disabled, new SetVar(SetType.SESSION,
+                SessionVariable.ENABLE_FILE_CACHE_IO_ADAPTOR, new 
StringLiteral("false")));
+        TQueryOptions options = disabled.toThrift();
+        Assertions.assertTrue(options.isSetEnableFileCacheIoAdaptor());
+        Assertions.assertFalse(options.isEnableFileCacheIoAdaptor());
+        Assertions.assertEquals("false", disabled.getForwardVariables()
+                .get(SessionVariable.ENABLE_FILE_CACHE_IO_ADAPTOR));
+        SessionVariable forwarded = new SessionVariable();
+        forwarded.setForwardedSessionVariables(disabled.getForwardVariables());
+        
Assertions.assertFalse(forwarded.toThrift().isEnableFileCacheIoAdaptor());
+        Assertions.assertTrue(new 
SessionVariable().toThrift().isEnableFileCacheIoAdaptor());
+    }
+}
diff --git a/gensrc/thrift/PaloInternalService.thrift 
b/gensrc/thrift/PaloInternalService.thrift
index e8a529b8795..7f19bb49736 100644
--- a/gensrc/thrift/PaloInternalService.thrift
+++ b/gensrc/thrift/PaloInternalService.thrift
@@ -544,6 +544,9 @@ struct TQueryOptions {
   // reads the data instead.
   // Defaults to false because an old FE never sends this field, and BE 
checked both cases before.
   1006: optional bool force_pushdown_zonemap_minmax = false
+  // Use the cache option range to avoid unrelated query-option IDs allocated 
on other branches.
+  // Explicitly sent by new FEs; an omitted field keeps older-FE queries on 
the local policy.
+  1007: optional bool enable_file_cache_io_adaptor = false;
 }
 
 
diff --git 
a/regression-test/suites/query_p0/virtual_slot_ref/adjust_virtual_slot_nullable.groovy
 
b/regression-test/suites/query_p0/virtual_slot_ref/adjust_virtual_slot_nullable.groovy
index 04273e48403..a7472f4a917 100644
--- 
a/regression-test/suites/query_p0/virtual_slot_ref/adjust_virtual_slot_nullable.groovy
+++ 
b/regression-test/suites/query_p0/virtual_slot_ref/adjust_virtual_slot_nullable.groovy
@@ -20,9 +20,11 @@ suite("adjust_virtual_slot_nullable") {
     def tbl1 = "tbl_adjust_virtual_slot_nullable_1"
     def tbl2 = "tbl_adjust_virtual_slot_nullable_2"
 
+    // Cost-based join commutation changes the recorded shape when cloud 
statistics arrive.
+    // Keep the nullable-slot assertion independent of statistics collection 
timing.
     multi_sql """
         set runtime_filter_mode='OFF';
-        set disable_join_reorder=false;
+        set disable_join_reorder=true;
         SET ignore_shape_nodes='PhysicalDistribute';
         drop table if exists tbl_adjust_virtual_slot_nullable_1 force;
         drop table if exists tbl_adjust_virtual_slot_nullable_2 force;


---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]

Reply via email to